Grok Imagine Image Text to Image API

xai/grok-imagine-image/text-to-image

5 aspect ratios

Grok Imagine Image Text to Image turns text into realistic or stylized images, combining subject detail with lighting and composition. Written descriptions guide the scene’s appearance, while five aspect ratios fit portraits, product concepts, and social visuals.

Get API Key

Input

Prompt

629/5000

Size

OutputReady

Continue with

Grok Imagine Image Edit Grok Imagine Video Text to Video Grok Imagine Video Image to Video

Examples

An intimate documentary photograph inside a small old vinyl record restoration room. A young adult male technician with a silver buzz cut and round face gently holds a carbon-fiber record brush against a black vinyl record lying flat on a workbench. His other hand steadies the outer edge. Frame his face, shoulders and both hands together, believable fingers and a single brush. Slanting side-window daylight reveals the fine grooves and a few dust particles, with worn wooden shelves softly out of focus. Quiet concentration, natural skin texture, warm understated color, candid rather than posed. No readable labels, branding, promotional graphics, or watermark.

An eye-level wildlife photograph of one Eurasian lynx peeking around the right side of a snow-covered fallen tree trunk in a boreal conifer forest. Show its head and forequarters with accurate feline anatomy, prominent black ear tufts, amber eyes, white cheek ruff and naturally damp whiskers. Its paws stand on undisturbed snow. Soft cool morning light, fine individual fur strands, a small amount of distant mist between spruce trunks, softly blurred background, realistic wildlife observation. No other animals, people, text, logos, or watermark.

REST API

Quick Start

Submit a request, save task_id, and retrieve the generated file when the task finishes.

Connect to Vidgo API

Store your API key on the server and send Authorization: Bearer VIDGO_API_KEY.

Endpoint: POSThttps://api.vidgo.ai/api/generate/submit
Authentication: Authorization: Bearer VIDGO_API_KEY

Submit a generation task

Set model and callback_url at the request root. Place the following fields inside input.

Submit request

curl --request POST \
  --url "https://api.vidgo.ai/api/generate/submit" \
  --header "Authorization: Bearer $VIDGO_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "model": "xai/grok-imagine-image/text-to-image",
  "input": {
    "prompt": "A ceramic cup on a wooden table, soft window light, a plain blue background.",
    "size": "1:1"
  }
}'

Retrieve the result

Poll every 2–5 seconds while status is not_started or running. Stop at finished or failed.

Track status

GET https://api.vidgo.ai/api/generate/status/{task_id}

Poll every 2–5 seconds while status is not_started or running. Stop at finished or failed.

not_startedrunningfinishedfailed

Submit response

{
  "code": 200,
  "data": {
    "task_id": "example-task-id",
    "status": "not_started",
    "created_time": "2026-09-27T10:00:00Z"
  }
}

Finished response

{
  "code": 200,
  "data": {
    "task_id": "example-task-id",
    "status": "finished",
    "created_time": "2026-09-27T10:00:00Z",
    "files": [
      {
        "file_url": "https://example.com/result.png",
        "file_type": "image"
      }
    ]
  }
}

Complete polling example

Submit a request, save task_id, and retrieve the generated file when the task finishes.

Complete polling example

set -euo pipefail
: "${VIDGO_API_KEY:?Set VIDGO_API_KEY in your environment}"

REQUEST_BODY=$(cat <<'JSON'
{
  "model": "xai/grok-imagine-image/text-to-image",
  "input": {
    "prompt": "A ceramic cup on a wooden table, soft window light, a plain blue background.",
    "size": "1:1"
  }
}
JSON
)

SUBMIT_RESPONSE=$(curl --silent --show-error --fail-with-body \
  --request POST \
  --url "https://api.vidgo.ai/api/generate/submit" \
  --header "Authorization: Bearer $VIDGO_API_KEY" \
  --header "Content-Type: application/json" \
  --data "$REQUEST_BODY")

TASK_ID=$(printf '%s' "$SUBMIT_RESPONSE" | jq -r '.data.task_id // .task_id // empty')
if [ -z "$TASK_ID" ]; then
  printf 'Submit response did not include task_id:
%s
' "$SUBMIT_RESPONSE" >&2
  exit 1
fi

while true; do
  STATUS_RESPONSE=$(curl --silent --show-error --fail-with-body \
    --url "https://api.vidgo.ai/api/generate/status/$TASK_ID" \
    --header "Authorization: Bearer $VIDGO_API_KEY")
  STATUS=$(printf '%s' "$STATUS_RESPONSE" | jq -r '.data.status // .status // empty')

  case "$STATUS" in
    finished)
      printf '%s' "$STATUS_RESPONSE" | jq -r '(.data.files // .files // [])[]?.file_url'
      break
      ;;
    failed)
      printf '%s' "$STATUS_RESPONSE" | jq -r '.data.error_message // .error_message // "Generation failed"' >&2
      exit 1
      ;;
    not_started|running)
      sleep 2
      ;;
    *)
      printf 'Unexpected task status: %s
' "$STATUS" >&2
      exit 1
      ;;
  esac
done

Request Parameters

Set model and callback_url at the request root. Place the following fields inside input.

Field	Type	Required	Default	Description
input.prompt	string	Yes	–	Describe the desired image and visual style. Enter 1–5,000 characters.
input.size	string	No	–	Choose 1:1, 2:3, 3:2, 16:9, or 9:16.

Response Fields

The submit response returns task_id. The status response returns generated files or the task error.

Field	Type	Description
code	integer	Response code; 0 or 200 indicates success.
data.task_id	string	Task identifier for status queries.
data.status	string	not_started, running, finished, failed
data.created_time	string	Task creation timestamp.
data.files[].file_url	string	URL of the generated file.
data.files[].file_type	string	image
data.error_message	string \| null	Reason for a failed task.

Task Lifecycle

Poll every 2–5 seconds while status is not_started or running. Stop at finished or failed.

not_started
Accepted and queued.
running
Generation in progress.
finished
Read the generated files.
failed
Read error_message and stop polling.

Polling and Errors

PollingPoll every 2–5 seconds while status is not_started or running. Stop at finished or failed.
Retry a status queryBack off on 429 and temporary server errors, then query the same task_id.
CallbackProvide a public callback_url at the request root to receive completion notifications.

Model Specifications

Specification	Value	Details
Input	Prompt	Describe the desired image and visual style. Enter 1–5,000 characters.
Output	image	Generated image.
size	1:1 · 2:3 · 3:2 · 16:9 · 9:16	Choose 1:1, 2:3, 3:2, 16:9, or 9:16.

View the Grok Imagine Image Text to Image API docs

Grok Imagine Image Text to Image

Grok Imagine Image Text to Image is xAI’s model for creating images from written descriptions, spanning photographic scenes and illustrated styles. It interprets the subject, setting, lighting, and composition together, so a creative brief can become a portrait, a product concept, or a scene illustration. Five output aspect ratios let the same creative direction fit square posts, portrait layouts, and widescreen compositions.

Why Choose Grok Imagine Image Text to Image?

Realistic and illustrated directionsExplore a photographic scene or an illustrated treatment through the same text input, making it useful for comparing visual directions early in a project.
A scene built from the briefSubject, surroundings, light, and framing are expressed together in the prompt, giving a concept a visual form before a reference image exists.
Composition for the intended placementSquare, portrait, and landscape outputs give portraits, social posts, and scene concepts a frame suited to their destination.

Parameters

Parameter	Requirement	Description
prompt	Required	Describe the desired image and visual style. Enter 1–5,000 characters.
size	Optional	Choose 1:1, 2:3, 3:2, 16:9, or 9:16. `1:12:33:216:99:16`

How to Use

Describe the imageEnter the subject, setting, lighting, and visual style.
Choose the output frameSelect Size for a portrait, social post, or landscape scene.
Run and view the resultReview the price and select Run, then preview and download the completed result.

Pricing

One credit equals $0.005.

Usage	Rate	Details
Image generation	6 credits / image	$0.030 / image

Use Cases

Product concept boardsTurn a description of an imagined object, material, and setting into a visual concept for discussing a product’s look.
Portrait art directionCombine a character description, pose, light, and photographic or illustrated style to explore a portrait concept.
Social illustrationsCreate a scene around a post’s subject and choose a square or vertical composition for the accompanying visual.

Prompt Tips

Start with the main subject, then describe its setting, position, and scale within the frame.
For a photographic look, specify materials, lighting direction, and viewpoint; for illustration, name the medium and palette.
Choose size to match the intended layout, and mention any space needed around the subject.
Keep the main scene description while changing one visual choice, such as lighting or style, to compare directions.

Usage Notes

Save the task_id to retrieve the result, or provide callback_url for a completion notification.

Related Models

Grok Imagine Image 2.0 Text to Image preview

Grok Imagine Image 2.0 Text to ImageGenerate crisp, high-fidelity images up to 2K from text prompts with Grok Imagine Image 2.0. Features designer-grade typography, precise prompt adherence, and versatile aspect ratios.

Grok Imagine Image 2.0 EditGenerate crisp, high-fidelity images up to 2K from text prompts with Grok Imagine Image 2.0. Features designer-grade typography, precise prompt adherence, and versatile aspect ratios.

Qwen Image 3.0 Text-to-ImageAlibaba Qwen Image 3.0 Standard and Pro generation and editing with eight aspect ratios, 1K or 2K output, and ordered one-to-three-image editing.

Qwen Image 3.0 Image EditAlibaba Qwen Image 3.0 Standard and Pro generation and editing with eight aspect ratios, 1K or 2K output, and ordered one-to-three-image editing.

Qwen Image 3.0 Pro Text-to-Image preview

Qwen Image 3.0 Pro Text-to-ImageAlibaba Qwen Image 3.0 Standard and Pro generation and editing with eight aspect ratios, 1K or 2K output, and ordered one-to-three-image editing.

Qwen Image 3.0 Pro Image EditAlibaba Qwen Image 3.0 Standard and Pro generation and editing with eight aspect ratios, 1K or 2K output, and ordered one-to-three-image editing.

Seedream 5.0 Pro Text-to-ImageThe ByteDance Seedream 5.0 Pro API generates 1K or 2K JPEG/PNG images from prompts and edits one to ten ordered HTTP(S) image inputs.

Seedream 5.0 Pro Image EditThe ByteDance Seedream 5.0 Pro API generates 1K or 2K JPEG/PNG images from prompts and edits one to ten ordered HTTP(S) image inputs.

Nano Banana 2 Lite Text to Image preview

Nano Banana 2 Lite Text to ImageGenerate crisp 1K images in ~4 seconds from text prompts with Nano Banana 2 Lite. Optimized for high-volume rapid iteration, in-image text in 25+ languages, and 10 aspect ratios at $0.025 per generation.

Nano Banana 2 Lite EditGenerate crisp 1K images in ~4 seconds from text prompts with Nano Banana 2 Lite. Optimized for high-volume rapid iteration, in-image text in 25+ languages, and 10 aspect ratios at $0.025 per generation.

Grok Imagine Image Quality Text to Image preview

Grok Imagine Image Quality Text to ImageGenerate high-fidelity images up to 2K resolution from text prompts with Grok Imagine Image Quality. Features photorealistic detail, sharp text rendering, and 5 aspect ratios.

Grok Imagine Image Quality EditGenerate high-fidelity images up to 2K resolution from text prompts with Grok Imagine Image Quality. Features photorealistic detail, sharp text rendering, and 5 aspect ratios.

GPT Image 2 Text-to-ImageOpenAI image generation and editing with quality tiers, flexible size controls, and single-image outputs up to 4K.

GPT Image 2 Image EditOpenAI image generation and editing with quality tiers, flexible size controls, and single-image outputs up to 4K.

Wan 2.7 Image Standard Text to Image preview

Wan 2.7 Image Standard Text to ImageCreate and edit images from prompts or reference photos with Wan 2.7 Image Standard and Pro models.

Wan 2.7 Image Standard EditCreate and edit images from prompts or reference photos with Wan 2.7 Image Standard and Pro models.

Grok Imagine Image Text to Image API frequently asked questions

What is the Grok Imagine Image Text to Image API?

Grok Imagine Image Text to Image is an xAI model for turning text descriptions into images. It creates realistic and stylized scenes with control through subject, lighting, and composition descriptions. Text provides the visual brief, and the selected aspect ratio sets the output frame for a portrait, product concept, or illustration. You can call it through the API or try it in the Playground tab.

Can Grok Imagine Image Text to Image create photographic scenes?

Yes. Describe the subject, materials, surroundings, and light for a photographic direction, such as a ceramic cup on a wooden table in soft window light. The image is generated from that written scene.

How does Grok Imagine Image Text to Image handle illustrated styles?

Describe the illustration medium and visual treatment in prompt, such as watercolor with a muted palette or a flat editorial illustration. The subject and setting can stay the same while you explore a different style.

Which aspect ratios does Grok Imagine Image Text to Image offer?

The size field accepts 1:1, 2:3, 3:2, 16:9, and 9:16. Choose the frame for the intended placement, then describe the subject’s position and surrounding space in the prompt.

When should I choose Grok Imagine Image Text to Image instead of Grok Imagine Image Edit?

Choose Grok Imagine Image Text to Image when the starting point is a written scene or creative brief. Choose Grok Imagine Image Edit when an existing image is the starting point and you want to describe changes to it.

Can I animate a Grok Imagine Image Text to Image result?

Yes. Use the generated image as the reference for Grok Imagine Video Image to Video, then describe the desired motion. This is a separate generation step that produces a 6- or 10-second clip.

What does one Grok Imagine Image Text to Image generation cost?

Each image costs 6 credits ($0.030). The same price applies to the five available size values.