Video

POST /v3/videos is a deterministic, provider-agnostic video endpoint. You pass a model and a prompt; Opper runs the job and gives you a URL to poll. The same two-step flow works across every video provider (Google Veo, xAI Grok-Imagine, Alibaba Wan, Pruna, and more): only the contents of parameters differ per model.

Video generation is asynchronous: submitting returns immediately with an id, and you poll for the result. A clip typically takes from ~30 seconds to a few minutes depending on the model, resolution, and duration.

How it works

Submit: POST /v3/videos with model + prompt → 202 { id, status_url }
Poll: GET {status_url} until status is completed or failed
Download: fetch the presigned url from the completed response (valid 1 hour)

Rather not poll? Pass a callback_url (or save a default URL for the project) and Opper sends a signed video.completed or video.failed event when the job ends. See Webhooks.

Run your first generation

Get an API key

Create a project-scoped runtime API key in the Opper dashboard.

Submit a generation

curl
Python

curl -sX POST https://api.opper.ai/v3/videos \
  -H "Authorization: Bearer $OPPER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "xai/grok-imagine-video",
    "prompt": "a hot air balloon drifting over green hills at dawn",
    "parameters": { "duration": 6, "aspect_ratio": "16:9", "resolution": "720p" }
  }'
# → 202 { "id": "gen_...", "status_url": "https://api.opper.ai/v3/artifacts/gen_.../status" }

import os, time, requests

BASE = "https://api.opper.ai"
headers = {"Authorization": f"Bearer {os.environ['OPPER_API_KEY']}"}

r = requests.post(f"{BASE}/v3/videos", headers=headers, json={
    "model": "xai/grok-imagine-video",
    "prompt": "a hot air balloon drifting over green hills at dawn",
    "parameters": {"duration": 6, "aspect_ratio": "16:9", "resolution": "720p"},
})
r.raise_for_status()
job = r.json()
print("submitted:", job["id"])

Poll until ready, then download

curl
Python

# Poll (repeat until status is "completed" or "failed")
curl -s https://api.opper.ai/v3/artifacts/gen_XXX/status \
  -H "Authorization: Bearer $OPPER_API_KEY"
# processing → { "status": "processing", "provider": "xai", "model": "xai/grok-imagine-video" }
# done       → { "status": "completed", "mime_type": "video/mp4", "url": "https://...presigned..." }

# Download the finished clip
curl -s "<url-from-completed-response>" -o video.mp4

status_url = job["status_url"]
while True:
    s = requests.get(status_url, headers=headers).json()
    if s["status"] == "completed":
        data = requests.get(s["url"]).content   # presigned; no auth header needed
        open("video.mp4", "wb").write(data)
        print("saved video.mp4", len(data), "bytes")
        break
    if s["status"] == "failed":
        raise SystemExit(f"generation failed: {s.get('error')}")
    time.sleep(10)

Models and parameters

model and prompt are required. A model id names its provider, such as bytedance:ap/seedance-2.5 or fal/kling-3.0-pro: the same model can be served by several providers, each with its own inputs, defaults and price. A bare name like seedance-2.5 answers 400 with the ids that serve it. Length, resolution and shape are top-level fields, normalized for every model:

Field	What it does
`seconds`	Clip length in seconds.
`resolution`	Output tier, such as `480p`, `720p`, `1080p` or `4k`. Most models bill each tier at its own rate.
`aspect_ratio`	`16:9`, `9:16`, `1:1`, and so on.
`store`	Save the finished clip to Files and return a `file_id`.
`parameters`	Anything model-specific, forwarded verbatim to the provider.

curl -sX POST https://api.opper.ai/v3/videos \
  -H "Authorization: Bearer $OPPER_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "model": "fal/kling-3.0-pro",
    "prompt": "a woman holds up a serum bottle and smiles, handheld selfie style",
    "seconds": 5,
    "aspect_ratio": "9:16",
    "parameters": { "generate_audio": false }
  }'

To discover what’s available programmatically, call GET /v3/videos/models. Each model’s params.video lists its accepted aspect_ratios, resolutions and max_duration, plus a parameters list of the provider knobs it takes, and pricing gives its per-second rates:

curl -s "https://api.opper.ai/v3/videos/models?capability=image_to_video" \
  -H "Authorization: Bearer $OPPER_API_KEY"

Audio

Kling, Seedance and Veo render native audio, and a silent clip costs less. The default differs by provider, so set parameters.generate_audio to true or false explicitly. A model whose rate depends on it shows an audio dimension on its pricing.rates, or a separate price_per_second_audio.

Image, video and audio inputs

Each input is an http(s) URL, a data-URI, or a file_id. A model takes an input only when it has the matching capability, and answers 400 otherwise:

Input	Needs capability	Use for
`image`	`image_to_video`	The first frame to animate.
`last_image`	`last_frame`	The ending frame; needs `image`.
`reference_images`	`reference_images`	A subject or character to keep consistent.
`video`	`video_editing`, `video_extension` or `reference_video`	A clip to edit, extend or re-animate.
`reference_videos`	`reference_video`	More source videos after `video`. Seedance takes three in all, cited in the prompt as video 1, 2 and 3.
`audio`	`audio_to_video`	Audio the character speaks, lips in sync. On a `lip_sync` model (VEED Fabric, OmniHuman) the prompt is optional and the audio sets the length.

A file_id from a previous image generation or upload works as any of these inputs, with no re-upload. See Files for how files work, lifecycle, and storage quotas.

Edit a clip (Seedance 2.5 on BytePlus)

curl -sX POST https://api.opper.ai/v3/videos \
  -H "Authorization: Bearer $OPPER_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "model": "bytedance:ap/seedance-2.5",
    "prompt": "change her shirt to a red sweater, keep everything else",
    "video": "file_abc123",
    "resolution": "720p"
  }'

Seedance (on BytePlus and on fal) refuses an image or video input that shows a realistic person, AI-generated ones included. On bytedance:ap/ models an image made with a bytedance:ap/seedream-* model through Opper passes, because BytePlus trusts its own outputs for 30 days. For an edit or extension, leave seconds and aspect_ratio out: the clip keeps the input’s.

Source-format rules differ per provider:

Provider	`image` / `video` accepts
Veo	base64 / data-URI / `gs://` URI only; an http URL is not fetched. (A `gs://` object must be readable by Opper’s Vertex service account, so base64/data-URI is the reliable choice.)
Pruna, xAI	a public, server-fetchable URL only (a data-URI or private URL won’t work).

Reference

Generate a video: POST /v3/videos
List video models: GET /v3/videos/models

Get started

Platform

Build

Observe & Control

Apps

Tutorials

Tooling

How it works

Run your first generation

Models and parameters

Audio

Image, video and audio inputs

Reference

​How it works

​Run your first generation

​Models and parameters

​Audio

​Image, video and audio inputs

​Reference

How it works

Run your first generation

Models and parameters

Audio

Image, video and audio inputs

Reference