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

# POST /v1/videos

> OpenAI-compatible async video generation — create tasks and poll for results.

# Video generation API

Video models use an **asynchronous** workflow: create a task with `POST /v1/videos`, then poll `GET /v1/videos/{video_id}?model=…` until `status` is `completed` or `failed`.

```bash theme={null}
# 1. Create a video task
curl https://api.openference.com/v1/videos \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Agnes-Video-2.5-Flash",
    "prompt": "A poor boy walks through a rainy alley, then years later steps out of a limousine in a sharp suit, cinematic transition",
    "mode": "text",
    "seconds": "5",
    "size": "720P",
    "aspect_ratio": "16:9"
  }'
```

Create response (task queued):

```json theme={null}
{
  "id": "task_abc123",
  "task_id": "task_abc123",
  "video_id": "video_xyz789",
  "object": "video",
  "model": "Agnes-Video-2.5-Flash",
  "status": "queued",
  "progress": 0,
  "seconds": "5",
  "size": "720P"
}
```

```bash theme={null}
# 2. Poll until completed (every 1–2 seconds)
curl "https://api.openference.com/v1/videos/video_xyz789?model=Agnes-Video-2.5-Flash" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Completed response:

```json theme={null}
{
  "status": "completed",
  "progress": 100,
  "model": "Agnes-Video-2.5-Flash",
  "metadata": {
    "url": "https://api.openference.com/assets/vid/9b6d2c1e-....mp4"
  },
  "seconds": "5",
  "size": "720P"
}
```

## Models

| Model id                | Task                               | Notes                        |
| ----------------------- | ---------------------------------- | ---------------------------- |
| `Agnes-Video-2.5-Flash` | Text-to-video, keyframe, reference | 720P only; 4–12 second clips |

See [Video generation models](/models/video-generation) for mode-specific parameters.

These models appear in `GET /v1/models` but not on the public website catalog.

## Common parameters (create)

| Field          | Type    | Notes                                         |
| -------------- | ------- | --------------------------------------------- |
| `model`        | string  | Required. A video-generation model id.        |
| `prompt`       | string  | Required. Describe the scene and motion.      |
| `mode`         | string  | Required. `text`, `keyframe`, or `reference`. |
| `seconds`      | string  | Clip length `"4"`–`"12"`; default `"5"`.      |
| `size`         | string  | `"720P"` for Agnes-Video-2.5-Flash.           |
| `aspect_ratio` | string  | e.g. `16:9`, `9:16`, `1:1`.                   |
| `n`            | integer | Only `1` is supported.                        |

### Keyframe mode (`mode: "keyframe"`)

Provide at least one of `first_frame` or `last_frame` (public image URLs).

### Reference mode (`mode: "reference"`)

Provide up to **5** image URLs in `images` and/or up to **3** audio URLs in `audios`.

## Poll parameters

| Field      | Location | Notes                                        |
| ---------- | -------- | -------------------------------------------- |
| `video_id` | path     | From the create response (`video_id`).       |
| `model`    | query    | Required. Same model id used at create time. |

## Daily limit

Video generation is limited to **500 seconds of output per account per day** (resets at 00:00 UTC). Exceeding it returns HTTP 429 with code `video_daily_limit_exceeded` and a `Retry-After` header.

Billing is applied when a task reaches `completed` status (based on output seconds).

## Notes

* Video models cannot be used on chat, responses, embeddings, or image endpoints.
* Completed videos are rehosted on Openference (`/assets/vid/…`) so URLs remain stable.
* Poll every 1–2 seconds; stop when `status` is `completed` or `failed`.
* Honor HTTP 429 responses using the `Retry-After` header.