Generate a video

Use grok-imagine-video-1.5 with a global API key and USD credit. Video generation is asynchronous: create once, save the task ID, poll, then download.

Create a task

Set BEEFAPI_KEY as shown in Quickstart, then run:

curl --fail-with-body https://global.beefapi.com/v1/videos \
  -H "Authorization: Bearer $BEEFAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-video-1.5",
    "prompt": "A paper boat floats across a puddle after rain, slow cinematic close-up",
    "duration": 4,
    "aspect_ratio": "16:9",
    "resolution": "720p",
    "generate_audio": false
  }' -o video-task.json

The response returns HTTP 200 with a task id and status: "queued". This means the task was accepted, not that the MP4 is ready. Save id from the response:

export VIDEO_ID="$(python3 -c 'import json; print(json.load(open("video-task.json"))["id"])')"

Poll until finished

curl --fail-with-body "https://global.beefapi.com/v1/videos/$VIDEO_ID" \
  -H "Authorization: Bearer $BEEFAPI_KEY"

Poll about every 5 seconds. Generation can take several minutes. A polling timeout does not mean the task failed; query the same ID again. Do not resubmit the create request to check progress.

Download the MP4

After completed:

curl --fail --location \
  "https://global.beefapi.com/v1/videos/$VIDEO_ID/content" \
  -H "Authorization: Bearer $BEEFAPI_KEY" \
  -o video.mp4

The download endpoint can redirect to a short-lived URL. --location follows it. Do not use --location-trusted, which could forward your API key to another host. If the download link expires, call the authenticated /content endpoint again. Download before sharing or archiving the file; do not publish the signed URL as a permanent link.

Animate one image

Send the following JSON to the same POST /v1/videos endpoint. Replace the URL with a publicly accessible HTTPS image:

{
  "model": "grok-imagine-video-1.5",
  "prompt": "Slowly move the camera forward as the leaves sway",
  "image": { "url": "https://example.com/first-frame.png" },
  "duration": 6,
  "aspect_ratio": "9:16",
  "resolution": "720p"
}

image also accepts a data URL. Set the aspect ratio explicitly: omitting it currently uses 16:9, even for portrait input.

Use multiple references

Use reference_images to guide subjects and style instead of locking a single first frame:

{
  "model": "grok-imagine-video-1.5",
  "prompt": "The character from <IMAGE_0> walks through the garden in <IMAGE_1>",
  "reference_images": [
    { "url": "https://example.com/character.png" },
    { "url": "https://example.com/garden.png" }
  ],
  "duration": 6,
  "resolution": "720p",
  "aspect_ratio": "16:9"
}

Reference mode accepts up to 7 images and is limited to 10 seconds and 720p. Do not combine image with reference_images.

Parameters and limits

Use preset voices with reference mode, not with a single first-frame image. Do not send stream: true or multipart uploads to this video endpoint. POST /v1/videos/generations is an alias for creation; use /v1/videos consistently in new integrations.

Video editing, remixing, and extension are not available through this global model. Do not switch to the old grok-imagine-video name for those operations.

Cost and failed tasks

The estimated charge is:

requested seconds × USD price per second at the chosen resolution
+ reference image count × USD price per reference image

A first-frame image counts as one reference image. Preset voices do not add a reference-image charge. Read live prices from Pricing or pricing.usd.json, including per_second_usd and reference_image_usd.

Credit is reserved when the task is accepted. A failed task releases its reservation when failure is recorded; a disconnected client alone does not cancel the task. See Billing.

For support, send the task ID, request ID, HTTP status, and error body. Never include your key or a complete signed download URL. See Errors.