Grok Video Format¶

This document explains how to call xAI's Grok series models through New-API. Currently, video generation is supported, and the billing logic fully supports dynamic parameters.

1. General Request Information¶

Base URL: https://api-cs-al.naci-tech.com/v1
Authentication: Include Authorization: Bearer $API_KEY header
Content-Type: Content-Type: application/json

About metadata passthrough

New-API performs fully transparent passthrough of the metadata object in the request body. Any advanced parameters natively supported by xAI but not listed in the standard field table (such as seed, negative_prompt, aspect_ratio, fps, etc.) can be passed directly within metadata.

2. Video Generation Model (grok-imagine-video)¶

Supports features such as Text-to-Video, Image-to-Video, and Video-to-Video (Remix).

Transparent Passthrough (Key Point)

New-API performs fully transparent passthrough of the metadata object. Many native xAI parameters (e.g., aspect_ratio, seed, fps), as well as some "mode switch" fields in this document (e.g., resolution, video), are recommended to be placed in metadata.

API Endpoint¶

Create video task: POST /v1/video/generations

Basic Request Parameters¶

Parameter	Type	Required	Description
`model`	string	Yes	Fixed as `grok-imagine-video`
`prompt`	string	Yes	Text description of the video content
`duration`	integer	No	Video duration (seconds), valid only for Text/Image-to-Video, range 1–15, default `5`. Not available in Video Editing (Remix) mode; output duration matches the input video and is capped at 8.7 seconds.
`metadata`	object	No	Additional metadata (passthrough object), supports fields in the table below
`images`	array	No	Input image array, used for Image-to-Video mode
`image`	string	No	Input single image: can be a public image URL or a base64 data URI (e.g., `data:image/jpeg;base64,...`), choice between `images` or `image`.

Metadata Fields¶

Field Name	Type	Description
`resolution`	string	Output resolution: `720p` (High Definition), `480p` (Standard Definition, default, faster processing). Valid only for Text/Image-to-Video; not supported in video editing mode, output resolution matches input video and is capped at 720p.
`aspect_ratio`	string	Aspect ratio, valid only for Text/Image-to-Video. Options: `1:1`, `16:9` (default), `9:16`, `4:3`, `3:4`, `3:2`, `2:3`. When not provided for Image-to-Video, it defaults to the input image's ratio; not supported in video editing mode, output matches input video.
`video`	string	Input video URL. Providing this field triggers Video-to-Video (Remix) mode.

Example Request 1: Text + Image to Video¶

curl -X POST https://api-cs-al.naci-tech.com/v1/video/generations \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-video",
    "prompt": "A cyberpunk city in the clouds",
    "duration": 5,
    "image": "https://example.com/init_frame.png",
    "metadata": {
      "resolution": "720p"
    }
  }'

Example Request 2: Video-to-Video (Remix)¶

To redraw or modify an existing video, pass the video parameter in metadata.

curl -X POST https://api-cs-al.naci-tech.com/v1/video/generations \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-video",
    "prompt": "Turn the video style into a Van Gogh oil painting",
    "metadata": {
      "video": "https://example.com/original_video.mp4"
    }
  }'

3. Query Video Task Status¶

After a successful submission, an id (i.e., task_id) will be returned, which can be used to query the generation progress and result using the following interfaces:

GET /v1/videos/<id>
GET /v1/video/generations/<id>

Query Examples (curl)¶

Example 1: Query via `GET /v1/videos/<id>` (OpenAI style)¶

curl -X GET "https://api-cs-al.naci-tech.com/v1/videos/xai-task-12345" \
  -H "Authorization: Bearer $API_KEY"

Example 2: Query via `GET /v1/video/generations/<id>` (agtcloud style)¶

curl -X GET "https://api-cs-al.naci-tech.com/v1/video/generations/xai-task-12345" \
  -H "Authorization: Bearer $API_KEY"

Response Field Description (Standard OpenAI Video Format)¶

status: queued (in queue), in_progress (generating), completed (success), failed (failure)
progress: Task completion progress (0-100)
metadata.url: Direct link to the generated video after completion
error: Error information object if the task fails

Typical Response Example¶

{
  "id": "xai-task-12345",
  "object": "video",
  "model": "grok-imagine-video",
  "status": "completed",
  "progress": 100,
  "created_at": 1718300000,
  "metadata": {
    "url": "https://api-cs-al.naci-tech.com/v1/videos/xai-task-12345/content"
  }
}

4. Get Video File Content (Proxy)¶

If you need to retrieve the video file stream directly (e.g., for playback in a frontend <video> tag), you can use the following proxy interface:

Request Path: GET /v1/videos/<id>/content

Request Example (curl)¶

curl -X GET "https://api-cs-al.naci-tech.com/v1/videos/xai-task-12345/content" \
  -H "Authorization: Bearer $API_KEY" \
  --output "output_video.mp4"

Description¶

This interface performs direct transparent passthrough of the upstream video file's binary stream.
Includes the correct Content-Type (e.g., video/mp4) and cache control headers.
Permissions: Also requires a valid Authorization token.

5. Billing Logic Description (Transparent Billing)¶

New-API dynamically calculates credit consumption based on the parameters you upload (including some parameters passed through in metadata). Therefore, it is recommended to record metadata on the business side for easier reconciliation and reproduction.