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 Content-Type header should be set to multipart/form-data.
• The request body should include the following form fields:
  • image: The image file you want to generate metadata for.
  • data: A JSON object containing the context (optional) and schema (optional) for the metadata generation.
  • language: A string specifying the desired language for the metadata output (optional).

Here's an example request using cURL and JavaScript:

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: multipart/form-data" \
  -F "image=@/path/to/your/image.jpg" \
  -F "data={\"context\":\"Playful kittens among blooming flowers\",\"schema\":{\"title\":\"string\",\"alternativeText\":\"string\",\"caption\":\"string\"}}" \
  -F "language=en" \
  https://forvoyez.com/api/describe

const form = new FormData()
form.append('image', fileInput.files[0])
form.append(
	'data',
	JSON.stringify({
		context: 'Playful kittens among blooming flowers',
		schema: {
			title: 'string',
			alternativeText: 'string',
			caption: 'string',
		},
	})
)
form.append('language', 'en')

fetch('https://forvoyez.com/api/describe', {
	method: 'POST',
	headers: {
		Authorization: 'Bearer YOUR_API_KEY',
	},
	body: form,
})
	.then(response => response.json())
	.then(data => {
		console.log(data)
		// Handle the API response data
	})
	.catch(error => {
		console.error('Error:', error)
		// Handle any errors that occurred during the request
	})

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:

  • data: A JSON object that can include the following properties:
    • context (string): Additional context or description about the image to assist in generating more accurate metadata.
    • schema (object): Specifies the desired output schema for the generated metadata. You can customize the schema based on your requirements.
  • language (string): Specifies the desired language for the metadata output. If not provided, the default is English ('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 (e.g., 400 Bad Request, 401 Unauthorized) and a JSON error response with more details.
• Make sure to catch and handle any errors in your application code to provide a smooth user experience.

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:

{
	"error": {
		"code": 400,
		"message": "Missing required parameter: image"
	}
}

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.