> ## Documentation Index
> Fetch the complete documentation index at: https://docs.snapgen.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Video API workflow

> Submit, monitor, and download an asynchronous video task.

All SnapGen video routes use the same asynchronous workflow. Choose a model from the **Video Series** sidebar, submit a request, save the returned `id`, and poll until the task completes.

The model page defines the accepted duration, aspect ratio, resolution, and reference-image rules. Do not send values from one model family to another.

<ParamField body="model" type="string" required>
  An available video model ID. Call [`GET /v1/models`](/api-reference/list-models)
  and select a model whose `supported_endpoint_types` includes `openai-video`.
</ParamField>

<ParamField body="prompt" type="string" required>
  Describe the subject, action, camera movement, lighting, and audio intent.
</ParamField>

<ParamField body="seconds" type="string" required>
  A model-specific duration. Use the exact value documented on the selected
  model page.
</ParamField>

<ParamField body="size" type="string">
  Gemini Omni only. Pass pixel dimensions such as `1280x720`.
</ParamField>

<ParamField body="aspect_ratio" type="string">
  Seedance 2 and Veo 3.1 only. Do not send `size` with these routes.
</ParamField>

<ParamField body="image_urls" type="string[]">
  Public `http` or `https` reference URLs when the selected model accepts them.
</ParamField>

<ParamField body="webhook" type="string">
  Optional public callback URL. SnapGen sends the final task object when the
  task completes or fails.
</ParamField>

## Submit a task

```bash theme={null}
curl https://api.snapgen.org/v1/videos \
  -H "Authorization: Bearer $SNAPGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "video-ds-2.0-fast",
    "prompt": "A paper sculpture unfolds into a city skyline",
    "seconds": "5",
    "aspect_ratio": "16:9"
  }'
```

```json theme={null}
{
  "id": "task_01HXYZ",
  "object": "video",
  "status": "queued",
  "model": "video-ds-2.0-fast",
  "seconds": "5"
}
```

## Poll and download

Include the same `model` query value while polling and downloading.

```bash theme={null}
curl "https://api.snapgen.org/v1/videos/task_01HXYZ?model=video-ds-2.0-fast" \
  -H "Authorization: Bearer $SNAPGEN_API_KEY"

curl -L "https://api.snapgen.org/v1/videos/task_01HXYZ/content?model=video-ds-2.0-fast" \
  -H "Authorization: Bearer $SNAPGEN_API_KEY" \
  --output video.mp4
```

Poll every 10 to 20 seconds while `status` is `queued` or `in_progress`. Download only after `status` becomes `completed`.

<CardGroup cols={2}>
  <Card title="Task status API" icon="list-check" href="/api-reference/task-status">
    Query the normalized task record and final media URLs.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/api-reference/webhooks">
    Receive the final task result without continuous polling.
  </Card>
</CardGroup>