API reference
Media API: images and videos
OpenAI-shaped endpoints for image generation and edits and for asynchronous video jobs, billed per image or per clip from the prepaid API balance at the prices in the price list.
- Images
- POST https://api.vani.ai/v1/images/generations · /images/edits
- Videos
- POST https://api.vani.ai/v1/videos · GET /videos · GET /videos/{id}
- Models
- GET https://api.vani.ai/v1/images/models · /videos/models
- Keys
- Prepaid (API platform) keys only
On this pageModels, sizes and prices
Models, sizes and prices
GET /images/models and GET /videos/models list every media model with its sizes or resolutions, modes (generate, edit, text or image to video), input limits, durations and price per image or per second. They are the authoritative list; prices also appear in the public price list.
- The media models are also listed in
GET /models, next to the text models, withnullcontext and output limits and a per-unitpricing. Send their ids to the media endpoints only: the chat endpoints refuse them. - Some models offer one fixed size and quality (listed as
low:1024x1024); a request for another size or quality is refused with 400 instead of being changed silently. - The image you get back has exactly the size you asked for: a provider image of another size is scaled and centre-cropped to it.
Images
- Fields:
model,prompt(up to 4,000 bytes),size(one the model lists; omitted orautomeans its first),n(1 to 4),response_format(b64_jsononly).quality,backgroundandoutput_formatare accepted for SDK compatibility but do not change the result, except on the fixed-quality models, which refuse any quality butlow. nabove 1 runs one provider request per image in parallel; you are charged only for the images returned. When none succeeds, nothing is charged and the provider error is returned.- Edits: multipart
imagefields (as many as the model'smax_input_images); masks are not supported. - Responses are synchronous and can take up to a few minutes; set your client timeout accordingly.
Two images
curl "https://api.vani.ai/v1/images/generations" \
-H "Authorization: Bearer $VANI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"openai/gpt-image-2.5","prompt":"a red cube on a white table","size":"1024x1024","n":2}'Videos
POST /videos(JSON or multipart withfirst_frame,last_frame,input_referenceor reference files) answers 202 with a video object (id,status,model,seconds,resolution,ratio).- Poll
GET /videos/{id}; whenstatusiscompleted, downloadGET /videos/{id}/content(MP4, byte ranges supported). Files are kept for 7 days. GET /videos?limit=&after=&order=lists your jobs, newest first (data,first_id,last_id,has_more).- Send an
Idempotency-Key: repeating the same request with the same key returns the job it created (200,x-vani-idempotent-replay: true) instead of starting a second, paid one. - A failed job releases its reservation; you are charged only for delivered videos.
Create, then poll
curl "https://api.vani.ai/v1/videos" \
-H "Authorization: Bearer $VANI_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"model":"x-ai/grok-imagine-video-1.5","prompt":"waves at sunset","seconds":6,"resolution":"720p"}'
curl "https://api.vani.ai/v1/videos/$VIDEO_ID" -H "Authorization: Bearer $VANI_API_KEY"Good to know
- Plan-billed keys (created in Vani Chat) get 403
api_wallet_key_required; media in Vani Chat uses the plan's allowance instead. - Video requests count toward your tier's concurrent-request limit while they run.
- Errors use Vani's envelope:
{"error": {"code", "message", "details"}}. A refused field is named indetails.param, with its bounds where it has them, for example{"param": "n", "min": 1, "max": 4}or{"param": "size", "allowed": ["1024x1024"]}. A provider failure is a 500.
More reference: OpenAI-compatible API · Anthropic-compatible API · Model ids, limits, headers and usage · Images and PDFs on the API · MCP tools on the API · Web search and web fetch tools · Artifacts API · Responses API: scope and limits · Model changes: webhooks, feeds and the changes API · API overview · Docs and quickstart