/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 (required): The content type of the request body. It should be set to 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. Supported image formats are JPEG, JPG, PNG, WebP, and GIF.
• schema (optional): A JSON string specifying the desired output format of the generated metadata.
• keywords (optional): A comma-separated list of keywords to assist in generating more accurate metadata.
• context (optional): Additional context or description to assist in generating more accurate metadata.
• language (optional): A string specifying the desired language for the metadata output. If not provided, the default is English ('en').

Example Request

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: multipart/form-data" \
  -F "image=@/path/to/your/image.jpg" \
  -F "schema={\"title\":\"string\",\"alternativeText\":\"string\",\"caption\":\"string\"}" \
  -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 JSON object containing the generated metadata for the provided image in the specified language.

{
	"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 will return an appropriate HTTP status code along with an error message in the response body. Here are the possible error responses:

• 400 Bad Request

  • 400 No file uploaded: The image parameter is missing in the request.
  • 400 Invalid image file: The uploaded file is not a valid image format.
  • 400 Invalid schema: The provided schema is invalid or malformed.
  • 400 Invalid language: The provided language code is not supported.

• 401 Unauthorized

  • 401 Unauthorized, missing Authorization header: The Authorization header is missing in the request.
  • 401 Unauthorized, invalid token: The provided API key or token is invalid.
  • 401 Unauthorized, no credit left: The user has insufficient credits to make the request.

• 429 Too Many Requests: The request limit for your subscription plan has been exceeded.

• 500 Internal Server Error: An unexpected error occurred on the server side.

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 obtain your API key from the Dashboard.

Rate Limiting

The /describe endpoint is subject to rate limiting to ensure fair usage and maintain the stability of the API. The rate limits are determined by your subscription plan.

If you exceed the rate limit, you will receive a 429 Too Many Requests error response. Upgrade your subscription plan or wait for the rate limit to reset before making further requests.

Schemas

You can customize the output format of the generated metadata by providing a JSON schema in the schema parameter of the request. The schema should specify the desired structure of the metadata.

Here's an example schema:

{
	"title": "string",
	"alternativeText": "string",
	"caption": "string",
	"tags": ["string"],
	"categories": ["string"]
}

If no schema is provided, the API will use a default schema to generate the metadata.

Examples

Here are a few examples of how to use the /describe endpoint with different programming languages:

curl -X POST \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: multipart/form-data" \
-F "image=@/path/to/your/image.jpg" \
-F "schema={\"title\":\"string\",\"alternativeText\":\"string\",\"caption\":\"string\"}" \
-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.