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

# Create Video

> POST /v1/videos — submit an async video generation job.

## Endpoint

```
POST /v1/videos
```

Returns **HTTP 202** immediately. Poll `GET /v1/videos/{id}` for the result.

## Request

<ParamField header="Authorization" type="string" required>
  `Bearer <your-token>`
</ParamField>

<ParamField header="Content-Type" type="string" required>
  `application/json`
</ParamField>

<ParamField header="Idempotency-Key" type="string">
  Any unique string. Reusing the same key returns the existing job instead of creating a new one. See [Idempotency](/docs/guides/idempotency).
</ParamField>

### Body

<ParamField body="model" type="string" required>
  Model ID from `GET /v1/models`.
</ParamField>

<ParamField body="prompt" type="string" required>
  Text description of the video to generate. Max 2500 characters.
</ParamField>

<ParamField body="negative_prompt" type="string">
  Elements to avoid in the output. Max 2500 characters.
</ParamField>

<ParamField body="aspect_ratio" type="string" default="16:9">
  Output aspect ratio. One of `16:9`, `9:16`, `1:1`.
</ParamField>

<ParamField body="duration" type="number" default="5">
  Clip length in seconds. Allowed values depend on the model — check `durations` from `GET /v1/models`.
</ParamField>

<ParamField body="guidance_scale" type="number" default="0.5">
  How closely to follow the prompt. Range `0`–`1`. Higher = more literal.
</ParamField>

<ParamField body="image" type="string">
  Publicly accessible image URL. **Required** for image-to-video models. See [Image to Video](/docs/guides/image-to-video).
</ParamField>

## Example

```bash theme={null}
curl -X POST https://hypergate.store/v1/videos \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kwaivgi/kling-v2.5-pro/text-to-video",
    "prompt": "A wooden boat drifting across a calm bay at dawn",
    "aspect_ratio": "16:9",
    "duration": 5
  }'
```

## Response `202`

```json theme={null}
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "model": "kwaivgi/kling-v2.5-pro/text-to-video",
  "status": "queued",
  "created_at": "2026-08-14T08:00:00.000Z"
}
```