Send a prompt to the Milvey API and get a video file back.

Base URL https://api.milvey.example/v1. A run takes a model, a prompt and a credit cap, and returns a file URL. The API is in private preview, so ids and numbers on this page are samples.

Join the list Read the run reference

Crowned hedgehog on an ornate throne (description; prompt not published)

Quickstart in a terminal

quickstart.sh

# 1. Studio → Settings → API keys. The key is shown once.
export MILVEY_API_KEY="mv_live_…"

# 2. Start a run. max_credits caps what it can cost.
curl https://api.milvey.example/v1/runs \
  -H "Authorization: Bearer $MILVEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"kling-v3","prompt":"Neon market in the rain","max_credits":120}'
# → {"id":"run_8f2a91","status":"queued","credits_held":110,…}

# 3. Poll until status is "succeeded", then download output.url
curl https://api.milvey.example/v1/runs/run_8f2a91 -H "Authorization: Bearer $MILVEY_API_KEY"

Keep the key in $MILVEY_API_KEY on a server. Browser code that holds the key exposes it to anyone who opens dev tools.

POST /v1/runs starts a run

Field	Type	Notes
`model`	string	Model slug, e.g. kling-v3, or auto. auto picks a model under max_credits.
`prompt`	string	Text prompt.
`duration`	integer	Seconds. Allowed values depend on the model.
`resolution`	string	480p, 720p or 1080p, if the model supports it.
`max_credits`	integer	Cap for this run. The request fails with 409 if the estimate is above it.
`webhook_url`	string	Optional. Receives run.succeeded or run.failed.

Statuses: queued, running, succeeded, failed. Poll every 3 to 5 seconds, or pass webhook_url.

response · 201

HTTP/1.1 201 Created

{
  "id": "run_8f2a91",
  "status": "queued",
  "model": "kling-v3",
  "credits_held": 110,
  "estimate": { "min": 110, "max": 110 },
  "poll_url": "/v1/runs/run_8f2a91"
}

response · when done

GET /v1/runs/run_8f2a91

{
  "id": "run_8f2a91",
  "status": "succeeded",
  "output": { "url": "https://cdn.milvey.example/run_8f2a91.mp4", "duration": 5 },
  "credits_charged": 110,
  "route": "kling-primary"
}

Errors and what they cost

run_77c0 · kling-v3 · 5s · 720p502 provider_failed

09:40:02	Hold for kling-v3 (estimate 110 cr)	−110
09:40:31	Kling returned 503 on every route. Rerouted to wan-2.2, the next model under the cap	0
09:41:10	wan-2.2 runs on Milvey GPUs and found no free capacity. It queued, then timed out. It does not fall back to a paid API	0
09:41:10	Hold released. Response 502 provider_failed	+110

Net cost 0 cr. Credits are charged only when a file is delivered. sample

HTTP	Code	Meaning	Charged
400	invalid_input	A field is missing or out of range.	No
401	unauthorized	Key missing, revoked or wrong.	No
402	insufficient_credits	Balance is below the estimate for this run.	No
409	cap_exceeded	Estimate is above your max_credits.	No
422	content_blocked	The provider refused the prompt or input.	No
429	rate_limited	Too many requests. Wait for Retry-After seconds.	No
502	provider_failed	Every route failed, no cheaper model fit under the cap, or an open model could not get GPU capacity.	No
200	succeeded	File delivered.	Yes

The same request in curl, TypeScript and Python

run.sh

curl https://api.milvey.example/v1/runs \
  -H "Authorization: Bearer $MILVEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"kling-v3","prompt":"Neon market in the rain","max_credits":120}'

Rate limits by plan

Plan	Requests	Video runs at a time	Pods	Queue
Starter	10 / minsample	1	1 pod	Standard
Creator	60 / minsample	3	2 pods	Priority GPUs
Studio	300 / minsample	10	Dedicated	Reserved capacity

A 429 response includes a Retry-After header in seconds. Limits are samples while pricing is set. Plan details: pricing.

Webhooks

POST to your webhook_url

POST https://example.com/hooks/milvey
X-Milvey-Signature: t=1762333964,v1=5c1f…

{
  "type": "run.succeeded",
  "id": "evt_41c7",
  "created": "2026-11-05T09:12:44Z",
  "data": { "run_id": "run_8f2a91", "credits_charged": 110 }
}

Events: run.succeeded, run.failed
Reply: Any 2xx status
Retries: With backoff, for up to 24 hours
Duplicates: Each event has a stable id. Store it and skip repeats.
Signature: Check X-Milvey-Signature with your webhook secret before reading the body.

Create a key in Studio and send the curl above.

Questions about the API, or a model you need on it? Join the list and reply to the first email. Requests and responses on this page are samples.

Email when signups open · Unsubscribe any time