Grok API
  1. Guides
Grok API
  • Getting started
    • Introduction
    • Models and Pricing
    • Billing
    • Consumption and Rate Limits
    • Usage Explorer
    • Free Credits
  • Guides
    • Asynchronous Requests
    • Image Understanding
    • Structured Outputs
    • Migration from Other Providers
    • Chat
      POST
    • Reasoning
      POST
    • Streaming Response
      POST
    • Deferred Chat Completions
      POST
    • Image Generations
      POST
    • Fingerprint
      POST
  1. Guides

Image Generations

POST
https://api.x.ai/v1/images/generations
Some of the models can provide image generation capabilities. You can provide some descriptions of the image you would like to generate, and let the model generate one or multiple pictures in the output.
If you're used to interacting with the chat/image-understanding models, the image generation is a bit different from them. You only need to send a prompt text in the request, instead of a list of messages with system/user/assistant roles. When you sent the prompt for image generation, your prompt will be revised by a chat model, and then sent to the image generation model.

Parameters#

n: Number of image(s) to generate (1-10, default to 1)
response_format: "url" or "b64_json". If "url" is specified, the response will return a url to the image(s) in data[index].url; if "b64_json" is specified, the response will return the image(s) in base64 encoded format in data[index].b64_json.
Note: quality, size or style are not supported by xAI API at the moment.
Request BodyExpand AllpromptstringrequiredPrompt for image generation.Show optional fields

Generate image#

The image generation is offered at a different endpoint https://api.x.ai/v1/images/generations from the chat and image-understanding models that share https://api.x.ai/v1/chat/completions. The endpoint is compatible with OpenAI SDK (but not with Anthropic SDK), so you can keep using the same base_url of https://api.x.ai/v1.
You can set "model": "grok-2-image" in the request body to use the model. The generated image will be in jpg format.
bashcurl -X 'POST' https://api.x.ai/v1/images/generations \ -H 'accept: application/json' \ -H 'Authorization: Bearer <API_KEY>' \ -H 'Content-Type: application/json' \ -d '{ -d '{ "model": "grok-2-image", "prompt": "A cat in a tree" }'
The Python and JavaScript examples will print out url of the image on xAI managed storage.
This is an example image generated from the above prompt:
1a9d1139d479c4e156cb73d26bd08e56_example-cat-in-tree.png

Base 64 JSON Output#

Instead of getting an image url by default, you can choose to get a base64 encoded image instead. To do so, you need to specify the response_format parameter to "b64_json".
You will get a b64_json field instead of url in the response image object.

Generating multiple images#

You can generate up to 10 images in one request by adding a parameter n in your request body. For example, to generate four images:

Revised prompt#

If you inspect the response object, you can see something similar to this:
{
    "data": [
        {
            "b64_json": "data:image/png;base64,...",
            "revised_prompt": "..."
        }
    ]
}
Before sending the prompt to the image generation model, the prompt will be revised by a chat model. The revised prompt from chat model will be used by image generation model to create the image, and returned in revised_prompt to the user.
To see the revised prompt with OpenAI SDK:
For example:
Input/OutputExample
prompt (in request body)A cat in a tree
revised_prompt (in response body)3D render of a gray cat with green eyes perched on a thick branch of a leafy tree, set in a suburban backyard during the day. The cat's fur is slightly ruffled by a gentle breeze, and it is looking directly at the viewer. The background features a sunny sky with a few clouds and other trees, creating a natural and serene environment. The scene is focused on the cat, with no distracting foreground elements, ensuring the cat remains the central subject of the image.
Request Request Example
Shell
JavaScript
Java
Swift
curl --location --request POST 'https://api.x.ai/v1/images/generations' \
--header 'Authorization: Bearer ' \
--header 'Content-Type: application/json' \
--data-raw '{
-d {'
Response Response Example
{}

Request

Header Params
Authorization
string 
required
Example:
Bearer {{XAI_API_KEY}}
Content-Type
string 
required
Example:
application/json
Body Params text/plain
Examples

Responses

🟢200Success
application/json
Body
object {0}
Modified at 2025-04-10 09:04:21
Previous
Deferred Chat Completions
Next
Fingerprint
Built with