ForVoyezlogo ForVoyez

API Documentation

This section provides a comprehensive reference for the ForVoyez API. You'll find detailed information about the available endpoints, request parameters, response formats, error codes, and error messages. Use this documentation as a guide while integrating the ForVoyez API into your application.

Complete Reference of Endpoints

The ForVoyez API offers the following endpoints, both under https://forvoyez.com/api/:

  • POST /describe: Generate metadata for an image. Each successful request uses 1 credit.
  • GET /tokens: Check an API key and read the credit balance of its account. It uses no credit; the WordPress plugin calls it to check your key and show your remaining credits.

Both endpoints authenticate with your API key in the Authorization: Bearer YOUR_API_KEY header. Call them from your server, never from browser code: see Authentication.

For detailed information about each endpoint, including the required parameters, request examples, and response formats, refer to the individual endpoint documentation:

/describe

/tokens

Details of Parameters and Responses

The /describe endpoint takes its parameters as form fields in a multipart/form-data request. The /tokens endpoint takes no parameters: the API key in the Authorization header is enough.

The API responses are returned in JSON format and contain the requested data or relevant error information. The response format varies based on the endpoint and the success or failure of the request.

Here's an example of a request and response for the /describe endpoint:

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=en" \
https://forvoyez.com/api/describe

The available parameters for the /describe endpoint are:

  • image: The image file (required)
  • schema: JSON string with a flat object mapping each output field to a description (optional, see Data Schemas)
  • keywords: Comma-separated list of keywords (optional)
  • context: Additional context about the image (optional)
  • language: Desired language for the output (optional, defaults to 'en')

For more details on the parameters and responses for each endpoint, refer to the individual endpoint documentation.

Error Codes and Error Messages

If a request to the ForVoyez API fails, you'll receive an appropriate HTTP status code along with a JSON error body. Its error field provides more information about the cause of the error and helps you troubleshoot the issue.

The API checks the API key and your credit balance before it reads the request body: a request with an invalid key gets a 401 even when its image is too large or missing.

Here are the error codes of the /describe endpoint:

  • 400 Bad Request: The request is invalid or missing required parameters.

  • 400 Bad Request, the body must be multipart/form-data: The request body is not a multipart/form-data form (let your HTTP client set the Content-Type header).

  • 400 Bad Request, No file uploaded: The image parameter is missing in the request.

  • 400 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).

  • 400 Invalid schema: ...: The schema has more than 20 fields, a field name longer than 64 characters, a description longer than 1,000 characters, or a field named __proto__ (see Data Schemas), or it asks for a longer answer than the API can return (about 1,500 words for all fields together).

  • 401 Unauthorized: Authentication failed.

  • 401 Unauthorized, missing Authorization header: The Authorization header is missing in the request.

  • 401 Unauthorized, invalid token: The provided API key is invalid, has expired, or has been deleted from the dashboard.

  • 401 Unauthorized, no credit left: The user has insufficient credits to make the request.

  • 413 Image too large: the maximum is 10 MB: The image is over 10 MB, or the request body is over 11 MB. A body announced as larger than 11 MB by its Content-Length header is refused before it is read.

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

  • 500 Image processing failed: ...: The image is a supported format but could not be decoded (truncated or corrupt file).

The error response is sent with Content-Type: application/json and an error field with more details. For example, a request without an image returns 400 Bad Request with this body:

{
	"error": "Bad Request, No file uploaded"
}

The /tokens endpoint has its own messages: 401 with Missing or invalid authentication token, Invalid or expired token, or Unauthorized, invalid token, 400 Malformed token: missing userId, 404 User not found, and 500 Server error. See /tokens.

For a complete list of error codes and their meanings, refer to the Error Codes documentation.

Contact support for assistance with error resolution

Next Steps

Now that you have a good understanding of the API documentation, you can:

  • Start making requests with the simplified parameter structure
  • Use keywords to improve image analysis accuracy
  • Customize the output format using the schema parameter
  • Handle error codes and messages gracefully in your application
  • If you encounter any issues or have questions, reach out to our support team for assistance.

Happy coding with the ForVoyez API!