Grok video API

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.

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

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"}'

{"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.

curl --fail-with-body "https://api.floodgate.dev/v1/videos/$TASK_ID" \
  -H "Authorization: Bearer $FLOODGATE_API_KEY"

{"id":"task_example","status":"completed","progress":100,"result_url":"/v1/videos/task_example/content"}

{"id":"task_example","status":"failed","error":{"code":"task_failed","message":"Video generation failed"}}

After completed, download with authentication:

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.

Getting started

Coding tools

API reference

Operations and limits

Submit

Poll and download

Errors and billing

​Operations and limits

​Submit

​Poll and download

​Errors and billing

Operations and limits

Submit

Poll and download

Errors and billing