Using the Grok Imagine API: Images, Video and Code (2026)

The Grok Imagine API lets your code call xAI’s Grok Imagine models directly: send a text prompt and get back a set of image variations, or send a start frame and get back a short video clip. This guide covers which models exist, what each request costs in credits, working curl and Python code, a worked example, and the mistakes that waste money in the first week.

A quick definition first. An API (application programming interface) is a way for a program to use a service over HTTP instead of a person clicking buttons in an app. In practice you send a JSON request to an endpoint, receive a job id, and fetch the finished file when it is ready.

What is the Grok Imagine API?

Grok Imagine is xAI’s family of image and video generation models, the same family behind the Imagine feature in the Grok app. The Grok Imagine API exposes those models to developers so you can generate media inside your own product, script, or pipeline. On Unicorn API they sit next to image, video, audio and chat models from other labs, so one API key and one credit balance covers all of them.

Three things set Grok Imagine apart from a typical text-to-image model (a model that turns a written prompt into a picture):

• Batches by default. The image model returns 6 variations per text prompt, or 2 when you attach reference images. That makes it good for exploring a concept quickly.
• Low per-second video pricing. Both video models charge the same rate per second of output, starting at 2.4 credits per second at 480p.
• A separate upscale step. You can render cheaply, then upscale only the outputs you keep.

All media models on the platform are asynchronous. Your request creates a job, generation runs in the background, and you poll the job until its status is succeeded. This matters for video, which takes longer than images, and especially for Video 1.5, which can be busy at peak times.

Which Grok Imagine models can you call?

There are four models in the family. Each has its own model id, which is the string you pass in the model field.

Model	Model id	What it does	Input fields	Options
Grok Imagine	grok-imagine	Text-to-image, optional reference images	prompt, n, ref_images, aspect_ratio	1:1, 2:3, 3:2, 16:9, 9:16
Grok Imagine Video 1.5	grok-imagine-video-1-5-preview	Image-to-video only: animates a start frame	image, prompt, duration, resolution, aspect_ratio, mode	1-15 s; 480p, 720p, 1080p; auto, 1:1, 16:9, 9:16, 3:2, 2:3
Grok Imagine Video 1.0	grok-imagine/image-to-video	Text-to-video or image-to-video	image, prompt, duration, resolution, aspect_ratio, mode	6-30 s; 480p, 720p, 1080p; 1:1, 16:9, 9:16, 3:2, 2:3
Grok Imagine Upscale	grok-imagine-upscale	Upscales an earlier generation	task_id, resolution	720p, 1080p

Video 1.5 or Video 1.0?

Both charge the same per-second rate, so the choice is about inputs and length. Video 1.5 is the newer model, released in June 2026, and it is image-to-video only: you must give it a start frame, and clips run from 1 to 15 seconds. Pick it when you already have the first frame, or generate one with the image model. Video 1.0 accepts a plain text prompt as well as a start frame, and runs from 6 to 30 seconds. Pick it for text-to-video, for clips longer than 15 seconds, or as a fallback when 1.5 is busy. For a broader look at length and cost trade-offs, see our post on AI video generator tools.

What the upscaler is for

Upscaling, also called super-resolution, means producing a higher-resolution version of an existing output. The upscaler takes a task_id (the id of an earlier job) and a target resolution of 720p or 1080p. Check the API documentation for which source jobs it accepts before you build a pipeline around it.

Grok Imagine API pricing in credits

Every request is priced in credits. On a monthly plan, credits cost $0.01 each: Starter is $25, Creator $50, Studio $100 and Pro $200 per month. Top-up credits cost $0.015 each and never expire. The table below uses the listed credit prices and converts them to dollars at both rates. Full details are on the pricing page.

Request	Credits	Plan ($0.01/credit)	Top-up ($0.015/credit)
Grok Imagine, per image	4	$0.04	$0.06
Video, 10 s at 480p	24	$0.24	$0.36
Video, 6 s at 720p	27	$0.27	$0.405
Video, 10 s at 720p	45	$0.45	$0.675
Video, 10 s at 1080p	80	$0.80	$1.20
Video, 15 s at 1080p	120	$1.20	$1.80
Video 1.0 only, 30 s at 1080p	240	$2.40	$3.60
Upscale to 720p	10	$0.10	$0.15
Upscale to 1080p	20	$0.20	$0.30

The video rates are 2.4 credits per second at 480p, 4.5 at 720p and 8 at 1080p, for both video models. So 1080p costs a little over 3x as much as 480p for the same clip length. Charges are rounded up to whole credits per output, which only matters for odd durations at 480p and 720p: a 5-second 720p clip is listed at 22.5 credits and charged as 23.

For images, the listed price is 4 credits per image, multiplied by n when you set it. Because one call can return several variations, ask for a quote before you run a large batch. The price endpoint, POST /v1/models/price, returns the exact cost of a request before you run it. Send it the same model and input you plan to submit to /v1/jobs, and it tells you what you will be charged.

For budgeting, the Starter plan’s 2,500 credits cover 625 images at 4 credits each, or about 55 ten-second clips at 720p.

How to call the Grok Imagine API

Every call to the Grok Imagine API follows the same three-step pattern: create a job, poll it, download the result.

Get a key

Create a key on the API keys page and export it in your shell so it never ends up in your source code:

export UNICORN_API_KEY="your-key-here"

Generate images with curl

curl -X POST https://api.unicornapi.net/v1/jobs \
  -H "Authorization: Bearer $UNICORN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine",
    "input": {
      "prompt": "A red fox resting in a snowy forest at dawn, soft light, highly detailed",
      "aspect_ratio": "16:9"
    }
  }'

The response includes the job id. Poll it until the status is succeeded:

curl https://api.unicornapi.net/v1/jobs/JOB_ID \
  -H "Authorization: Bearer $UNICORN_API_KEY"

The finished file is at outputs[0].url. Grok Imagine returns several variations, so loop over the whole outputs array to collect all of them.

Image to video in Python

This script is a complete Grok Imagine API Python example. It generates a batch of images, takes the first one as a start frame, and animates it with Video 1.5. It only needs the requests library.

import os
import time
import requests

BASE = "https://api.unicornapi.net"
HEADERS = {
    "Authorization": f"Bearer {os.environ['UNICORN_API_KEY']}",
    "Content-Type": "application/json",
}


def run_job(model, input_data, poll_every=5, timeout=900):
    """Create a job, poll until it succeeds, return the finished job."""
    resp = requests.post(
        f"{BASE}/v1/jobs",
        headers=HEADERS,
        json={"model": model, "input": input_data},
    )
    resp.raise_for_status()
    job_id = resp.json()["id"]

    deadline = time.time() + timeout
    while time.time() < deadline:
        job = requests.get(f"{BASE}/v1/jobs/{job_id}", headers=HEADERS)
        job.raise_for_status()
        job = job.json()
        if job["status"] == "succeeded":
            return job
        if job["status"] == "failed":
            raise RuntimeError(f"Job {job_id} failed: {job}")
        time.sleep(poll_every)
    raise TimeoutError(f"Job {job_id} did not finish in {timeout} s")


# 1. Generate image variations (4 credits per image)
images = run_job("grok-imagine", {
    "prompt": "A ceramic coffee mug on a wooden table by a window, "
              "morning light, steam rising, product photography",
    "aspect_ratio": "16:9",
})
urls = [o["url"] for o in images["outputs"]]
print("Variations:", *urls, sep="\n")

# 2. Animate the first variation: 5 s at 480p (12 credits)
video = run_job("grok-imagine-video-1-5-preview", {
    "image": urls[0],
    "prompt": "Steam curls slowly upward, light shifts gently, "
              "camera pushes in a little",
    "duration": 5,
    "resolution": "480p",
    "aspect_ratio": "16:9",
})
print("Video:", video["outputs"][0]["url"])

A few notes on the code. The timeout is generous because video jobs take longer than images and Video 1.5 can queue at busy times. The polling interval of 5 seconds is plenty: polling every few hundred milliseconds does not make the job finish sooner. See the documentation for the full list of job states and error responses.

If you work in Cursor, Claude Code or another coding agent, you can also let the agent call these models directly through MCP. The setup is on the agents page.

Worked example: from product shot to a 10-second clip

Here is a realistic job: a small brand wants a 10-second looping clip of its coffee mug for a landing page. This is how to do it with the Grok Imagine API without burning credits on takes you throw away.

1. Explore stills. Run the image model with a 16:9 aspect ratio and a product-photography prompt. You get a batch of variations at 4 credits per image. If none fit, adjust the prompt rather than re-running the same one; the variations already show you the range the model gives for that wording.
2. Pick a start frame. Choose the variation with the cleanest composition. Leave space around the subject, since motion and camera moves need room.
3. Test motion at 480p. Animate the chosen frame with Video 1.5 for 5 seconds at 480p. That costs 12 credits, or $0.12 on a plan. Watch for warped handles, flickering text and steam that behaves like smoke.
4. Render the keeper. Once the motion prompt works, re-run it at 10 seconds and 720p for 45 credits. The motion will not be identical to the test, so keep the prompt specific: name the camera move, the speed and what should stay still.
5. Decide on 1080p. A native 10-second 1080p render costs 80 credits. Upscaling a 720p result to 1080p costs 20, so 720p plus upscale is 65 credits. The upscaler adds pixels to an existing video rather than rendering new detail, so compare both options on your own footage before you standardise on one.

Total for the video steps: 12 for the test plus 45 for the final, plus 20 if you upscale, so 77 credits including upscaling. That is $0.77 on a monthly plan, and you knew the cost of each step before you ran it.

If you need longer than 15 seconds, switch the final render to Video 1.0, which goes up to 30 seconds at the same per-second rate. For more on chaining stills into motion, see our guide to image to video AI.

Grok Imagine vs other image models

Grok Imagine is not the only image model at this price point, and the right choice depends on the job. Here is how it compares with two other popular options in the same catalog.

Model	Price	Best at	Reference images	Aspect ratios
Grok Imagine	4 credits per image	Exploring a concept: 6 variations per prompt	Yes (returns 2 variations with refs)	1:1, 2:3, 3:2, 16:9, 9:16
Nano Banana 2 Lite	4 credits per image	Fast 1K images and edits, cheapest Gemini image model	Up to 10	16:9, 1:1, 9:16, 21:9, 4:3, 3:2, 2:3
GPT Image 1.5	3 low, 4 medium, 22 high	Prompt adherence, legible text, transparent backgrounds	Up to 4	1:1, 3:2, 2:3

Practical guidance:

• Pick Grok Imagine when you want many options from one prompt, or when the still is a start frame for a Grok Imagine video.
• Pick Nano Banana 2 Lite for editing with many reference images, or for ultrawide 21:9 and 4:3 formats that Grok Imagine does not offer.
• Pick GPT Image 1.5 when the image contains words that must be spelled correctly, such as packaging, posters or UI mockups, or when you need a transparent background.

Since all three share one key and one balance, you can route each request to the best model without new accounts. Try them side by side in the browser playground, or browse the full model catalog.

Grok Imagine app vs API: free use and spicy mode

Many searches about Grok Imagine are really about the consumer app: whether it is still free, what the daily limits are, and what “spicy mode” does. These are app questions, and the answers do not carry over to the API.

Is Grok Imagine no longer free?

The Grok app has offered free generations with daily caps, and those caps have changed over time, which is why “Grok Imagine no longer free” threads keep appearing on Reddit. We track the current app limits in our post on the Grok Imagine limit. The Grok Imagine API is not free: every request spends credits. In exchange, there is no app-style daily cap stopping a batch job halfway, and you get an exact price before every request.

What about spicy mode?

Spicy mode is a setting in the consumer app. It is not a parameter of the API. The input fields for the Grok Imagine models are the ones listed in the table above, and none of them switches content filtering off. Expect content policies to apply to every request, and build your product around prompts suited to a general audience. If a workflow depends on app-only behaviour, it is fragile: app settings change without notice, while model ids and request shapes are what your code relies on.

Common mistakes with the Grok Imagine API

These are the errors we see most often from developers starting out with the Grok Imagine API.

1. Sending a text-only prompt to Video 1.5. Video 1.5 is image-to-video only. Always include a start frame in the image field. For pure text-to-video, use Video 1.0.
2. Asking Video 1.0 for a short clip. Video 1.0 starts at 6 seconds. For a 3-second loop, use Video 1.5.
3. Forgetting that n multiplies the cost. The image price is per image and scales with n. Quote large batches with POST /v1/models/price first.
4. Rendering at 1080p before the prompt works. At 8 credits per second, every failed 1080p take costs over 3x a 480p test. Test low, then render high.
5. Using an unsupported aspect ratio. Grok Imagine images support 1:1, 2:3, 3:2, 16:9 and 9:16. Requests for 21:9 or 4:3 need a different model, such as Nano Banana 2 Lite.
6. No timeout or retry plan for busy periods. Video 1.5 can be busy at peak times. Set a polling timeout and fall back to Video 1.0, which shares the same per-second rate, when a deadline matters.
7. Relying on job URLs as permanent storage. Download outputs and store them in your own bucket or CDN rather than serving the job URL to users long-term.
8. Vague motion prompts. “Make it move” gives random motion. Name the camera move, the speed, and what must stay still, such as “camera pushes in slowly, mug stays centred, only steam moves”.

Get those right and the Grok Imagine API becomes a cheap, predictable building block: stills at 4 credits each, video priced by the second, and an upscaler for the takes worth keeping. Create a key, run the Python script above with your own prompt, and check the price endpoint before you scale up.