Estimate the credit cost of a video generation
For a fixed duration, estimated_cost.amount is the exact charge. For adaptive (duration: -1, the default), estimated_cost.adaptive is true and the price is a range: amount_min–amount_max, where amount equals amount_max (the credits held up front). You are charged for the delivered length and refunded the difference. Same validation as POST /v1/videos, but without side effects — no character synthesis, no reference materialization. A cast (subjects[]) is validated identically to POST /v1/videos — cast characters are existence/readiness-checked — and does not change the price.
reference_video_url/reference_audio_url (a file_<ulid> from POST /v1/files or an HTTPS URL) are validated for shape and parameter-combination compatibility, identically to POST /v1/videos. A file_<ulid> additionally gets the same read-only checks the create call performs — it must exist, belong to your team (404 otherwise), and have been uploaded with the matching purpose (400 reference_media_invalid otherwise). The media bytes are never fetched at estimate time — the estimate never touches the network — so byte-level validation (format, duration, resolution) and HTTPS-URL fetching only happen on the actual create call. A reference-to-video request never charges the enhance_prompt multiplier, even when enhance_prompt: true — the system composes the prompt around the reference and never invokes the enhancer.
Because the reference clip is never fetched, its real duration is unknown at estimate time, so a reference (video_task: reference) or extend request is priced at the 15-second input ceiling — an upper bound. The actual charge is typically lower: the create hold prices against the real clip length. As with the image estimate, this is a deliberate, conservative divergence — you are never charged more than this estimate.
Video rates are DB-driven. Video is priced from the live per-model rate table — see GET /v1/models for the current per-model credit rates — NOT frozen in the Aurous-Version rate card. Unlike image pricing (which is version-frozen), per-model video rates MAY change without an Aurous-Version bump; this is the same pricing asymmetry the LLM chat/embeddings surfaces use (spec §6.4). Pin an Aurous-Version for stable request/response shapes; call this estimate endpoint for an authoritative current-price quote immediately before you generate.
Authorizations
Your team API key (starts with al_live_).
Headers
Optional API version pin (YYYY-MM-DD). Defaults to your team's pinned version, or the system default 2026-07-16 for unauthenticated requests.
^\d{4}-\d{2}-\d{2}$"2026-07-16"
Body
Text prompt describing the video. Required unless first_frame_url is provided (image-to-video). Subject-driven generation (character_id or reference_image_urls) still requires a prompt describing the action — a subject alone cannot substitute for one.
"A golden sunset over the ocean with gentle waves"
Optional. An id (or slug, where one is set) from GET /v1/video_loras. Pins a specific video model. If omitted, the platform picks a suitable model for your prompt; if none matches, your prompt is generated as plain video (or, with a subject attached, a subject-driven video). Pin a model only to override that choice.
"action_01HXMQ7Z3K8Y2VNABCDEFGHJKM"
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.
"char_01HXMQ7Z3K8Y2ABCDEFGHJKM"
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.
6Ordered 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.
2First 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).
2048"file_01HXMQ7Z3K8Y2NABCDEFGHJKMN"
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.
2048"https://example.com/last.jpg"
Output video resolution
480p, 720p, 1080p Output video aspect ratio
16:9, 4:3, 1:1, 3:4, 9:16, 21:9, adaptive 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.
-1, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15 5
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).
Whether to add watermark
Whether to enhance the prompt with AI
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 between 409,600 px (≈640×640) and 2,073,600 px (1920×1080, ≈1080p). 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.
2048"https://cdn.example.com/clips/dance-loop.mp4"
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).
2048"https://cdn.example.com/audio/voiceover.mp3"
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.
reference, extend Direction to continue the clip when video_task is extend. Defaults to forward. Only valid with video_task: "extend".
forward, backward Response
Cost estimate
Discriminator
estimate "estimate"
Cost breakdown for this would-be generation.
Currency unit. All amounts in this response are in credit.
credit "credit"
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.