ForVoyezlogo ForVoyez

/describe Endpoint

The /describe endpoint allows you to generate metadata for your images using the ForVoyez API. By sending a POST request to this endpoint with an image file and optional parameters, you can obtain a title, alternative text, and caption for the image in your desired language.

Request

Endpoint

POST https://forvoyez.com/api/describe

Headers

  • Authorization (required): The authentication token (API key) to authorize the request. The token should be prefixed with Bearer .
  • Content-Type: multipart/form-data with a boundary. Your HTTP client sets this header for you when you send a form (cURL -F, FormData in JavaScript, files= in Python requests): do not set it yourself, or the boundary is lost and the API answers 400 Bad Request, the body must be multipart/form-data.

Request Body

The request body should be in multipart/form-data format and include the following fields:

  • image (required): The image file for which you want to generate metadata, up to 10 MB. Supported image formats are JPEG, PNG, WebP, and GIF. The API detects the format from the file content, so the file name and the content type of the form part do not matter (a part sent as application/octet-stream works).
  • schema (optional): A JSON string with a flat object that maps each output field to a short description of what to generate, with at most 20 fields. See Schemas below.
  • keywords (optional): A comma-separated list of keywords to assist in generating more accurate metadata. Only the first 1,000 characters are used.
  • context (optional): Additional context or description to assist in generating more accurate metadata. Only the first 1,000 characters are used.
  • language (optional): The language of the metadata output, as a language code (en, fr, it, pt-BR, zh-TW...) or a language name (French, Brazilian Portuguese...), up to 64 characters. If not provided, the default is English (en).

Example Request

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "image=@/path/to/your/image.jpg" \
  -F "schema={\"title\":\"A short title for the image\",\"alternativeText\":\"Alt text for screen readers\",\"caption\":\"A one-sentence caption\"}" \
  -F "keywords=playful,kittens" \
  -F "context=Playful kittens" \
  -F "language=fr" \
  https://forvoyez.com/api/describe

Response

Success Response

If the request is successful, the API will return a 200 OK status and a flat JSON object containing the generated metadata for the provided image in the specified language. The object has exactly the keys of your schema (or title, alternativeText, and caption when no schema is sent), and every value is a string. When the request has no schema field, the object also has alt_text, a copy of alternativeText kept for older versions of the WordPress plugin.

{
	"title": "Chatons joueurs",
	"alternativeText": "Deux chatons jouant avec une pelote de laine",
	"caption": "Adorables chatons s'amusant et faisant des bêtises"
}

Error Responses

If the request is unsuccessful, the API returns the HTTP status code of the error and a JSON body (Content-Type: application/json) whose error field contains a human-readable message:

{
	"error": "Unauthorized, no credit left"
}

The API checks the request in this order, and answers with the first error it finds: the Authorization header and the API key (401), your credit balance (401), the size of the request body (413), the form and its image field (400), the schema (400), the image itself (400, 413, or 500), and finally the generation (500, or 400 when the answer would be too long). A request with an invalid API key therefore gets a 401 even when its image is too large or missing.

Here are the possible error responses, with an example body for each:

  • 400 Bad Request

    • Bad Request, the body must be multipart/form-data: The request body is not a multipart/form-data form, or its Content-Type header was set by hand without the boundary.
      • Body: {"error": "Bad Request, the body must be multipart/form-data"}
    • Bad Request, No file uploaded: The image field is missing in the request.
      • Body: {"error": "Bad Request, No file uploaded"}
    • Bad Request, Invalid image file: The uploaded file is not a JPEG, PNG, WebP, or GIF image. The format is detected from the file content, so a renamed file of another type gets this error.
      • Body: {"error": "Bad Request, Invalid image file"}
    • Invalid schema: ...: The schema is over the schema limits: more than 20 fields, a field name longer than 64 characters, a description longer than 1,000 characters, or a field named __proto__. The rest of the message names the limit.
      • Body: {"error": "Invalid schema: at most 20 fields are allowed"}
    • Invalid schema: the requested fields need a longer answer than the API can return ...: The schema asks for more text than one answer can hold (about 1,500 words for all fields together).
      • Body: {"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"}

  • 401 Unauthorized

    • Unauthorized, missing Authorization header: The Authorization header is missing in the request, or it does not start with Bearer .
      • Body: {"error": "Unauthorized, missing Authorization header"}
    • Unauthorized, invalid token: The provided API key is invalid, has expired, or has been deleted from the dashboard.
      • Body: {"error": "Unauthorized, invalid token"}
    • Unauthorized, no credit left: Your credit balance is empty.
      • Body: {"error": "Unauthorized, no credit left"}

  • 413 Payload Too Large: The image is over 10 MB, or the request body is over 11 MB. When the Content-Length header announces a body over 11 MB, the API answers before reading the upload.

    • Body: {"error": "Image too large: the maximum is 10 MB"}

  • 500 Internal Server Error: The metadata could not be generated (for example, the AI model failed or did not answer in time) or another unexpected error occurred. No credit is used, so you can retry the request.

    • Body: {"error": "Internal Server Error"}
    • A JPEG, PNG, WebP, or GIF file that cannot be decoded (truncated or corrupt) also gets 500, with a message that starts with Image processing failed: and gives the cause.

For more details on error codes and messages, refer to the Error Codes documentation.

Authentication

To use the /describe endpoint, you need to include a valid API key in the Authorization header of your request. The API key should be prefixed with Bearer .

If you don't have an API key yet, sign up for a ForVoyez account and create one on the API Keys page of your dashboard. Send your requests from your server: an API key in browser code can be read and used by anyone (see Authentication). To check a key or read your credit balance without using a credit, call /tokens.

Credits

Each successful request to the /describe endpoint uses 1 credit from your balance. A request that fails does not use any credit, whatever the error, including a 500 when the metadata could not be generated. When your balance is empty, the API returns 401 Unauthorized with the message Unauthorized, no credit left.

See Limits and Quotas to learn how credits are added to your balance.

Schemas

You can customize the output fields of the generated metadata by providing a schema in the schema field of the request. The schema is a flat JSON object: each key is an output field and each value describes what to generate for it. Nested objects and arrays are not supported, and every value in the response is a string.

Here's an example schema:

{
	"title": "A short title for the image",
	"alternativeText": "Alt text for screen readers",
	"caption": "A one-sentence caption",
	"tags": "Five comma-separated keywords describing the image"
}

If no schema is provided, the API will use a default schema that returns title, alternativeText, and caption. A schema can have at most 20 fields, with field names up to 64 characters and descriptions up to 1,000 characters; a larger schema is rejected with 400 Bad Request. All fields together must also fit in one answer of about 1,500 words: a schema that asks for more is rejected with 400 Bad Request and no credit is used. See Data Schemas for more details.

Examples

Here are a few examples of how to use the /describe endpoint with different programming languages. Run them on your server: the JavaScript example is for Node.js 20 or later (save it as a .mjs file) and reads your API key from 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 short title for the image\",\"alternativeText\":\"Alt text for screen readers\",\"caption\":\"A one-sentence caption\"}" \
-F "keywords=playful,kittens" \
-F "context=Playful kittens" \
-F "language=fr" \
https://forvoyez.com/api/describe

For more code examples and detailed usage instructions, refer to the API Documentation.