API Reference

GrokImagine API

Create Grok Imagine image and video tasks with the model + input contract, then query results securely with a Bearer API key.

Request contract

model + input

Public endpoints

POST generate · GET status

Available models

Quick start

Choose a model and the example updates to a ready-to-run cURL request.

bash

1	curl -X POST 'https://grokimagineapi.com/v1/generate' \
2	-H 'Authorization: Bearer YOUR_API_KEY' \
3	-H 'Content-Type: application/json' \
4	-d '{
5	"model": "grok-imagine/text-to-image",
6	"input": {
7	"prompt": "A cinematic night market in the rain",
8	"aspect_ratio": "16:9"
9	}
10	}'

Authentication

The user API key is accepted only in the Authorization Bearer header. A token field in the body is ignored.

Keep API keys on your server. Manage API keys

http

1	Authorization: Bearer YOUR_API_KEY

Models and pricing

Each model has its own input parameters and a fixed credit cost per generation.

Model	Capability	Credits	input
grok-imagine/text-to-image	Text to image	5	prompt is required; aspect_ratio is optional.
grok-imagine/text-to-video	Text to video	24	prompt is required; aspect_ratio and mode are optional.
grok-imagine/image-to-video	Image to video	24	Provide image_urls, or task_id with an optional index. Do not provide both.
grok-imagine/upscale	Upscale	12	task_id from a compatible completed task is required.
grok-imagine/extend	Extend video	24	task_id and prompt are required; extend_times is "6" or "10".

Endpoints

POST/v1/generateCreate a generation task

Submit an asynchronous task and receive a task_id. Both model and input are required.

Body ParametersJSON

model:string

Allowed values:

input:object

Parameters for the selected model. The legacy flat prompt / mode / ratio contract is not accepted.

callback_url:optional string

A public HTTP(S) URL that receives the completion callback.

public:optional boolean

Allow the task result to appear in public showcases.

Request example

5 credits

json

1	{
2	"model": "grok-imagine/text-to-image",
3	"input": {
4	"prompt": "A cinematic night market in the rain",
5	"aspect_ratio": "16:9"
6	}
7	}

Response examples

Task created. Use task_id to query progress.

1	{
2	"code": 200,
3	"message": "success",
4	"data": {
5	"task_id": "task_example_id",
6	"status": "IN_PROGRESS"
7	}
8	}

GET/v1/statusQuery task status

Poll for results with the task_id returned by the generate endpoint.

Body ParametersJSON

task_id:string

The task ID returned by the generate endpoint.

Use the same Bearer API key that created the task. A missing task and a task owned by another key both return 404.

cURL

bash

1	curl 'https://grokimagineapi.com/v1/status?task_id=task_example_id' \
2	-H 'Authorization: Bearer YOUR_API_KEY'

Response examples

The task completed and resultUrls contains the output.

1	{
2	"code": 200,
3	"message": "success",
4	"data": {
5	"task_id": "task_example_id",
6	"status": "SUCCESS",
7	"consumed_credits": 5,
8	"error_message": null,
9	"created_at": "2026-07-24T05:00:00.000Z",
10	"request": {
11	"model": "grok-imagine/text-to-image",
12	"input": {
13	"prompt": "A cinematic night market in the rain"
14	}
15	},
16	"response": {
17	"resultUrls": [
18	"https://cdn.example.com/result.webp"
19	]
20	}
21	}
22	}

API Tester

Edit headers, query parameters, and JSON in the browser, then send a real request. Replace the example API key first.

Consola de APIPOST

URL Base

Endpoint

Encabezados

Cuerpo de la Petición

Error codes

The BFF preserves the upstream service's HTTP status and JSON response. Check both the HTTP status and response code.

HTTP	Meaning
400 Petición Incorrecta	Invalid model, input, callback_url, or task_id.
401 No autorizado	Bearer API key is missing or invalid.
402	The API key has insufficient credits.
404 No encontrado	No matching task exists for this API key.
429 Demasiadas peticiones	The service throttled the request.
500 Error interno del servidor	BFF or upstream service failure.