Skip to main content
POST
/
v1
/
videos
Create a new video generation
curl --request POST \
  --url https://api.example.com/v1/videos \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <api-key>' \
  --data '
{
  "video_lora_id": "lora_01HXMQ7Z3K8Y2ABCDEFGHJKM",
  "prompt": "A golden sunset over the ocean with gentle waves",
  "first_frame_url": "file_01HXMQ7Z3K8Y2NABCDEFGHJKMN",
  "last_frame_url": "https://example.com/last.jpg",
  "resolution": "480p",
  "ratio": "16:9",
  "duration": 5,
  "seed": 123,
  "camera_fixed": true,
  "watermark": true,
  "enhance_prompt": true,
  "webhook_url": "<string>"
}
'
{
  "id": "img_01HXMQ7Z3K8Y2ABCDEFGHJKM",
  "status": "succeeded",
  "prompt": "A golden sunset over mountains, cinematic lighting",
  "created_at": "2026-05-04T10:00:00Z",
  "media_type": "image",
  "negative_prompt": "blurry, low quality",
  "output_urls": [
    "https://api.aurous-labs.com/v1/images/img_01HXMQ7Z3K8Y2ABCDEFGHJKM/output/0?token=..."
  ],
  "output_video_url": "https://api.aurous-labs.com/v1/videos/vid_01HXMQ7Z3K8Y2ABCDEFGHJKM/output?token=...",
  "reference_image_urls": [
    "https://example.com/ref1.jpg"
  ],
  "error_message": "Content policy violation",
  "duration_ms": 14820,
  "cost": {
    "amount": 2,
    "currency": "credit",
    "breakdown": {
      "base": 1,
      "enhance": 1
    }
  },
  "width": 1024,
  "height": 1024,
  "image_count": 1,
  "size_preset": "square",
  "inference_type": "t2i",
  "seed": 42,
  "video_duration": 5,
  "video_resolution": "480p",
  "video_ratio": "16:9",
  "video_camera_fixed": {},
  "character_id": "char_01HXMQ7Z3K8Y2ABCDEFGHJKM",
  "bundle_name": "Cinematic Trio",
  "loras": [
    {
      "id": "lora_01HXMQ7Z3K8Y2ABCDEFGHJKM",
      "name": "Sunset Style"
    }
  ],
  "aurous_version": "2026-05-15",
  "creation_request_id": "req_01HXMQ7Z3K8Y2ABCDEFGHJKM",
  "completed_at": "2026-05-04T10:00:14Z"
}

Documentation Index

Fetch the complete documentation index at: https://docs.aurous-labs.com/llms.txt

Use this file to discover all available pages before exploring further.

Authorizations

​
X-Api-Key
string
header
required

Your team API key (starts with al_live_ — legacy keys may start with og_).

Headers

​
Idempotency-Key
string

See POST /v1/images - same contract.

​
Aurous-Version
string

Optional API version pin (YYYY-MM-DD). Defaults to your team's pinned version, or the system default 2026-05-15 for unauthenticated requests.

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

"2026-05-15"

Body

application/json
​
video_lora_id
string
required

Opaque video LoRA identifier (lora_*) or slug. UUIDs accepted for legacy back-compat.

Example:

"lora_01HXMQ7Z3K8Y2ABCDEFGHJKM"

​
prompt
string

Text prompt describing the video. Optional — enhances the generation when provided.

Example:

"A golden sunset over the ocean with gentle waves"

​
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). URLs are server-side fetched through an SSRF-pinned client (rejects private IPs / cloud metadata).

Maximum string length: 2048
Example:

"file_01HXMQ7Z3K8Y2NABCDEFGHJKMN"

​
last_frame_url
string

Last frame for first+last frame interpolation. Same rules as first_frame_url.

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
​
duration
number

Video duration in seconds (2-12)

Required range: 2 <= x <= 12
Example:

5

​
seed
number

Random seed (-1 for random)

​
camera_fixed
boolean

Whether to fix the camera position

​
watermark
boolean

Whether to add watermark

​
enhance_prompt
boolean

Whether to enhance the prompt with AI

​
webhook_url
string

Webhook URL to receive POST callback when generation completes or fails

Response

Video generation created

​
id
string
required

Opaque generation ID

Example:

"img_01HXMQ7Z3K8Y2ABCDEFGHJKM"

​
status
enum<string>
required

Current generation status. Lifecycle: pending (created, not yet dispatched) → processing (provider running) → terminal succeeded / failed / cancelled. (P0-4 from api-consumer review: previously listed queued, expired, and moderation_rejected — none of which the v1.0 server actually emits today. Codegen-strict clients would crash on the first pending response. Those values may return in v1.1 once the BullMQ producer and TTL reaper are exposed publicly.)

Available options:
pending,
processing,
succeeded,
failed,
cancelled
Example:

"succeeded"

​
prompt
string
required

The text prompt used for generation

Example:

"A golden sunset over mountains, cinematic lighting"

​
created_at
string
required

Creation timestamp (ISO 8601)

Example:

"2026-05-04T10:00:00Z"

​
media_type
enum<string> | null

Distinguishes image vs video generation. May be null for older rows minted before this column existed.

Available options:
image,
video
Example:

"image"

​
negative_prompt
object

Negative prompt to exclude from generation

Example:

"blurry, low quality"

​
output_urls
string[] | null

Generated image proxy URLs. Available for ~24 hours after generation. Save what you want to keep — long-term storage is intentionally not part of the platform. URLs return 410 Gone after expiry.

Example:
[
  "https://api.aurous-labs.com/v1/images/img_01HXMQ7Z3K8Y2ABCDEFGHJKM/output/0?token=..."
]
​
output_video_url
object

Generated video proxy URL (only present on media_type: video). Same 24h TTL as image output_urls.

Example:

"https://api.aurous-labs.com/v1/videos/vid_01HXMQ7Z3K8Y2ABCDEFGHJKM/output?token=..."

​
reference_image_urls
string[] | null

Reference image URLs that were used as visual anchors for this generation, if any. Snapshotted at inference time — for character-attached generations, these are the resolved character refs at submission, not the live character state.

Example:
["https://example.com/ref1.jpg"]
​
error_message
object

Error message if the generation failed

Example:

"Content policy violation"

​
duration_ms
object

Processing duration in milliseconds (set on terminal status)

Example:

14820

​
cost
object

Per-generation cost breakdown — same shape as the estimated_cost returned by POST /v1/{images,videos}/estimate. null for legacy rows minted before this field shipped (PR-4 / 2026-05-15+); populated for all new generations. The amount reflects the committed charge for terminal-status rows.

Example:
{
  "amount": 2,
  "currency": "credit",
  "breakdown": { "base": 1, "enhance": 1 }
}
​
width
number

Image width in pixels (image generations only)

Example:

1024

​
height
number

Image height in pixels (image generations only)

Example:

1024

​
image_count
number

Number of images requested in the batch

Example:

1

​
size_preset
object

Size preset applied (overrides width/height when set)

Example:

"square"

​
inference_type
enum<string> | null

Inference mode actually dispatched. t2i = text-to-image; i2i = image-to-image (when reference_image_urls or character_id are set).

Available options:
t2i,
i2i
Example:

"t2i"

​
seed
object

Random seed used (image generations)

Example:

42

​
video_duration
object

Video duration in seconds (video generations only)

Example:

5

​
video_resolution
enum<string> | null

Video resolution (video generations only)

Available options:
480p,
720p,
1080p
Example:

"480p"

​
video_ratio
enum<string> | null

Video aspect ratio (video generations only)

Available options:
16:9,
4:3,
1:1,
3:4,
9:16,
21:9
Example:

"16:9"

​
video_camera_fixed
object

Whether the camera was held fixed during the video

​
character_id
object

Opaque character ID if the generation referenced a character (image only)

Example:

"char_01HXMQ7Z3K8Y2ABCDEFGHJKM"

​
bundle_name
object

Display name of the LoRA bundle, if a bundle was applied. Bundles surface uniformly under the loras array; this field is informational.

Example:

"Cinematic Trio"

​
loras
object[] | null

LoRAs applied to this generation. Populated only on single-LoRA dispatch. For bundle dispatch (when bundle_name is set), loras is null — bundle members are intentionally not unrolled in the public response (catalog uniformity, spec D24). null also for prompt-only and pure-reference generations.

​
aurous_version
string

API contract version applied at the time this row was minted (D25 — frozen for replay across future version bumps).

Example:

"2026-05-15"

​
creation_request_id
string

Aurous-Request-Id of the POST that created this row. Quote in support tickets to trace the original create request.

Example:

"req_01HXMQ7Z3K8Y2ABCDEFGHJKM"

​
completed_at
object

Terminal-status timestamp (ISO 8601). NULL until the generation reaches a terminal state.

Example:

"2026-05-04T10:00:14Z"