Kalvia AI · Developers
Kalvia API: AI video and image generation for your own code
The app's generators, one HTTPS request away.
The Kalvia API lets scripts, back ends and AI agents start the same image and video generations as the app. Each request runs through the same validation, pricing and credit checks as the Generate button, and every result is saved to your Kalvia library.
It is a JSON API over HTTPS. Create a key, read the model catalogue, start a generation, then check its status and download the file when it is ready.
- Base URL
https://kalvia.ai- Authentication
Authorization: Bearer <API key>- Format
JSON over HTTPS
Quickstart
From a key to a finished video.
Four requests cover the whole job. The examples use curl; any HTTP client works the same way.
Create a key
Sign in, open the Developers page and create a key. Save it as
KALVIA_API_KEYin your environment.Read the model catalogue
Each model lists the resolutions, ratios, durations and modes it accepts, its defaults, and an estimate in credits.
List models curl https://kalvia.ai/api/v1/models \ -H "Authorization: Bearer $KALVIA_API_KEY"Start a generation
The response returns at once with the new generation's
idand statusqueued; the job runs in the background.Start a video curl https://kalvia.ai/api/generations \ -H "Authorization: Bearer $KALVIA_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: fox-in-snow-001" \ -d '{ "prompt": "A red fox walks through fresh snow at dawn, low tracking shot, soft golden light", "settings": { "modelKey": "seedance-2.5", "mode": "t2v", "resolution": "720p", "ratio": "16:9", "durationSec": 5, "audio": true, "format": "mp4", "bitrate": "standard", "seed": null, "watermark": false, "cameraFixed": false }, "refs": [] }'Check it and download
Check every few seconds until the status is
completed, then download the file with the same key.Check status curl https://kalvia.ai/api/generations/GENERATION_ID \ -H "Authorization: Bearer $KALVIA_API_KEY"Download the video curl -L -o shot.mp4 \ "https://kalvia.ai/api/generations/GENERATION_ID/download?format=mp4" \ -H "Authorization: Bearer $KALVIA_API_KEY"
Authentication
API keys.
A key acts as your account for generation work, and nothing else.
- Create keys on the Developers page while signed in. A new key is shown once, so copy it straight away.
- Send the key in the Authorization header of every request: Authorization: Bearer fxgen_…
- You can hold up to 10 active keys, each with its own label. Revoking a key stops it immediately.
- Keys reach only the model catalogue, upload and generation endpoints below. Account settings, billing and key management always require a signed-in session.
- Keep keys on a server or in environment variables. Never put them in browser code, apps you distribute or public repositories.
Reference
Endpoints.
Paths are relative to the base URL. Requests and responses are JSON, except uploads (multipart) and downloads (the file).
Models and prices
| Endpoint | What it does |
|---|---|
GET/api/v1/models | Every enabled video and image model with its resolutions, aspect ratios, duration limits, modes, defaults, prompt limit and estimated credits for one generation. |
GET/api/capacity | What one generation costs on each model and resolution, and how many your current balance covers. |
Generations
| Endpoint | What it does |
|---|---|
POST/api/generations | Start a generation from a prompt, settings and optional references. Send an Idempotency-Key header so a retried request never starts or charges a second job. |
GET/api/generations | List your generations, newest first. Filter with status=active or status=completed, page with limit (up to 500) and offset, and add session=all to include every session. Active jobs carry progress and etaSec. |
GET/api/generations/{id} | One generation: status, prompt, settings, estimated and actual credits, output size and duration, and any error. |
POST/api/generations/{id}/cancel | Cancel a generation that is still queued or running. |
GET/api/generations/{id}/download | Download the finished file. Videos accept format=mp4 or format=mov, and format=png&t=SECONDS for a single frame. |
References
| Endpoint | What it does |
|---|---|
POST/api/uploads | Upload one reference image, video or audio file as multipart form data in a field named file: images and audio up to 100 MB, video up to 500 MB. The response's upload.id goes into a generation's refs. |
POST /api/generations
Starting a generation.
The body has three parts: prompt, settings and refs. Values are checked against the model's catalogue entry, and a request the model cannot take is refused before anything is charged.
| Field | What it takes |
|---|---|
prompt | Required. What to generate. The model's limit is promptCharLimit in the catalogue. |
refs | Required, may be empty. Up to 16 references, each { uploadId, kind, index, role }: kind is image, video or audio, index counts from 1 within its kind, and role is first_frame, last_frame, keyframe or reference. Only your own uploads are accepted. |
settings.kind | video (the default when omitted) or image. |
settings.modelKey | Required. A key from /api/v1/models, for example the keys in the model table below. |
settings.resolution, settings.ratio | Values from the model's resolutions and ratios lists. |
settings.mode | Video. One of the model's mode IDs; see the list below. |
settings.durationSec | Video. Between the model's minDurationSec and maxDurationSec, in steps of durationStepSec. |
settings.audio | Video. Generate sound with the picture, on models where audioSupported is true. |
settings.format, settings.bitrate | Video. mp4 or mov, and standard or high. |
settings.seed, settings.cameraFixed, settings.watermark | Video. A fixed seed or null for a random one, whether to lock the camera, and whether to add a watermark. |
settings.quality | Image. Only for models that list qualities. |
settings.batch | Image. Make 1 to 8 variations in one request; each is its own generation. |
Video modes
t2v- text to video
r2v- video guided by reference images, clips or audio
flf2v- first and last frame
edit- change an existing video with an edit prompt
extend- continue an existing video
multiframes- several keyframes in one shot
longvideo- a longer video built in extension rounds
Each model accepts only the modes in its own modes list, and some modes need references, given in that mode's requires.
Images and references
An image request sets settings.kind to image. To guide a generation with your own media, upload it first and pass its id in refs.
curl https://kalvia.ai/api/generations \
-H "Authorization: Bearer $KALVIA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "Product photo of a matte black water bottle on wet slate, studio light",
"settings": {
"kind": "image",
"modelKey": "seedream-5",
"resolution": "2k",
"ratio": "1:1",
"batch": 2
},
"refs": []
}'curl https://kalvia.ai/api/uploads \
-H "Authorization: Bearer $KALVIA_API_KEY" \
-F "file=@reference.png"The response holds generation (the first record), generations (every record, one per image variation) and issues. Retrying with the same Idempotency-Key returns the original records with replayed: true instead of starting new jobs.
Lifecycle
Status and credits.
Credits are reserved when a job is accepted and settled to its actual cost when it finishes, at the same prices as the app. If your balance cannot cover a job, it is refused with 402 and nothing starts.
queued- Accepted and waiting for a slot. Credits are reserved.
generating- The model is working. The list endpoint adds progress and etaSec.
downloading- Kalvia is fetching and checking the output.
completed- The file is in your library and ready to download.
failed- The job ended with an error, given in the error field.
cancelled- You cancelled the job before it finished.
Errors
When a request fails.
Every error response is JSON with an error message that explains what to change.
| Status | Meaning |
|---|---|
400 | The request is malformed: no prompt, settings or refs, a prompt over 32,000 characters, more than 16 references, or an invalid idempotency key. |
401 | The API key is missing, malformed or revoked. |
402 | Your balance cannot cover the job. Nothing starts. |
403 | A reference is not one of your own uploads. |
404 | The generation does not exist or belongs to another account. |
409 | The idempotency key was already used with different input, or the job can no longer be cancelled. |
413, 415 | The upload is larger than its type allows, or the file type is not supported. |
422 | The model, mode, resolution, ratio or duration is not accepted, or the model is no longer available. No credits are charged. |
429 | Too many requests. Wait the number of seconds in the Retry-After header, then retry. |
503 | The model's engine is not connected right now. No credits are charged. |
Models
Model keys.
Read from Kalvia's model catalogue when this page was built. GET /api/v1/models always returns the current list, limits and prices.
| Model | Key | Takes |
|---|---|---|
| MiniMax H3 | minimax-h3 | Video · t2v, r2v, flf2v · up to 15 s · 768p, 2k |
| MiniMax H3 Max | minimax-h3-max | Video · t2v, flf2v · up to 15 s · 480p, 768p |
| Seedance 2.0 | seedance-2.0 | Video · t2v, r2v, flf2v, edit, extend · up to 15 s · 480p, 720p, 1080p, 4k |
| Seedance 2.5 | seedance-2.5 | Video · t2v, r2v, flf2v, edit, extend, multiframes, longvideo · up to 30 s · 480p, 720p, 1080p |
| Seedance 2.0 Fast | seedance-2.0-fast | Video · t2v, r2v, flf2v, edit, extend · up to 15 s · 480p, 720p |
| Seedance 2.0 Mini | seedance-2.0-mini | Video · t2v, r2v, flf2v, edit, extend · up to 15 s · 480p, 720p |
| Seedance 1.5 Pro | seedance-1.5-pro | Video · t2v, flf2v · up to 12 s · 480p, 720p, 1080p |
| Seedance 1.0 Pro | seedance-1.0-pro | Video · t2v, flf2v · up to 12 s · 480p, 720p, 1080p |
| Seedance 1.0 Pro Fast | seedance-1.0-pro-fast | Video · t2v, flf2v · up to 12 s · 480p, 720p, 1080p |
| MiniMax Image 01 | minimax-image-01-direct | Image · 1k, 2k |
| Seedream 5.0 Pro | seedream-5-pro | Image · 2k, 4k |
| Seedream 5.0 | seedream-5 | Image · 2k, 4k |
| Seedream 4.5 | seedream-4-5 | Image · 2k, 4k |
| Seedream 4.0 | seedream-4 | Image · 1k, 2k, 4k |
Assistants
ChatGPT, Claude and other MCP clients.
To create from a conversation instead of code, connect an assistant to Kalvia's hosted MCP server. You approve the connection with your Kalvia sign-in, and the assistant gets the same generation tools under the same credit controls, without handling an API key.
Coming next
What the API will cover next.
Planned work, not yet available. It ships when it has been tested.
- Canvas, Editor and tool operations
- Reading approved shots from a canvas, applying timeline changes and requesting an export, exposed from the same operation registry as the app.
- Command-line tool
- A kalvia command for generate, status and models in a terminal, using the same API keys.
Questions
Before you build.
Does Kalvia have an API?
Yes. Kalvia has a JSON API over HTTPS for starting image and video generations, checking their status and downloading the results. It authenticates with API keys that you create and revoke on the Developers page.
How much does the Kalvia API cost?
Generations started through the API cost the same credits as in the app and are priced from the same catalogue. GET /api/v1/models returns an estimate for each model, and the reserved amount is settled to the actual cost when the job finishes.
Which models can I call through the API?
Currently MiniMax H3, MiniMax H3 Max, Seedance 2.0, Seedance 2.5, Seedance 2.0 Fast, Seedance 2.0 Mini, Seedance 1.5 Pro, Seedance 1.0 Pro, Seedance 1.0 Pro Fast for video and MiniMax Image 01, Seedream 5.0 Pro, Seedream 5.0, Seedream 4.5, Seedream 4.0 for images. GET /api/v1/models always returns the current list.
Where do generations made through the API appear?
In your Kalvia library, next to the ones you made in the app, so you can open them on a canvas, upscale them or cut them in the editor.
Can I use Kalvia from ChatGPT or Claude instead of writing code?
Yes. Kalvia's hosted MCP server lets ChatGPT, Claude and other MCP clients list models, start generations and check them after you approve the connection.
Get started
Build with Kalvia.
Create a Kalvia account, then make an API key on the Developers page. API generations use the same credits and prices as the app.