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

# Grok video API

> Generate Grok videos from text through Floodgate. Poll the compatible task view, download completed results, and check input limits, errors and second billing.

Use Grok video generation with a text prompt. Floodgate returns a public task ID and a compatible task view for status checks.

## Operations and limits

| Method | Path | Purpose |
| - | - | - |
| POST | `/v1/videos/generations` | Submit |
| GET | `/v1/videos/{task_id}` | Poll |
| GET | `/v1/videos/{task_id}/content` | Download |

The reviewed offerings are `grok-imagine-video` and `grok-imagine-video-1.5-preview` in `Xai-Grok-1`. Use only currently available operations in [Model Square](https://floodgate.dev/models).

| Field | Required | Values |
| - | - | - |
| `model` | Yes | The accepted model ID |
| `prompt` | Yes | Text input |
| `duration` | Yes | Integer, 1 to 15 seconds |
| `resolution` | Yes | `720p` |
| `aspect_ratio` | No | `16:9`, `9:16`, `1:1` |

Reference media, image input, audio controls and advanced actions are outside this contract.

## Submit

```bash theme={null}
curl --fail-with-body https://api.floodgate.dev/v1/videos/generations \
  -H "Authorization: Bearer $FLOODGATE_API_KEY" -H 'Content-Type: application/json' \
  -d '{"model":"grok-imagine-video","prompt":"A quiet forest beside a lake","duration":5,"resolution":"720p"}'
```

```json theme={null}
{"id":"task_example","task_id":"task_example","object":"video","model":"grok-imagine-video","status":"queued","progress":0,"created_at":1700000000}
```

## Poll and download

Set `TASK_ID` to the returned `id`. Pending states are `queued` and `in_progress`. Stop at `completed` or `failed`.

```bash theme={null}
curl --fail-with-body "https://api.floodgate.dev/v1/videos/$TASK_ID" \
  -H "Authorization: Bearer $FLOODGATE_API_KEY"
```

```json theme={null}
{"id":"task_example","status":"completed","progress":100,"result_url":"/v1/videos/task_example/content"}
```

```json theme={null}
{"id":"task_example","status":"failed","error":{"code":"task_failed","message":"Video generation failed"}}
```

After `completed`, download with authentication:

```bash theme={null}
curl --fail-with-body "https://api.floodgate.dev/v1/videos/$TASK_ID/content" \
  -H "Authorization: Bearer $FLOODGATE_API_KEY" --output video.mp4
```

Use Floodgate's `id` and `result_url` fields. Do not parse the upstream `request_id` or `video.url` envelope.

## Errors and billing

Billing uses verified output seconds at the selected resolution. Follow-ups keep the original task's group and price. Confirmed failures release reservations; missing final usage can leave settlement pending.

Check required fields and limits on `400`. An unfinished download returns `400`; an expired result returns `410`. Keep the existing task after a timeout or `submission_uncertain`. See [shared video errors](https://docs.floodgate.dev/videos.md#errors-and-retries).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.