Grok AI Image Generator API documentation
Generate images with Grok AI Image Generator (xAI). Supports both text and image input modes.
Endpoints
| Contract item | Value |
|---|---|
| Capability | grok-ai-image-generator |
| Submit | POST https://vidmage.ai/api/v1/grok-ai-image-generator/submit |
| Query | POST https://vidmage.ai/api/v1/grok-ai-image-generator/query |
| Task identifier | taskId |
| Result field | imageUrl |
Authenticate with Authorization: Bearer YOUR_API_KEY. Save the task identifier and query the same capability. Use a stable Idempotency-Key for submission retries.
Product guide: Grok Image API
Parameters and input rules
| Field | Type | Required | Default | Meaning and limits |
|---|---|---|---|---|
prompt | string | Yes | Not specified | Text prompt describing the image to generate (max 20000 chars). For an unspecified character or figurine, use an original non-branded character with no logos and no resemblance to existing copyrighted superheroes; preserve any character the user explicitly names. Minimum characters: 1Maximum characters: 20000 |
imageUrl | string | No | Not specified | Optional input image URL. When provided, the task runs in image edit mode. In that mode, output ratio is inferred from the input image. |
aspectRatio | string | No | "1:1" | Output aspect ratio for modes that expose a ratio parameter. Ignored when imageUrl selects a mode whose ratio is inferred from the input image. Values: "1:1", "16:9", "9:16", "4:3", "3:4", "3:2", "2:3" |
resolution | string | No | "1k" | Output resolution tier. Ignored when imageUrl selects a mode that does not expose resolution. Values: "1k", "2k" |
numImages | string | No | "1" | Number of image variations to generate. Values: "1", "2", "3", "4" |
outputFormat | string | No | "jpeg" | Output image file format. Values: "jpeg", "png", "webp" |
text to image
These are public VidMage field names. The server maps them to provider fields. Input media selects the mode; use its limits together with the parameter table.
| Control | Mode-specific rule |
|---|---|
prompt | Required; 1–4000 characters. |
aspectRatio | Values: "1:1", "16:9", "9:16", "4:3", "3:4", "3:2", "2:3". Default: 1:1. |
resolution | Values: "1k", "2k". Default: 1k. |
numImages | Number of image variations to generate. Values: "1", "2", "3", "4"Default: "1" |
outputFormat | Output image file format. Values: "jpeg", "png", "webp"Default: "jpeg" |
image edit
These are public VidMage field names. The server maps them to provider fields. Input media selects the mode; use its limits together with the parameter table.
| Control | Mode-specific rule |
|---|---|
prompt | Required; 5–20000 characters. |
aspectRatio | Not used in this mode. |
resolution | Not used in this mode. |
imageUrl | Formats: jpg, jpeg, png, webp. |
Example request
{
"prompt": "A retro-futuristic electric motorcycle parked beneath neon signs on a rainy city street",
"aspectRatio": "1:1",
"resolution": "1k",
"numImages": "1",
"outputFormat": "jpeg"
}# Set VIDMAGE_IDEMPOTENCY_KEY to a unique value for this task; preserve it for transport retries.
curl -X POST "https://vidmage.ai/api/v1/grok-ai-image-generator/submit" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Idempotency-Key: ${VIDMAGE_IDEMPOTENCY_KEY}" \
-H "Content-Type: application/json" \
-d '{"prompt":"A retro-futuristic electric motorcycle parked beneath neon signs on a rainy city street","aspectRatio":"1:1","resolution":"1k","numImages":"1","outputFormat":"jpeg"}'
# -> { "success": true, "taskId": "...", "creditsConsumed": ... }Task results and recovery
URL of the generated image. Read imageUrl from the completed query response. Preserve taskId while the task is running.
curl -X POST "https://vidmage.ai/api/v1/grok-ai-image-generator/query" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "taskId": "TASK_ID_FROM_SUBMIT" }'
# -> { "success": true, "data": { "status": "...", "imageUrl": "https://..." } }Submission and task queries report the available task and usage information. A timeout is not a confirmed failure. Recover the existing task instead of resubmitting.
For face selection and error recovery, follow Task lifecycle. MCP uses the normalized taskId argument in get_task_result, including capabilities whose REST identifier is requestId.
Credits
| Component / option | Rate | Minimum |
|---|---|---|
| 1k | 10 credits / generation | — |
| 2k | 15 credits / generation | — |
Base charge is per generation at the selected resolution.
numImages multiplies the base charge by the selected output count.
Use the Playground or the MCP credit estimator for your exact inputs. Credits and billing.