Skip to content

New: DeepSeek V4.1 Flash Derisked. In chat and on the API.

See modelsWhat's newReport a bug
Open chat
API reference

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, with null context and output limits and a per-unit pricing. 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.

Model ids, limits, headers and usage

Images

  • Fields: model, prompt (up to 4,000 bytes), size (one the model lists; omitted or auto means its first), n (1 to 4), response_format (b64_json only). quality, background and output_format are accepted for SDK compatibility but do not change the result, except on the fixed-quality models, which refuse any quality but low.
  • n above 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 image fields (as many as the model's max_input_images); masks are not supported.
  • Responses are synchronous and can take up to a few minutes; set your client timeout accordingly.
Shell

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 with first_frame, last_frame, input_reference or reference files) answers 202 with a video object (id, status, model, seconds, resolution, ratio).
  • Poll GET /videos/{id}; when status is completed, download GET /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.
Shell

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 in details.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