grok-image-2

v1.0.0

Published

3 months ago

Grok Image 2 text-to-image and reference-image editing API skill with complete async examples

0High
0Medium
0Low

cheercheung

grok-image-2 grok-imagine-image-2 xai-image text-to-image image-editing image-generation agent-skill api

Grok Image 2 API & Agent Skill

AI Agent? Run npx skills add https://github.com/cheercheung/grok-image-2/tree/main/skills/grok-image-2, then read llms-install.md

Grok Image 2 uses grok-imagine-image-2.0 for both text-to-image and reference-image editing. Developers can create a task, poll it to completion, and retrieve final image URLs; agent users can install a prompt-and-payload workflow that validates every supported option before a paid call

Agent Skill

This repository combines two public entrances in one maintained package

| Entrance | What it provides | |---|---| | Agent skill | Prompt construction, mode selection, payload validation, approval boundary, and structured task output | | API guide | Complete create → poll/callback → final image URL examples in cURL, Python, and JavaScript |

The API is asynchronous. A create request returns a task ID; the client then polls GET /v1/tasks/{task_id} or receives an HTTPS callback. Completed image URLs expire after 24 hours, so production clients should download or copy them promptly

Installation

Agent install — recommended

npx skills add https://github.com/cheercheung/grok-image-2/tree/main/skills/grok-image-2

npm fallback installer

npx grok-image-2@latest -y --path ~/.claude/skills

Use another explicit skill directory when needed, such as ~/.codex/skills or ~/.hermes/skills

Manual install

git clone https://github.com/cheercheung/grok-image-2.git
cd grok-image-2
node bin/cli.js -y --path ~/.codex/skills --no-open

Agent Auto-Install

Install the Grok Image 2 skill by running:

npx skills add https://github.com/cheercheung/grok-image-2/tree/main/skills/grok-image-2

Then read the installed SKILL.md. Check whether EVOLINK_API_KEY is available without printing its value. If it is missing, show the tracked key URL from the skill and ask me to paste the key. Validate it through the non-generating credits endpoint before any image generation. Always preview the exact request and cost boundary before a paid call

Getting an API key

Open the API key page
Sign in or create an account and return to the key page
Create or select a key, then store it as EVOLINK_API_KEY
Validate the key without generating an image

export EVOLINK_API_KEY="your_key_here"
curl -fsS https://api.evolink.ai/v1/credits \
  -H "Authorization: Bearer ${EVOLINK_API_KEY}"

Never commit a key to Git, a prompt, an issue, or a shell history file you do not control

API Quick Start

This creates one 1K, low-quality square text-to-image task. It does not wait for completion

export EVOLINK_API_KEY="your_key_here"

curl --request POST \
  --url https://api.evolink.ai/v1/images/generations \
  --header "Authorization: Bearer ${EVOLINK_API_KEY}" \
  --header "Content-Type: application/json" \
  --header "X-EvoLink-Source: skill" \
  --header "X-EvoLink-Skill: grok-image-2" \
  --header "X-EvoLink-Package: grok-image-2" \
  --header "X-EvoLink-Campaign: grok-image-2" \
  --header "X-EvoLink-Touchpoint: first-run" \
  --data '{
    "model": "grok-imagine-image-2.0",
    "prompt": "A minimalist editorial poster for a synthwave album, sharp small typography, magenta and midnight blue",
    "size": "1:1",
    "resolution": "1K",
    "quality": "low",
    "n": 1
  }'

Pending response shape

{
  "created": 1757156493,
  "id": "task-unified-1757156493-imcg5zqt",
  "model": "grok-imagine-image-2.0",
  "object": "image.generation.task",
  "progress": 0,
  "status": "pending",
  "type": "image",
  "usage": {
    "billing_rule": "per_call",
    "credits_reserved": 3.06,
    "user_group": "default"
  }
}

Full First-Run Flow

The executable examples check the key, create the image task, check HTTP errors, poll through pending and processing, stop on failed, enforce a timeout, and print each final URL

# Zero-credit payload preview
bash scripts/grok-image-2.sh \
  --prompt "A clean product photo of a ceramic lamp on travertine" \
  --size 1:1 \
  --resolution 1K \
  --quality low \
  --dry-run

# Paid execution only after reviewing the preview and approving the cost boundary
bash scripts/grok-image-2.sh \
  --prompt "A clean product photo of a ceramic lamp on travertine" \
  --size 1:1 \
  --resolution 1K \
  --quality low \
  --execute

When the script prints TASK_SUBMITTED, do not rerun it. Continue polling the returned task ID to avoid duplicate paid tasks

Completed response shape

{
  "id": "task-unified-1757156493-imcg5zqt",
  "model": "grok-imagine-image-2.0",
  "object": "image.generation.task",
  "progress": 100,
  "status": "completed",
  "type": "image",
  "results": [
    "https://media.invalid/generated-image.jpg"
  ]
}

Grok Image 2 Workflows

| Workflow | How to select it | Good for | |---|---|---| | Text-to-image | Omit image_urls | Posters, product concepts, illustrations, social assets | | Single-image edit | Pass one public image URL | Background, lighting, season, color, or targeted content changes | | Multi-image edit | Pass two or three public image URLs and reference them as <IMAGE_0>, <IMAGE_1>, and <IMAGE_2> | Composition, subject transfer, product-plus-scene combinations |

Both workflows use the same endpoint and model ID

| Purpose | Method | Path | |---|---|---| | Create image task | POST | /v1/images/generations | | Query task | GET | /v1/tasks/{task_id} |

Request Parameters

| Field | Type | Required | Accepted values and behavior | |---|---|---:|---| | model | string | yes | Must be grok-imagine-image-2.0 | | prompt | string | yes | Generation brief or edit instruction | | image_urls | string[] | no | Omit for text-to-image; 1–3 public HTTP/HTTPS JPEG, PNG, or WebP URLs for editing; no base64/data URLs | | size | string | no | auto, 1:1, 4:3, 3:4, 3:2, 2:3, 16:9, 9:16, 2:1, 1:2, 19.5:9, 9:19.5, 20:9, 9:20 | | resolution | string | no | 1K or 2K; 4K is unsupported | | quality | string | no | low or medium; high is unsupported | | n | integer | no | 1–10; each output is billed independently | | callback_url | string | no | Public HTTPS URL, maximum 2048 characters, no private/local IP |

See API parameters for validation details

Prompting and Editing

A useful prompt specifies the subject, intended use, composition, camera/framing, lighting, palette, material detail, background, text handling, and exclusions. The API has no separate negative_prompt field, so important exclusions should be phrased directly in the main prompt

For multi-image edits, map references explicitly

Place the person from <IMAGE_0> into the room from <IMAGE_1>. Preserve the person's face, clothing, and proportions. Match the room's warm window light and camera perspective. Do not add extra people or text

The model can render typography, but exact copy should be quoted and kept short. Verify every character in the output before production use

🖼️ Showcase

| Text-to-image | Single-image edit | Multi-image edit | |---|---|---| | Build a poster, product shot, illustration, or social asset from a structured brief | Preserve the supplied subject while changing a named region, background, material, or lighting condition | Compose up to three references with explicit <IMAGE_N> roles and preservation constraints |

This repository does not include fabricated outputs. Add real result media only after a verified generation and source review

Documentation

Production Notes

Use usage.credits_reserved from the create response as the immediate cost signal
Use callbacks for high-volume systems and retain polling as a recovery path
Back off on 429 and transient 5xx responses; do not automatically recreate a submitted task
Save result images before their 24-hour URLs expire
Host reference images at stable, directly downloadable public URLs
Treat n as a linear output-cost multiplier; reference-image input charges apply once per request

FAQ

Is the API synchronous? No. Creation returns a task ID and the final URLs arrive through task polling or callback

Which model do I use for editing? The same grok-imagine-image-2.0 model. Add 1–3 image_urls

Can I send base64 images? No. References must be public HTTP/HTTPS URLs to supported image formats

Can it generate 4K or high quality? No. The documented limits are 1K/2K and low/medium

How many images can one request return? n supports 1–10, with per-image billing

How long are outputs available? The documented result links are valid for 24 hours

Troubleshooting

| Problem | Fix | |---|---| | EVOLINK_API_KEY missing | Create/select a key, export it, and validate with GET /v1/credits | | 400 invalid_request | Check model ID, enum values, n, image count, and public image URL format | | 401 unauthorized | Replace or re-export the key; do not print it in logs | | 402 insufficient_quota | Stop and ask the user to approve a new cost boundary before retrying | | 403 model_access_denied | Confirm the account has access to grok-imagine-image-2.0 | | 429 rate_limit_exceeded | Back off with jitter and reduce concurrency | | Task is failed | Read error.code and error.message; correct the input instead of resubmitting blindly | | Polling timed out | Keep the task ID and query it again; never recreate the task only because the client timed out |

Compatibility

| Agent | Recommended path | |---|---| | Hermes Agent | npx skills add https://github.com/cheercheung/grok-image-2/tree/main/skills/grok-image-2 | | Claude Code | npx skills add https://github.com/cheercheung/grok-image-2/tree/main/skills/grok-image-2 | | Codex | npx skills add https://github.com/cheercheung/grok-image-2/tree/main/skills/grok-image-2 | | OpenClaw | Same command; npm fallback may use an explicit OpenClaw skills directory |

Community

Use API bug reports for reproducible request/runtime issues and documentation fixes for source-backed corrections. Never post API keys or private input URLs in an issue

License

MIT