Video - Opper

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 (OpenAI Sora, xAI Grok-Imagine, Pruna Wan, Google Veo) — 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)

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": "openai/sora-2",
    "prompt": "a hot air balloon drifting over green hills at dawn",
    "parameters": { "seconds": "4", "size": "1280x720" }
  }'
# → 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": "openai/sora-2",
    "prompt": "a hot air balloon drifting over green hills at dawn",
    "parameters": {"seconds": "4", "size": "1280x720"},
})
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": "openai", "model": "openai/sora-2" }
# 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 the only fields Opper owns. Everything inside parameters is forwarded verbatim to the provider, which validates and rejects it — so the accepted keys depend on the model. Common examples:

Model	Example `parameters`
`openai/sora-2`	`{ "seconds": "4", "size": "1280x720" }`
`xai/grok-imagine-video`	`{ "duration": 6, "aspect_ratio": "16:9", "resolution": "720p" }`
`pruna/wan-t2v`	`{ "resolution": "720p", "aspect_ratio": "16:9" }`
`vertexai/veo-3.1-fast-generate-001`	`{ "durationSeconds": 4, "resolution": "720p", "generateAudio": false }`

To discover what’s available programmatically — including each model’s accepted aspect_ratios, resolutions, and max_duration — call GET /v3/videos/models:

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

Each item’s capabilities tells you the input modality: video_generation is text-to-video, image_to_video needs a reference image, and video_editing is video-to-video.

Reference image and video

Alongside prompt, you can pass a top-level image (image-to-video) or video (video-to-video). Each is an http(s) URL, a data-URI, or a file_id.

image — supported by image_to_video models: openai/sora-2, openai/sora-2-pro, vertexai/veo-3.1-generate-001, vertexai/veo-3.1-fast-generate-001, pruna/wan-i2v, xai/grok-imagine-video.
video — supported by video_editing models: pruna/vace.

A file_id from a previous image generation or upload works as the seed image here — no re-upload. See Files for how files work, lifecycle, and storage quotas.

Seed a video from a file_id

curl -sX POST https://api.opper.ai/v3/videos \
  -H "Authorization: Bearer $OPPER_API_KEY" -H "Content-Type: application/json" \
  -d '{ "model": "openai/sora-2", "prompt": "the cat blinks slowly", "image": "file_abc123" }'

# image-to-video (Sora): image URL or base64 data-URI
curl -sX POST https://api.opper.ai/v3/videos \
  -H "Authorization: Bearer $OPPER_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "model": "openai/sora-2",
    "prompt": "the cat slowly turns its head and blinks",
    "image": "https://example.com/cat.jpg",
    "parameters": { "seconds": "4", "size": "720x1280" }
  }'

Source-format rules differ per provider:

Provider	`image` / `video` accepts
Sora	http URL or base64/data-URI. The image’s pixel dimensions must equal the requested `size`.
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

​How it works

​Run your first generation

​Models and parameters

​Reference image and video

​Reference

How it works

Run your first generation

Models and parameters

Reference image and video

Reference