Use the Grok Imagine Video API for 6, 10 or 15 second 720p tasks

The xplaai Grok Imagine Video API exposes grok-imagine-video through POST /v1/videos. The public contract generates 720p tasks in 6, 10 or 15 seconds, accepts landscape, portrait and square aspect ratios, and supports public reference-image URLs. JSON requests use URL fields, while local images use repeated multipart files.

Create an API key or review the current video documentation.

Grok Imagine Video contract at a glance

Do not send a generic pixel size. This model uses its fixed 720p resolution plus an aspect-ratio or direction field.

Create a Grok video task

export XPLA_API_KEY="your_api_key"

curl --request POST \
  --url https://xplaai.com/v1/videos \
  --header "Authorization: Bearer $XPLA_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "grok-imagine-video",
    "prompt": "a futuristic city with flying cars and a controlled cinematic camera move",
    "mode": "custom",
    "seconds": "10",
    "images": [
      "https://example.com/reference-1.jpg",
      "https://example.com/reference-2.jpg"
    ],
    "metadata": {
      "resolution": "720p",
      "aspectRatio": "16:9",
      "durationSeconds": 10
    }
  }'

When more than one duration alias is present, the values must agree. The example uses ten seconds in both places.

Choose 6, 10 or 15 seconds

The public contract accepts exactly three duration tiers:

• 6 seconds for a compact shot;
• 10 seconds for a longer single creative unit;
• 15 seconds for the longest supported task in this contract.

If duration is omitted, the current contract defaults to 15 seconds. It is still better to send the duration explicitly so the application, task record and user interface agree.

Do not round fractional input or replace an unsupported value silently. Reject it before submission.

Choose an aspect ratio or direction

Supported ratio values include:

• 16:9 for landscape video;
• 9:16 for vertical video;
• 1:1 for square video;
• 3:2 and 2:3 for additional horizontal or vertical compositions.

The contract also accepts common direction aliases such as landscape, portrait, square, horizontal and vertical. xplaai normalizes these to the model's direction values.

Use one representation in your application. If multiple aliases are sent, require them to resolve to the same orientation.

Add public reference images

For JSON requests, pass reachable public image URLs through one of these documented inputs:

• top-level image;
• top-level images;
• metadata.file_urls.

Multiple images are processed in array order. Use one input style per request instead of duplicating the same image across several aliases.

This main contract intentionally does not accept:

• input_reference;
• metadata.ref_images;
• stored-image IDs represented by those fields;
• a generic size value.

Those fields belong to different public contracts. Rejecting them prevents one model's parameters from being interpreted as another model's request.

Upload local reference images with multipart

Use repeated files fields for local images:

curl --request POST \
  --url https://xplaai.com/v1/videos \
  --header "Authorization: Bearer $XPLA_API_KEY" \
  --form "model=grok-imagine-video" \
  --form "prompt=animate the supplied product references" \
  --form "seconds=10" \
  --form "files=@./reference-1.jpg" \
  --form "files=@./reference-2.jpg"

Do not mix local multipart images with public-URL inputs in the same request. Validate file type and size in your own application before upload.

Use the optional mode field only with supported values

The current public contract documents these optional values:

• custom;
• normal;
• extremely-crazy;
• extremely-spicy-or-crazy.

Treat the mode as an enum. Do not pass an arbitrary UI label directly to the API.

Poll and retrieve the generated video

Store the task ID returned by the creation call. Poll:

GET https://xplaai.com/v1/videos/{task_id}
Authorization: Bearer $XPLA_API_KEY

When the task completes, retrieve the content:

GET https://xplaai.com/v1/videos/{task_id}/content
Authorization: Bearer $XPLA_API_KEY

Persist task state and make a failed generation distinguishable from a temporary polling error.

Main and backup model names are separate contracts

xplaai documentation may list separately named Grok backup models. They are not transparent fallbacks for grok-imagine-video.

If an application chooses one of those alternatives, it must:

1. send that exact public model name;
2. use that model's own documented input fields;
3. avoid carrying seconds, mode or metadata fields from the main contract when they are unsupported;
4. store the selected public name with the task.

This makes routing and request behavior explicit to the developer.

Validate the request in your application

Before submission, check:

• duration is 6, 10 or 15;
• resolution is not presented as a user-selectable value beyond 720p;
• the aspect ratio or direction is accepted;
• duration and ratio aliases agree;
• JSON reference images are public URLs;
• only one reference-input style is used;
• input_reference, metadata.ref_images and size are absent;
• mode is one of the documented enum values.

Compare Grok with other xplaai video contracts

• Veo 3.1 Fast provides a fixed eight-second contract with 720p/1080p and frame or ingredient references.
• Kling Video 3.0 supports 3–15 second generation and separates 720p standard from 1080p professional mode.
• The AI video API overview explains the shared asynchronous lifecycle.

For workflows that also coordinate product materials and several vertical outputs, explore the Batch Commerce Video Skill.

Frequently asked questions

What durations does Grok Imagine Video support?

The public contract accepts 6, 10 and 15 seconds. If omitted, duration currently defaults to 15 seconds.

What resolution does it generate?

grok-imagine-video uses a 720p contract. Do not send an arbitrary pixel-size field.

Which aspect ratios are accepted?

The documented ratios are 16:9, 9:16, 1:1, 3:2 and 2:3, plus supported direction aliases.

Can I use multiple reference images?

Yes. JSON requests can send public URLs through images or metadata.file_urls. Multipart requests can upload repeated files.

Which fields should I not send?

Do not send input_reference, metadata.ref_images or size to the main grok-imagine-video contract.

Do backup Grok models activate automatically?

No. Backup models have separate public names and contracts. The caller must select one explicitly.

Generate with Grok Imagine Video

Create an xplaai API key, submit a small task with an explicit duration and aspect ratio, and verify polling and content retrieval before production use.