Video Generation API Guide

The GetToken Video API provides Grok text-to-video and image-to-video generation. Video generation is asynchronous: create a task, query its status, and then retrieve the video file through the content endpoint.

Every request requires a dedicated service_type=video_api API key. Video keys are managed separately from text and image keys and cannot be used interchangeably.

Prerequisites

1. Sign in to the GetToken console.
2. Create a dedicated video API key from Console → Video API.
3. Review base_url and endpoint selection in base_url & endpoint selection.

The examples below use:

base_url: https://api.gettoken.dev

Endpoints

The current documented contract covers video generation, status queries, and content downloads. Video editing and extension are outside the scope of this guide.

Models and Input Modes

Image-to-video is an input mode for video generation. It does not expose a separate image generation API.

Generation Parameters

Supported Sizes

The current documented sizes do not include 480p.

Reference images may use JPEG, PNG, or WebP. A single image may be up to 60 MiB, and the complete request body may be up to 96 MiB. Public image URLs must be directly accessible over HTTPS.

Create a Text-to-Video Task

curl --fail https://api.gettoken.dev/v1/videos/generations \
  -H "Authorization: Bearer YOUR_VIDEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-video",
    "prompt": "A quiet city street after rain",
    "seconds": "8",
    "size": "1280x720"
  }'

Create an Image-to-Video Task

curl --fail https://api.gettoken.dev/v1/videos/generations \
  -H "Authorization: Bearer YOUR_VIDEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-video-1.5-preview",
    "prompt": "Move the subject forward while the camera slowly pushes in",
    "seconds": "8",
    "size": "1280x720",
    "image_url": "https://example.com/reference.webp"
  }'

After the task is created, prefer the top-level id from the response and use it as task_id in subsequent requests. Compatibility responses may also include request_id or task_id.

Query Task Status

curl --fail \
  -H "Authorization: Bearer YOUR_VIDEO_API_KEY" \
  https://api.gettoken.dev/v1/videos/TASK_ID

The documented statuses are:

Poll every 5–10 seconds. A five-minute overall client timeout is a reasonable default.

When a task is complete, the status response may look like this:

{
  "id": "TASK_ID",
  "status": "done",
  "video": {
    "url": "/v1/videos/TASK_ID/content",
    "duration": 8
  }
}

video.url is an authenticated content endpoint, not video bytes embedded in the JSON response. The client must make a separate HTTP request with its API key to retrieve the file.

Download Video Through the Content Endpoint

The status endpoint returns task metadata, not the video file. After the task reaches done, you must request /v1/videos/{task_id}/content to retrieve the video bytes.

Use the same video API key that created the task:

curl --fail \
  -H "Authorization: Bearer YOUR_VIDEO_API_KEY" \
  https://api.gettoken.dev/v1/videos/TASK_ID/content \
  --output grok-video.mp4

Do not depend directly on an upstream signed URL from the status response. The GetToken content endpoint retrieves the official video server-side and returns it as a video/mp4 byte stream. This keeps authentication consistent and avoids requiring the client to connect directly to the upstream video host.

The content endpoint supports HTTP Range. Players, resumable downloads, and segmented clients may send a Range header:

curl --fail \
  -H "Authorization: Bearer YOUR_VIDEO_API_KEY" \
  -H "Range: bytes=0-" \
  https://api.gettoken.dev/v1/videos/TASK_ID/content \
  --output grok-video.mp4

The response may include:

• Content-Type: video/mp4
• Accept-Ranges: bytes
• Content-Length
• Content-Range for partial responses

Status queries and content downloads are not billed again. The content endpoint still validates task ownership and API key permissions, so Authorization is required and another key cannot be substituted.

Pricing and Retention

Video is billed by actual generated duration. See Console → Video API for real-time quotes. You can estimate the cost by model, quality, and duration before submitting, while the usage record remains the final billing reference.

GetToken retains video results for 24 hours. After a task reaches done, promptly save the result to your own storage through the content endpoint.

Notes

• If a creation response is uncertain, do not automatically resubmit through another account; doing so may create and bill duplicate tasks.
• grok-imagine-video-1.5-preview requires image_url.
• Status and content requests must use the same video API key that created the task.
• Cancellation, batch generation, and multiple reference images are not currently available.