Grok Imagine Image 2.0 API (Grok Imagine Image 2 API) — Python SDK & MCP Server

A focused Python SDK and MCP server for the Grok Imagine Image 2.0 API through MuAPI. Also known as the Grok Imagine Image 2 API or Grok Imagine API, it provides xAI image generation, text-to-image, chained follow-up image editing, local uploads, and asynchronous job polling from Python or an MCP-capable agent.

Availability: Live on MuAPI as two endpoints — grok-imagine-image-2 for text-to-image and grok-imagine-image-2-edit for follow-up edits.

Related Projects

• MuAPI — Unified API for image, video, and audio generation across hundreds of AI models.
• Grok Imagine Image 2.0 on MuAPI — Official model landing page for Grok Imagine Image 2.0 generation and editing.
• Grok Imagine Image 2.0 playground — Try the model in the browser when access is enabled.
• MuAPI API reference — REST endpoint and asynchronous prediction lifecycle documentation.
• MuAPI access keys — Create the x-api-key credential required by this SDK.
• awesome-ai-image-models — Compare image models by API, price, quality, and use case.
• Awesome-GPT-Image-2-API-Prompts — Reusable prompt patterns for image generation, typography, editing, and visual design.
• Open-Generative-AI — Open-source image and video studio powered by MuAPI.
• Generative-Media-Skills — Agent-ready skills for driving image, video, and audio models from coding assistants.
• muapi-cli — Command-line access to MuAPI image, video, and audio endpoints.
• Wan-3.0-API — the companion Python SDK and MCP server for Wan video generation.
• Flux-3-Dev-API — MuAPI access to FLUX image and video workflows.

Install

git clone https://github.com/Anil-matcha/Grok-Imagine-Image-2-API.git
cd Grok-Imagine-Image-2-API
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env

Set MUAPI_API_KEY in the env file. The client uses https://api.muapi.ai/api/v1 by default. Set GROK_IMAGINE_IMAGE_2_API_BASE_URL to target a compatible self-hosted or proxy endpoint instead. GROK_API_BASE_URL is also accepted as a shorter alias.

Quick start

from grok_imagine_image_2_api import GrokImagineImage2API

api = GrokImagineImage2API()

job = api.text_to_image(
    "A high-contrast halftone portrait in fine white dots on a black background",
    aspect_ratio="1:1",
)

result = api.wait_for_completion(job["request_id"])
print(result)

The API is asynchronous: submit a prompt, keep the returned request ID, and poll until the task is completed.

Follow-up editing

Grok Imagine Image 2.0's edit model doesn't take a freshly uploaded photo — it applies a targeted edit to an image it previously generated, referenced by that job's request_id. Pass edit_image() the request_id from a prior text_to_image() (or edit_image()) call along with a prompt describing the change:

job = api.text_to_image("A raccoon in a teal Hawaiian shirt at a beach club table", aspect_ratio="1:1")
base = api.wait_for_completion(job["request_id"])

edit_job = api.edit_image(
    prompt="Change the Hawaiian shirt to a plain white t-shirt, keep everything else unchanged.",
    request_id=job["request_id"],
)
result = api.wait_for_completion(edit_job["request_id"])
print(result)

Pass an optional mask_indexs list of integers to scope the edit to specific segments of the source image instead of the whole frame. Each edit call returns its own request_id, so edits can be chained repeatedly to keep refining the same image.

Upload a local reference

uploaded = api.upload_file("reference.png")
print(uploaded)

Useful for storing your own reference assets alongside a job; note that Grok Imagine Image 2.0 itself doesn't accept uploaded images as edit input — see Follow-up editing above.

API surface

Supported aspect ratios

The current catalog contract supports:

1:1, 2:3, 3:2, 16:9, and 9:16.

MCP server

Expose the model to MCP-capable clients:

python mcp_server.py

The server provides text_to_image, edit_image, and get_task_status tools. Configure it in an MCP client with the repository's Python interpreter and pass MUAPI_API_KEY through the process environment.

Example configuration:

{
  "mcpServers": {
    "grok-imagine-image-2": {
      "command": "/absolute/path/to/.venv/bin/python",
      "args": ["/absolute/path/to/Grok-Imagine-Image-2-API/mcp_server.py"],
      "env": {
        "MUAPI_API_KEY": "your_muapi_api_key"
      }
    }
  }
}

Endpoint compatibility

The client calls these MuAPI paths beneath the configured base URL:

• POST /grok-imagine-image-2 — {prompt, aspect_ratio}
• POST /grok-imagine-image-2-edit — {prompt, request_id, mask_indexs?}
• POST /upload_file
• GET /predictions/{request_id}/result

The SDK uses the x-api-key header and JSON request bodies.

Development

Run the local tests and syntax checks with:

python -m unittest discover -s tests -v
python -m py_compile grok_imagine_image_2_api.py mcp_server.py

License

MIT