Create a Grok Imagine Video video

Create Grok Imagine Video video tasks via unified POST /v1/videos. Model capabilities are subject to the actual callable range of the current Tikway gateway.

Model	Resolution	Duration	Supported Modes	Audio	Reference Limitations
grok-imagine-video-1.5-fast	480p / 720p	6–30 seconds	Vincent, up to 7 picture reference, first and last frames	Upstream defaults to sound; the current unified field cannot be turned off	Unofficial high-speed channel
grok-imagine-video-1.5	480p / 720p / 1080p	1–15 seconds	The current gateway requires exactly 1 picture; can bring up to 3 preset sounds	Default is sound; the current unified field cannot be turned off	Does not support the last frame
grok-imagine-video	480p / 720p	Generate 1–15 seconds; extend 1–10 seconds	Vincent, multi-image reference, video extension	Upstream has sound by default; the current unified field cannot be turned off	End frame is not supported

Source: xAI Video Generation Documentation. The difference between the official website capabilities and the current unopened capabilities of the gateway can be found in this audit report.

POST https://api.tikway.ai/v1/videos

cURL

Fast text to video

curl --request POST \ --url https://api.tikway.ai/v1/videos \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data ' { "model": "grok-imagine-video-1.5-fast", "prompt": "A golden retriever runs on the beach at sunset. The camera follows smoothly, and the picture has a natural and delicate film quality.", "duration": 10, "resolution": "720p", "aspect_ratio": "16:9" } '

202

{
  "id": "9552de3d-171f-4cca-b492-7baa56523239",
  "status": "pending",
  "polling_url": "https://api.tikway.ai/v1/videos/9552de3d-171f-4cca-b492-7baa56523239"
}

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Create a Grok Imagine Video video task. Parameters are narrowed according to the current Tikway gateway capabilities; for differences between models, see operation description and x-model-capabilities.

model · enum<string> · required

Grok Imagine Video Model ID.

Available options: grok-imagine-video-1.5, grok-imagine-video

prompt · string · required

Video generation or editing prompt words.

Minimum string length: 1

duration · integer

Model related: 6–30 seconds for 1.5 Fast; 1–15 seconds for 1.5 and Basic; 1–10 seconds for Basic video extension.

Required range: 1 <= x <= 30

aspect_ratio · enum<string>

Video aspect ratio. When producing videos, some models will automatically determine the proportions based on the input material.

Available options: 2:3, 3:2, 1:1, 9:16, 16:9

resolution · enum<string>

Output resolution. Available values ​​for different models or modes are shown in the model capabilities table.

Available options: 480p, 720p, 1080p

frame_images · object[]

1.5 Fast supports the first and last frames; 1.5 and the basic version can only use one picture as the first frame and cannot pass last_frame.

Maximum array length: 2

Hide child attributes

frame_images. type · enum<string> · required

Reference frame position.

Available options: first_frame, last_frame

frame_images. image_url · string<uri> · required

Reference image URL string.

Minimum string length: 1

input_references · object[]

The maximum number of picture references is 7; 1.5 current routing requires exactly 1 picture. The video is only available as an extension for the basic version. 1.5 Up to 3 reference_audio can be transmitted, and the default voice_id is filled in reference_voice; audio_url is only used as a unified protocol placeholder.

Maximum array length: 7

Option 1

Option 2

Option 3

Hide child attributes

input_references. image_url · string<uri> · required

Image URL string.

Minimum string length: 1

input_references. type · enum<string>

Optional. Material type; if provided, must be consistent with the corresponding URL field.

Available options: image_url, video_url, audio_url

input_references. role · enum<string>

Material usage. When omitted, normal reference material is inferred from the URL field.

Available options: reference_image, source_video, first_clip, reference_audio

input_references. video_url · string<uri>

Video URL string.

Minimum string length: 1

input_references. audio_url · string<uri>

Audio URL string.

Minimum string length: 1

input_references. reference_voice · string

Preset patch ID; only used by some models that support patch references.

Minimum string length: 1

callback_url · string<uri>

User task callback address. Called by Tikway after the task status changes, it is not directly passed to the model upstream.

Pattern: ^https://

extra_body · object

Grok TTAPI extension parameters. It is recommended to use unified fields first.

Response

202 - application/json

POST /v1/videos Response parameters after the video task is successfully created. The interface returns HTTP 202.

id · string · required

The unique identifier of the video generation task, used for subsequent query of task status.

Minimum string length: 1

Example:

"9552de3d-171f-4cca-b492-7baa56523239"

status · enum<string> · required

Task creation status. pending means that the task has been created and is waiting for submission; queue means that the task has entered the generation queue.

Available options: pending, queue

Example:

"queue"

polling_url · string<uri> · required

Video task query address, the client can poll the task status through GET request.

Pattern: ^https://

Example:

"https://api.example.com/v1/videos/9552de3d-171f-4cca-b492-7baa56523239"