Data Schemas

The ForVoyez API allows you to customize the output of the generated metadata by providing a schema in the schema field of the request. In this section, we'll explore the schema structure, how to customize schemas, and how the API handles the schema you send.

JSON Schema Structure

The schema is a flat JSON object. Each key is the name of a field you want in the response, and each value is a short description that tells the AI what to generate for that field. Here's an example of a basic schema:

{
	"title": "A short title for the image",
	"alternativeText": "Alt text for screen readers",
	"caption": "A one-sentence caption"
}

The response contains exactly the keys of your schema, and every value is returned as a string:

{
	"title": "Playful Kittens",
	"alternativeText": "Two kittens playing with a ball of yarn",
	"caption": "Adorable kittens having fun and being mischievous"
}

If you don't send a schema, the API uses its default schema, which returns the title, alternativeText, and caption fields. Without a schema field, the response also has alt_text, a copy of alternativeText kept for older versions of the WordPress plugin.

Customizing Schemas

You can customize the schema to match your specific requirements: rename the fields, add your own fields, or keep only the ones you need. Here's an example of a customized schema:

{
	"title": "A product title under 60 characters",
	"alternativeText": "Alt text for screen readers, under 125 characters",
	"seoDescription": "A meta description of about 150 characters",
	"tags": "Five comma-separated keywords describing the image"
}

In this customized schema:

• The title and alternativeText fields have descriptions that set a length target.
• A custom field named seoDescription is added.
• The tags field asks for a comma-separated list, returned as a single string.

Keep the following rules in mind:

• The schema must be a flat object: nested objects and arrays are not supported.
• Values are descriptions, not types: "type", "required", "items" or "default" settings are not interpreted.
• Every value in the response is a string. To get a list, ask for a comma-separated list in the description (as with tags above) and split it in your code.
• Every key of the schema is present in the response, and keys that are not in the schema are never returned.

To use a customized schema in your API request, send it as a JSON string in the schema field, next to the other form fields. Here are examples using cURL and JavaScript (Node.js 20 or later, run on your server with your API key in the FORVOYEZ_API_KEY environment variable):

curl -X POST \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "image=@/path/to/your/image.jpg" \
-F "schema={\"title\":\"A product title under 60 characters\",\"alternativeText\":\"Alt text for screen readers, under 125 characters\",\"seoDescription\":\"A meta description of about 150 characters\",\"tags\":\"Five comma-separated keywords describing the image\"}" \
-F "language=en" \
https://forvoyez.com/api/describe

The response for this schema looks like this:

{
	"title": "Kittens Playing with Yarn",
	"alternativeText": "Two tabby kittens playing with a red ball of yarn on a wooden floor",
	"seoDescription": "Two playful tabby kittens tumble over a red ball of yarn on a sunny wooden floor.",
	"tags": "kittens, yarn, playful, tabby, pets"
}

Schema Validation

The API reads the schema field as a JSON string and keeps only its keys and their descriptions. Make sure your schema is a valid JSON object before sending it:

• If the schema field is missing, empty, or is not a valid JSON object, the API uses the default schema (title, alternativeText, caption).
• Use plain strings for the descriptions: other values (numbers, objects, arrays) are not interpreted as types or structures.
• A schema can have at most 20 fields. Field names can be up to 64 characters and descriptions up to 1,000 characters, and __proto__ is not allowed as a field name.

A schema over these limits is rejected with 400 Bad Request and no credit is used. The error field of the JSON response names the limit:

{
	"error": "Invalid schema: at most 20 fields are allowed"
}

All the fields of one answer must also fit in about 1,500 words. A schema that asks for more, for example many fields that each ask for several paragraphs, is rejected with 400 Bad Request and no credit is used:

{
	"error": "Invalid schema: the requested fields need a longer answer than the API can return (about 1,500 words for all fields together), ask for fewer or shorter fields"
}

Test your schema in the API Playground before using it in production.

If you have any questions or need further assistance with data schemas, feel free to reach out to our support team.