Video

Generate video from a text prompt or reference image with a single async endpoint.

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

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

Run your first generation

1. Get an API key

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

2. Submit a generation

   curl

   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" }
   

   Python

   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"])
   
3. Poll until ready, then download

   curl

   # 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
   

   Python

   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
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, such as 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, such as 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": "xai/grok-imagine-video", "prompt": "the cat blinks slowly", "image": "file_abc123" }'

# image-to-video (xAI): a public, server-fetchable image URL
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": "the cat slowly turns its head and blinks",
    "image": "https://example.com/cat.jpg",
    "parameters": { "duration": 6, "resolution": "720p" }
  }'

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