Using the API

To effectively integrate the ForVoyez API into your application, it's essential to understand the request format, the required and optional parameters, and how to handle errors and responses. In this section, we'll cover these topics in detail.

Request Format

When making requests to the ForVoyez API, you'll need to send a POST request to the /describe endpoint with the following format:

• The Authorization header should include your API key as a Bearer token.
• The request body must be multipart/form-data. Let your HTTP client set the Content-Type header, which includes the form boundary: do not set it yourself.
• The request body should include the following form fields:
  • image: The image file you want to generate metadata for (required)
  • schema: A JSON string mapping each output field to a description (optional)
  • keywords: Comma-separated keywords to help with image analysis (optional)
  • context: Additional context about the image (optional)
  • language: Desired language for the output (optional, defaults to 'en')

Send your requests from your server, never from a web page: an API key in browser code can be read and used by anyone (see Authentication). To analyse images that your visitors upload, send them to your server first and call the ForVoyez API from there.

Here's an example request using cURL and JavaScript (Node.js 20 or later, saved as a .mjs file, 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 short title for the image\",\"alternativeText\":\"Alt text for screen readers\",\"caption\":\"A one-sentence caption\"}" \
  -F "keywords=playful,kittens,flowers" \
  -F "context=Playful kittens among blooming flowers" \
  -F "language=en" \
  https://forvoyez.com/api/describe

// Server-side only (Node.js 20 or later): never put your API key in browser
// code. The key is read from the FORVOYEZ_API_KEY environment variable.
import { readFile } from 'node:fs/promises'

const image = new Blob([await readFile('/path/to/your/image.jpg')])

const form = new FormData()
form.append('image', image, 'image.jpg')
form.append(
	'schema',
	JSON.stringify({
		title: 'A short title for the image',
		alternativeText: 'Alt text for screen readers',
		caption: 'A one-sentence caption',
	})
)
form.append('keywords', 'playful,kittens,flowers')
form.append('context', 'Playful kittens among blooming flowers')
form.append('language', 'en')

const response = await fetch('https://forvoyez.com/api/describe', {
	method: 'POST',
	headers: {
		Authorization: `Bearer ${process.env.FORVOYEZ_API_KEY}`,
	},
	body: form,
})
const data = await response.json()

if (!response.ok) {
	// Error bodies are {"error": "<message>"}: see the Error Codes page
	throw new Error(`ForVoyez API error ${response.status}: ${data.error}`)
}

console.log(data)

Required and Optional Parameters

When making a request to the ForVoyez API, there are both required and optional parameters you can include:

• Required parameters:

  • image: The image file for which you want to generate metadata. This should be included as a file in the multipart/form-data request body.

• Optional parameters:

  • schema: A JSON string with a flat object that maps each output field to a description of what to generate; every field is returned as a string (e.g., {"title":"A short title for the image","alternativeText":"Alt text for screen readers"})
  • keywords: A comma-separated list of keywords to help guide the image analysis
  • context: Additional context or description about the image to assist in generating more accurate metadata
  • language: Specifies the desired language for the metadata output (defaults to 'en')

If you don't provide the optional parameters, the API will use default values for metadata generation.

Error Handling and Responses

When making requests to the ForVoyez API, it's important to handle errors gracefully and understand the structure of the API responses. Here are a few things to keep in mind:

• Successful requests will return a 200 OK status code along with a JSON response containing the generated metadata.
• If there's an error with your request, such as missing required parameters or an invalid API key, the API will return an appropriate HTTP status code (400 Bad Request, 401 Unauthorized, 413 Payload Too Large, or 500 Internal Server Error) and a JSON error response whose error field gives more details. A request that fails never uses a credit.
• Make sure to catch and handle any errors in your application code to provide a smooth user experience. See Error Codes for every message.
• To check your API key or your credit balance without using a credit, send a GET request to /tokens.

Here's an example of a successful API response:

{
	"title": "Playful Kittens Among Blooming Flowers",
	"alternativeText": "Two animated kittens playing among blooming flowers with a clear blue sky",
	"caption": "Adorable kittens having fun in a field of vibrant blossoms under the clear blue sky"
}

And here's an example of an error response (400 Bad Request, sent when the image field is missing):

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

Next Steps

Now that you know how to make requests to the ForVoyez API, handle errors, and interpret the responses, you can explore further:

• Data Schemas: Learn how to customize and validate the metadata output schema.
• Limits and Quotas: Understand the request limits and how to handle quota overages.
• Code Examples: See code snippets in different programming languages to help you get started.

If you encounter any issues or have questions about using the API, don't hesitate to reach out to our support team for assistance.