Generate a Video from Text

Text-to-video generation takes a natural-language description and produces a short video clip. It uses the same base URL and authentication as text completions, through the dedicated /v1/videos endpoint. Generation is asynchronous: you submit a job and poll for the result.

Submit a job#

Shell

curl https://opendunes.com/api/v1/videos \
  -H "Authorization: Bearer $OPENDUNES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/veo-3.1",
    "prompt": "A lone camel walks across golden sand dunes at sunset, cinematic wide shot",
    "seconds": 6
  }'

The endpoint responds 202 Accepted with a job id and a poll URL:

JSON

{
  "id": "vid_01j...",
  "status": "pending",
  "poll_url": "https://opendunes.com/api/v1/videos/vid_01j..."
}

Request parameters#

Parameter	Type	Required	Description
`model`	string	Yes	Video model slug (`?modality=video`)
`prompt`	string	Yes	Text description of the desired video
`seconds`	integer	No	Requested clip length, 1–60 (default: 8; model-dependent maximum)

Poll for the result#

Python

import os, time, httpx

headers = {"Authorization": f"Bearer {os.environ['OPENDUNES_API_KEY']}"}

job = httpx.post(
    "https://opendunes.com/api/v1/videos",
    headers=headers,
    json={"model": "google/veo-3.1",
          "prompt": "A lone camel walks across golden sand dunes at sunset, cinematic wide shot",
          "seconds": 6},
).json()

while True:
    status = httpx.get(f"https://opendunes.com/api/v1/videos/{job['id']}", headers=headers).json()
    if status["status"] == "completed":
        print(status["url"])  # signed, time-limited URL
        break
    if status["status"] == "failed":
        print("generation failed")
        break
    time.sleep(5)

On completed, the job carries a signed URL to the rendered clip:

JSON

{
  "id": "vid_01j...",
  "status": "completed",
  "url": "https://opendunes.com/api/v1/media/videos/2026/07/22/vid_01j....mp4?expires=...&signature=..."
}

Writing effective prompts#

Video models respond well to prompts that specify:

Subject — what or who is in the frame.
Action — what is happening or moving.
Setting — location, time of day, weather.
Camera language — wide shot, close-up, tracking shot, slow motion.
Style — cinematic, documentary, animation, 4K.

Bad: "a city"

Good: "Drone shot flying over Algiers at dawn, the Mediterranean coast visible to the north, golden light, cinematic 4K"

Downloading the video#

The url is a temporary signed link — re-polling the job returns a fresh one. The stored clip is retained for a limited time (about two weeks), so download it promptly:

Python

import httpx, pathlib

resp = httpx.get(status["url"])
resp.raise_for_status()
pathlib.Path("output.mp4").write_bytes(resp.content)

Cost#

Video is billed per second of output in DA. The cost of the requested seconds is held on submission and settled on completion; a failed or timed-out job releases the full hold and charges nothing. Per-second rates appear in the model catalog. See the video API reference.

Submit a job#

Shell

curl https://opendunes.com/api/v1/videos \
  -H "Authorization: Bearer $OPENDUNES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/veo-3.1",
    "prompt": "A lone camel walks across golden sand dunes at sunset, cinematic wide shot",
    "seconds": 6
  }'

The endpoint responds 202 Accepted with a job id and a poll URL:

JSON

{
  "id": "vid_01j...",
  "status": "pending",
  "poll_url": "https://opendunes.com/api/v1/videos/vid_01j..."
}

Parameter

Type

Required

Description

model

string

Yes

Video model slug (?modality=video)

prompt

string

Yes

Text description of the desired video

seconds

integer

Requested clip length, 1–60 (default: 8; model-dependent maximum)

Poll for the result#

Python

import os, time, httpx

headers = {"Authorization": f"Bearer {os.environ['OPENDUNES_API_KEY']}"}

job = httpx.post(
    "https://opendunes.com/api/v1/videos",
    headers=headers,
    json={"model": "google/veo-3.1",
          "prompt": "A lone camel walks across golden sand dunes at sunset, cinematic wide shot",
          "seconds": 6},
).json()

while True:
    status = httpx.get(f"https://opendunes.com/api/v1/videos/{job['id']}", headers=headers).json()
    if status["status"] == "completed":
        print(status["url"])  # signed, time-limited URL
        break
    if status["status"] == "failed":
        print("generation failed")
        break
    time.sleep(5)

On completed, the job carries a signed URL to the rendered clip:

JSON

{
  "id": "vid_01j...",
  "status": "completed",
  "url": "https://opendunes.com/api/v1/media/videos/2026/07/22/vid_01j....mp4?expires=...&signature=..."
}

Writing effective prompts#

Video models respond well to prompts that specify:

Subject — what or who is in the frame.

Action — what is happening or moving.

Setting — location, time of day, weather.

Camera language — wide shot, close-up, tracking shot, slow motion.

Style — cinematic, documentary, animation, 4K.

Bad: "a city"

Good: "Drone shot flying over Algiers at dawn, the Mediterranean coast visible to the north, golden light, cinematic 4K"

Downloading the video#

The url is a temporary signed link — re-polling the job returns a fresh one. The stored clip is retained for a limited time (about two weeks), so download it promptly:

Python

import httpx, pathlib

resp = httpx.get(status["url"])
resp.raise_for_status()
pathlib.Path("output.mp4").write_bytes(resp.content)