Skip to main content
POST
Estimate the credit cost of a video generation

Authorizations

​
X-Api-Key
string
header
required

Your team API key (starts with al_live_).

Headers

​
Aurous-Version
string

Optional API version pin (YYYY-MM-DD). Omit the header to receive the platform default, currently 2026-08-26.

Pattern: ^\d{4}-\d{2}-\d{2}$
Example:

"2026-08-26"

Body

application/json
​
prompt
string

Text prompt describing the video. Optional when the request carries another content source: a first_frame_url (image-to-video), a reference_video_url (reference-to-video), or a pinned video_lora_id (the video model supplies the motion and, when nothing else is sent, generates its own subject). Subject-driven generation (subjects[], character_id, or reference_image_urls) still requires a prompt describing the action unless a video model is pinned or a reference video is attached. A request with none of the four sources returns 400 missing_field.

Example:

"A golden sunset over the ocean with gentle waves"

​
video_lora_id
string | null

Optional, and TRI-STATE. An id (or slug, where one is set) from GET /v1/video_loras pins a specific video model. A pinned model is also a complete request on its own: send just video_lora_id — no prompt — and the model generates its own subject and motion; add subjects[] (or the legacy character_id/reference_image_urls) to cast specific people, still with no prompt required. Only a pinned id substitutes for a prompt — null never does, and an empty string is treated as omitted. A pin cannot combine with reference_video_url (400 parameter_invalid_combination): both supply the motion. If OMITTED, the platform picks a suitable model for you: matching reads your prompt, or — when first_frame_url is attached — what the IMAGE shows. If none matches, your request is generated as plain video, plain image-to-video, or (with a subject attached) a subject-driven video; matching never fails the request. Send NULL to opt out of IMAGE-based matching — meaningful only when first_frame_url is attached, where it guarantees plain image-to-video. WITHOUT a first frame, null behaves exactly like omitting the field and your prompt is still auto-matched; pin an id if you need a specific model. A first frame plus a pinned or matched model reports inference_type: "r2v" and starts NEAR your image rather than exactly on it. PRICING: a pinned or matched model also supplies default_resolution and default_ratio alongside default_duration for whatever you left out (anything you send explicitly wins), and all three are priced — so null on an otherwise-bare first-frame request falls back to adaptive duration at 1080p and costs ~2.8x the same still with a model pinned. Send duration and resolution alongside null if you want the exact-frame guarantee at a predictable price.

Example:

"action_01HXMQ7Z3K8Y2VNABCDEFGHJKM"

​
character_id
string
deprecated

Drive the video from a saved character (reference-to-video). Must be status: ready — otherwise 400 character_not_ready. Cross-team ids 404 (existence never leaked). Mutually exclusive with reference_image_urls (→ 400 mutually_exclusive_input) and with first_frame_url/last_frame_url (→ 400 parameter_invalid_combination). Omit both a subject and a frame for plain text-to-video. Superseded by subjects[] (which also supports multi-person casts); fully supported — successful responses carry an advisory Deprecation: true header when this field is used.

Example:

"char_01HXMQ7Z3K8Y2VNABCDEFGHJKM"

​
reference_image_urls
string[]
deprecated

Up to 6 subject reference images — each a file_<ulid> (POST /v1/files) or an https:// URL (SSRF-pinned server-side fetch). Image files only: a file_<ulid> uploaded with purpose reference_video/reference_audio is rejected (400 invalid_format). The subject is anchored across the video. Mutually exclusive with character_id and with first_frame_url/last_frame_url. Superseded by subjects[] (which also supports multi-person casts); fully supported — successful responses carry an advisory Deprecation: true header when this field is used.

Maximum array length: 6
Example:
​
subjects
object[]

Ordered cast for a multi-person video. Up to 2 subjects per generation (current engine limit — may increase; exceeding it returns 400 parameter_invalid_combination). Each subject is a saved character or its own group of 1–4 reference images; character and reference subjects can be mixed. Supersedes the single-subject character_id/reference_image_urls fields — sending both shapes returns 400 mutually_exclusive_input. A cast may accompany reference_video_url (the clip supplies motion, the cast supplies identity) but not video_task: "extend" and not first_frame_url/last_frame_url. Duplicate characters or a reference image reused across subjects return 400. Empty array is treated as omitted.

Maximum array length: 2
​
first_frame_url
string

First frame for image-to-video / first+last frame interpolation. Either an opaque file_<ulid> ID returned by POST /v1/files, or an https:// URL pointing at a public host (max 2048 chars). Image files only — a file_<ulid> uploaded with purpose reference_video/reference_audio is rejected (400 invalid_format). URLs are server-side fetched through an SSRF-pinned client (rejects private IPs / cloud metadata). MINIMUM SIZE — when a video model is pinned or left to auto-match, this frame is upscaled into a short seed clip, so it must be at least 64 px on its shortest side AND at least 6,400 px in total (80x80 is the smallest square accepted; at a 64 px short side the long side needs 100). A file_<ulid> below that returns 400 first_frame_too_small before any credit hold (dimensions were measured at upload); an https:// URL is accepted and settles at status: failed with error_code: "first_frame_too_small" and a full refund, because validation never fetches the bytes. The check runs on the POSSIBILITY of a model, not on one actually being used — an un-pinned frame is rejected even if no model would have matched your image. No minimum applies with video_lora_id: null, nor when a last_frame_url rides alongside — a first+last pair never auto-matches and builds no seed clip either, so no first_frame_too_small ever fires on an interpolation request.

Maximum string length: 2048
Example:

"file_01HXMQ7Z3K8Y2NABCDEFGHJKMN"

​
last_frame_url
string

Last frame for first+last frame interpolation. Same rules as first_frame_url. Requires first_frame_url — sending last_frame_url alone returns 400 with code parameter_invalid_combination.

Maximum string length: 2048
Example:

"https://example.com/last.jpg"

​
resolution
enum<string>

Output video resolution

Available options:
480p,
720p,
1080p
​
ratio
enum<string>

Output video aspect ratio

Available options:
16:9,
4:3,
1:1,
3:4,
9:16,
21:9,
adaptive
​
duration
enum<number>

Video length in seconds. Pass -1 for ADAPTIVE (default): the model selects the optimal whole-second length within its supported range (currently 4–15 s) and you are billed for the delivered length — a VARIABLE price. Call POST /v1/videos/estimate to see the min–max range before submitting. Pass a whole number 4–15 to pin a fixed length (fixed price). Omitting uses the video model's default length when your request pins or is matched to one; otherwise adaptive (-1). Adaptive holds the 15 s ceiling from your balance until it settles.

Available options:
-1,
4,
5,
6,
7,
8,
9,
10,
11,
12,
13,
14,
15
Example:

5

​
generate_audio
boolean

Whether the generated video includes synchronized audio. Defaults to the selected video model's audio setting (currently true for all models unless noted on the model).

​
watermark
boolean

Whether to add watermark

​
enhance_prompt
boolean

Whether to enhance the prompt with AI. A no-op on requests without a prompt (model-driven and reference-driven bodies): nothing to enhance, nothing charged.

​
reference_video_url
string

Your reference video — the motion source for a reference-mode generation, or the clip to continue when video_task is extend. Either an opaque file_<ulid> returned by POST /v1/files (uploaded with purpose: reference_video — format/duration/resolution were already validated at upload), or an HTTPS URL. Requirements: MP4 or MOV (H.264/H.265), 2–15 seconds, up to 50 MB, frame area of at least 409,600 px (≈640×640). Clips above 2,073,600 px (1920×1080, ≈1080p) are downscaled to fit before use, preserving aspect ratio, duration and audio. That downscale runs while this request is open, so a large clip adds seconds before the 201 — allow a client timeout of at least 120 s and send an Idempotency-Key — and uploading it once via POST /v1/files moves that cost off the create call. URLs must be publicly fetchable or pre-signed, serve HTTPS directly (redirects are refused — pass the final URL), and respond within the fetch budget. Cannot be combined with first_frame_url/last_frame_url. While the reference is prepared the generation stays in processing — see the endpoint description for timing.

Maximum string length: 2048
Example:

"https://cdn.example.com/clips/dance-loop.mp4"

​
reference_audio_url
string

An audio reference (voice, music, or ambience) to guide the generated soundtrack — either a file_<ulid> from POST /v1/files (purpose: reference_audio) or an HTTPS URL. WAV or MP3, 2–15 seconds, up to 15 MB. Needs a companion — a reference video, a subject (subjects[] or the legacy fields), or a pinned video_lora_id — and requires audio output (generate_audio must not be false). Same URL rules as reference_video_url (public or signed HTTPS, no redirects).

Maximum string length: 2048
Example:

"https://cdn.example.com/audio/voiceover.mp3"

​
video_task
enum<string>
default:reference

What to do with reference_video_url. reference (default): generate a new scene that borrows the clip's motion. extend: continue the clip itself in extend_direction; extend takes the clip as-is, so it cannot be combined with video_lora_id. Only valid when reference_video_url is present.

Available options:
reference,
extend
​
extend_direction
enum<string>
default:forward

Direction to continue the clip when video_task is extend. Defaults to forward. Only valid with video_task: "extend".

Available options:
forward,
backward

Response

Cost estimate

​
object
enum<string>
required

Discriminator

Available options:
estimate
Example:

"estimate"

​
estimated_cost
object
required

Cost breakdown for this would-be generation.

​
currency
enum<string>
required

Currency unit. All amounts in this response are in credit.

Available options:
credit
Example:

"credit"

​
warnings
object[]

Non-fatal request adjustments the real create would also report (e.g. a retired style pin that generates without a style, or a parameter with no effect on this generation path). Same shape and codes as the warnings on the POST /v1/images 201 body — the estimate warns exactly when the create would. Omitted when empty. Codes are an OPEN set: ignore unknown codes.

Example: