Documentation

Create video

POST/v1/videos

Starts an asynchronous video generation task. Poll its status, then download the result.

Start

Help

Python Setup

Node.js Setup

PHP Setup

API Reference

Request

Content-Type

application/json or multipart/form-data

model

required — a video model id that lists POST /v1/videos in the catalog

prompt

required by most models

input_reference

optional (multipart) — one reference image file, up to 32MB

size / seconds / …

forwarded unchanged

Steps

POST /v1/videos returns a task object with an id and status.
GET /v1/videos/{id} returns the current status (free).
When the task is completed, GET /v1/videos/{id}/content streams the video (free; only the variant query parameter is forwarded).

cURL example

terminal

curl https://apily.pro/v1/videos \
  -H "Authorization: Bearer apily_your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"model":"<video-model-id>","prompt":"a paper boat on a river"}'

curl https://apily.pro/v1/videos/<video-id> \
  -H "Authorization: Bearer apily_your-api-key"

curl https://apily.pro/v1/videos/<video-id>/content \
  -H "Authorization: Bearer apily_your-api-key" \
  --output video.mp4

Error responses

Symptom	Cause	Fix
`404 Video not found`	The id was not created with an API key of your account.	Use the `id` returned by your own `POST /v1/videos`.
`503 Video provider unavailable`	The provider that accepted the task is no longer configured.	Contact support with the video id.
`401 Missing API key`	No auth header was sent.	Apily accepts `Authorization: Bearer …` and `x-api-key: …`.
`401 Invalid API key`	Key copied with stray spaces, truncated, or revoked.	Copy the key whole from the API page in your Apily account, the `apily_` prefix included.
`403 Email not verified`	Your Apily account's email address isn't verified yet.	Verify your email from the banner in the Apily app, then retry.
`404 Model not found`	The model ID isn't in the Apily catalog.	Copy the exact ID from `GET /v1/models` or the Models page in your account.
`503 Model temporarily unavailable`	The model exists, but no upstream provider is reachable right now.	Retry in a moment — it usually recovers within a minute. Switch models if it keeps happening.
`402 Insufficient balance`	Your token balance can't cover the request's estimated cost.	Top up your balance on the Billing page in your Apily account.
`429 Too many requests`	Your account sent more than 600 `/v1/*` requests in a minute — all of your API keys share one budget. The body is `{ error: { message, type: "rate_limit_error", code: "rate_limit_exceeded" }, retryAfterSeconds }`.	Wait the `Retry-After` header (or `retryAfterSeconds`) before retrying, and lower request concurrency.
`502 Upstream error`	The upstream provider returned an unexpected error.	Retry the request; try a different model if it persists.

The model price is charged when the task is accepted. If the task later fails, the charge is returned the first time you request its status. Status and content requests are free.