Limits and Usage Quotas

Your use of the ForVoyez API is limited by your credit balance, and each request by a few size limits. In this section, we'll discuss the credits included in each subscription, the limits of a single request, how to handle quota overages, and the possibility to purchase additional credit packs.

Request Limits per Subscription

Each API request that generates metadata for one image uses 1 credit. Each subscription plan adds a fixed number of credits to your balance at every payment. Here are the credits included in our subscription plans:

Starter Monthly Plan: 250 credits per month
Starter Annual Plan: 3,000 credits per year (equivalent to 250 per month)
Growth Monthly Plan: 2,500 credits per month
Growth Annual Plan: 30,000 credits per year (equivalent to 2,500 per month)

Unused credits accumulate in your balance: they never expire and are not reset when your subscription renews.

If your credit balance reaches zero, the API will return a 401 error with the body {"error": "Unauthorized, no credit left"}. It's important to monitor your usage and upgrade your subscription plan if needed to avoid interruptions in your service. To read your balance from your code without using a credit, call the /tokens endpoint: its user.credits field is your current balance.

See our pricing plans for more details

Limits of a Single Request

These limits apply to every /describe request, whatever your plan. A request rejected because of one of them does not use a credit.

Image size: at most 10 MB. A larger image gets 413 Payload Too Large with {"error": "Image too large: the maximum is 10 MB"}.
Request body: at most 11 MB in total (the image, the form framing, and the text fields). When the Content-Length header announces a larger body, the API answers 413 before reading the upload.
Image formats: JPEG, PNG, WebP, and GIF, detected from the file content. Other formats, such as AVIF, HEIC, SVG, or TIFF, get 400 Bad Request, Invalid image file.
Image resolution: the API scales every image down to at most 1,000 pixels on its longest side before analysing it, so a larger image does not give a more detailed result.
schema: at most 20 fields, with field names up to 64 characters and descriptions up to 1,000 characters (see Data Schemas). All the fields of one answer must fit in about 1,500 words.
context and keywords: only the first 1,000 characters of each are used. language: only the first 64 characters are used.
Response time: the generation of the metadata is stopped after about 25 seconds, and the request then fails with 500 Internal Server Error. Use a client timeout of at least 30 seconds.

See Error Codes for the exact error messages.

Handling Quota Overages

If you run out of credits, you have a few options to continue using the ForVoyez API:

Wait until your next renewal: Your subscription adds its credits to your balance at each payment, on top of any credits you have left. If you can wait, you can pause your usage or limit your requests to essential operations.
Upgrade your subscription plan: If you consistently run out of credits, consider upgrading from the Starter to the Growth plan, which offers more credits per month. This will give you a larger quota to work with and help you avoid overages.
Purchase additional credit packs: If you need a temporary boost, you can purchase additional credit packs. Credit packs are one-time purchases that add a specific number of credits to your balance.

See your credit balance and usage in the dashboard

Purchasing Additional Credit Packs

If you're already subscribed to a plan and need more credits, you can purchase additional credit packs. Credit packs are available in the following options:

Refill 250: 250 additional credits
Refill 825: 825 additional credits
Refill 2,500: 2,500 additional credits

To purchase a credit pack:

Log in to your ForVoyez account and navigate to the Plans page.
In the "Refill Plans" section, click on the "Refill your credits" button of the pack you want.
Complete the payment process.

The additional credits will be added to your balance as soon as the payment is confirmed, and you can continue using the API without interruption.

Please note that credit packs are non-refundable. Their credits never expire: unused credits stay in your balance and carry over from one billing cycle to the next.

Next Steps

Now that you understand the credit limits, quota overages, and the option to purchase additional credit packs, you can:

Monitor your usage in the dashboard to see your credit balance and which API keys use your credits.
Upgrade your subscription plan if you consistently exceed your quota.
Purchase credit packs for temporary quota boosts.

If you have any questions about limits and usage quotas or need assistance with your subscription, please don't hesitate to reach out to our support team.