Video generation

1. POST /v1/videos/generations — submit a job. Answers 202 with a job object containing an id.
2. GET /v1/videos/generations/{id} — poll the job until its status is terminal (succeeded or failed).

​

Quickstart

# 1) Submit — returns 202 with the job id
JOB=$(curl -s https://api.aireserve.com/v1/videos/generations \
  -H "Authorization: Bearer $AIRESERVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan-2.6",
    "prompt": "A drone shot over a misty pine forest at sunrise",
    "duration_seconds": 5,
    "size": "1280x720"
  }')
JOB_ID=$(echo "$JOB" | jq -r .id)

# 2) Poll every few seconds until the job is terminal
while :; do
  JOB=$(curl -s "https://api.aireserve.com/v1/videos/generations/$JOB_ID" \
    -H "Authorization: Bearer $AIRESERVE_API_KEY")
  STATUS=$(echo "$JOB" | jq -r .status)
  echo "status: $STATUS"
  case "$STATUS" in succeeded|failed) break ;; esac
  sleep 3
done

# 3) Download the finished clip (mp4)
curl -o clip.mp4 "$(echo "$JOB" | jq -r .result.video.url)"

​

Request parameters

​

Media inputs

​

The job object

{
  "id": "3f8a1e2c-9d4b-4c6a-b7e1-2a5c8d9f0e13",
  "object": "video.generation.job",
  "kind": "video",
  "model": "wan-2.6",
  "status": "succeeded",
  "created_at": 1752000000,
  "completed_at": 1752000041,
  "result": {
    "video": {
      "url": "https://…/output.mp4",
      "width": 1280,
      "height": 720,
      "duration": 5
    }
  },
  "error": null,
  "artifact_expires_at": null,
  "upstream_deleted_at": null
}

• On success, result.video.url is an MP4 hosted on the provider’s CDN — download promptly and persist on your side; the URL is not permanent. Every model also returns the same URL as result.videos[0], so a parser written against either field works for every provider.
• Generated artifacts follow each provider’s own retention policy — no fixed deletion window is guaranteed (see the provider data-handling page for per-provider retention). artifact_expires_at and upstream_deleted_at report platform-scheduled deletion of the provider-side artifact where a model supports it; they are null for models without platform-side deletion — including every model in the table below.
• Extra metadata in result varies by model (for example wan-2.6 echoes width/height/duration; seedance-2.0 omits them).
• On failure, error is a human-readable string and result stays null.

​

Models & pricing

​

Wan 3.0 (Higgsfield)

# Submit a source image animation. Requires both organization consents.
JOB=$(curl --fail-with-body -sS https://api.aireserve.com/v1/videos/generations \
  -H "Authorization: Bearer $AIRESERVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan3.0-i2v-higgsfield",
    "prompt": "A slow cinematic camera push toward the subject",
    "image": "https://example.com/first-frame.png",
    "duration_seconds": 5,
    "resolution": "720p",
    "ratio": "16:9",
    "audio": true
  }')
JOB_ID=$(printf '%s' "$JOB" | jq -r .id)

# Repeat every few seconds until succeeded or failed; use a deadline in production.
curl --fail-with-body -sS "https://api.aireserve.com/v1/videos/generations/$JOB_ID" \
  -H "Authorization: Bearer $AIRESERVE_API_KEY"

​

BACH (Video Rebirth)

1. Apply infrastructure so the two secret containers and the proxy’s access grants exist: dispatch the Infrastructure Deploy workflow from main with environment=uat, then environment=production (action=up), or run cd packages/infra && bun up:uat / bun up:production. The workflow is workflow_dispatch only — it does not run on merge.
2. Add the credential versions, UAT first: gcloud secrets versions add BACH_ACCESS_KEY --project audacity-uat --data-file=- and gcloud secrets versions add BACH_SECRET_KEY --project audacity-uat --data-file=-; repeat with --project audacity-production. Never create the secrets themselves with gcloud — Pulumi owns them.
3. Once Video Rebirth’s rates are in writing, commit packages/db/scripts/pricing-sync/update-provider-pricing-<date>-bach.ts with one row per model under provider: "bach" — inputPricePer1mTokens = USD per 1,000,000 generated seconds at 720p, outputPricePer1mTokens = the same at 1080p, outputPricePerImage = the default-job reference for reporting. The Provider Pricing Apply workflow applies it on merge; scripts/pricing-sync/bach-pricing-parity.test.ts pins the column convention. A 0.000000 placeholder is not a rate card — the model stays dark.
4. Deploy litellm-proxy (UAT auto-deploys on merge; production through Deploy All). The adapter re-reads pricing every 60 seconds, so no restart is needed for a rate change alone.
5. Smoke on UAT: confirm the three ids appear in GET /v1/models, submit a bach-1.0-video job, poll to succeeded, and check the usage row carries provider: "bach" with the expected estimated cost.

​

Image-to-video and reference-to-video (fal)

​

Image-to-video and reference-to-video (ByteDance official API)

• Keyframe mode: first_frame (or its alias image) starts the clip on your image; add last_frame to also pin the closing frame. Images may be a public URL, a data:image/...;base64, data URI, or bare Base64 (PNG, JPEG, GIF, WebP, BMP).
• Reference mode (ByteDance’s “omni reference”): reference_images, reference_videos and reference_audios, in any combination, referenced in the prompt as “Image 1”, “Video 1”, “Audio 1”. Video editing and video extension are reference-mode requests whose prompt describes the change or the continuation of a reference_videos clip. Videos and audio are http(s) URLs only.

​

Polling from Python

import os, time, requests

BASE = "https://api.aireserve.com"
HEADERS = {"Authorization": f"Bearer {os.environ['AIRESERVE_API_KEY']}"}

job = requests.post(
    f"{BASE}/v1/videos/generations",
    headers=HEADERS,
    json={
        "model": "wan-2.6",
        "prompt": "A drone shot over a misty pine forest at sunrise",
        "duration_seconds": 5,
        "size": "1280x720",
    },
    timeout=30,
)
job.raise_for_status()
job = job.json()

deadline = time.monotonic() + 600          # give up after 10 minutes
while job["status"] in ("queued", "running"):
    if time.monotonic() > deadline:
        raise TimeoutError(f"video job {job['id']} did not finish in time")
    time.sleep(3)
    resp = requests.get(
        f"{BASE}/v1/videos/generations/{job['id']}", headers=HEADERS, timeout=30
    )
    if resp.status_code >= 500:
        continue                            # transient — retry the next poll
    resp.raise_for_status()
    job = resp.json()

if job["status"] == "succeeded":
    url = job["result"]["video"]["url"]
    with open("clip.mp4", "wb") as f:       # download promptly — URLs expire
        f.write(requests.get(url, timeout=120).content)
else:
    print("generation failed:", job["error"])

​

Errors

• 400 at submit — duration_seconds is not one of the values the model supports (for example wan-2.6 only accepts 5, 10, or 15). The message lists the allowed values; no job is created.
• 502 at submit — the provider rejected the job synchronously (for example a prompt rejected by upstream validation). The response carries the provider’s message and a job_id; the failed job remains readable by id.
• 404 job_not_found on poll — the job id is unknown or belongs to a different workspace’s key.