Images API

MuskAPI provides OpenAI-compatible image generation and editing endpoints. Create an API key first, then make sure its group allows image generation and the requested image model is available.

Image requests usually take longer than text requests. Use an HTTP timeout of at least two minutes in production and keep concurrency bounded.

Base URL and authentication

Copy the Base URL from User Center - API Keys. All examples use Bearer authentication.

BASE_URL="Base URL copied from User Center - API Keys"
API_KEY="YOUR_MUSKAI_API_KEY"

Choose the provider format first

The three provider families do not share one request schema. Do not change only model while reusing the rest of the payload.

Provider	Common model IDs	Endpoint and format
GPT-Image-2	gpt-image-2	OpenAI Images endpoints; JSON for generation and multipart upload for edits.
OpenAI-compatible Nano Banana	nano-banana-2, nano-banana-pro	OpenAI Images endpoints; use aspect_ratio and resolution=1k/2k/4k, without GPT Image quality or pixel size.
Grok	grok-imagine-image, grok-imagine-image-quality	OpenAI-compatible Images endpoints with aspect_ratio; references use a JSON image_urls array.
Gemini (Nano Banana / NoBanana)	gemini-3.1-flash-image-preview, gemini-3-pro-image-preview	Native /v1beta/models/{model}:generateContent; image options live in generationConfig.imageConfig.

Availability can change by group and upstream capacity. Confirm the exact model ID and media capabilities in the model catalog before deploying a client.

nano-banana-2 and nano-banana-pro use the OpenAI Images-compatible API. They are different from the native Gemini Nano Banana models documented later on this page.

GPT-Image-2

Generate an image

POST /v1/images/generations

curl "$BASE_URL/v1/images/generations" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "An orange cat in a spacesuit floating above Jupiter, cinematic lighting",
    "size": "1024x1024",
    "quality": "medium",
    "n": 1,
    "response_format": "b64_json"
  }'

Parameter	Description
model	Image model ID. Check the current model list in the console.
prompt	Describe the subject, composition, style, lighting, and text requirements.
size	Exact size or size tier supported by the selected model and channel.
quality	Common values are low, medium, and high; some models accept auto. Size and quality affect price.
n	Number of images. Billing and request quota use the actual image count.
response_format	Use b64_json for embedded image data. Some upstreams may return a temporary url; clients should support both.

The result is returned in the OpenAI Images data array.

Edit an image

POST /v1/images/edits

Send the request as multipart/form-data. Let your HTTP client generate the Content-Type boundary.

curl "$BASE_URL/v1/images/edits" \
  -H "Authorization: Bearer $API_KEY" \
  -F 'model=gpt-image-2' \
  -F 'prompt=Keep the pose and replace the background with a rainy neon city' \
  -F 'size=1024x1024' \
  -F 'quality=medium' \
  -F 'response_format=b64_json' \
  -F 'image=@./reference.png;type=image/png'

Multiple references, masks, transparent backgrounds, and available sizes depend on the model and upstream channel. Keep each reference image below 20 MB.

Do not set the multipart Content-Type manually; the HTTP client must add its boundary. The gateway accepts at most four reference URL/upload items, while the selected upstream may impose a lower limit.

Gateway JSON compatibility: references on generations

If a client can only send JSON, you may call /v1/images/generations with the gateway extension field image_urls. The gateway converts the request to the upstream standard /v1/images/edits multipart request. This is not an official OpenAI parameter. Each item must be a public HTTPS image URL or a data:image/png|jpeg|webp;base64,... data URL; up to four references are accepted and each decoded image is limited to 20 MB.

curl "$BASE_URL/v1/images/generations" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "Keep the cat pose and replace the background with a cinematic scene above Jupiter",
    "image_urls": ["data:image/png;base64,BASE64_IMAGE_DATA"],
    "size": "1024x1024",
    "quality": "medium",
    "response_format": "b64_json"
  }'

When calling the official OpenAI endpoint directly, do not send image_urls; use the /v1/images/edits multipart upload shown above.

OpenAI-compatible Nano Banana

Both models use POST /v1/images/generations. Use ratio and resolution tiers instead of GPT Image pixel sizes and quality values.

curl "$BASE_URL/v1/images/generations" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-2",
    "prompt": "A cinematic neon city at night with crisp architectural detail",
    "aspect_ratio": "16:9",
    "resolution": "2k",
    "n": 1,
    "response_format": "b64_json"
  }'

Replace the model with nano-banana-pro for the Pro variant. Common resolution tiers are 1k, 2k, and 4k; read supported ratios from the model catalog. A successful item contains either data[0].b64_json or data[0].url. Download temporary URLs immediately, and reject HTTP 200 responses that contain neither field.

Grok

Use grok-imagine-image for the fast tier and grok-imagine-image-quality for the quality tier. Grok uses aspect_ratio; do not copy GPT-Image-2 pixel size values blindly.

curl "$BASE_URL/v1/images/generations" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-image",
    "prompt": "A documentary photograph of a ramen shop in rainy futuristic Tokyo",
    "aspect_ratio": "16:9",
    "response_format": "b64_json"
  }'

For an edit, send public HTTPS URLs or data:image/...;base64,... values in JSON. Up to four references are accepted by the gateway, with a decoded limit of 20 MB each.

curl "$BASE_URL/v1/images/edits" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-image-quality",
    "prompt": "Keep the subject and replace the background with a mountain sunrise",
    "aspect_ratio": "16:9",
    "image_urls": ["https://example.com/reference.png"],
    "response_format": "b64_json"
  }'

Current catalog capabilities include ratios such as 1:1, 16:9, 9:16, 4:3, 3:4, 3:2, and 2:3. Select the quality model when you need its quality/resolution tier; quality=high is not guaranteed to turn the fast model into the quality model.

Gemini (Nano Banana / NoBanana)

Gemini image models use the native Gemini schema, not the OpenAI Images body.

GEMINI_MODEL="gemini-3.1-flash-image-preview"

curl "$BASE_URL/v1beta/models/$GEMINI_MODEL:generateContent" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{"parts": [{"text": "A minimalist perfume product poster with soft side lighting"}]}],
    "generationConfig": {
      "responseModalities": ["IMAGE"],
      "imageConfig": {"aspectRatio": "4:5", "imageSize": "2K"}
    }
  }'

To add a reference, append an inlineData part beside the text part. inlineData.data must contain raw Base64 without a data:image/...;base64, prefix.

{
  "contents": [{
    "parts": [
      {"text": "Keep the product shape and use a dark blue star field"},
      {"inlineData": {"mimeType": "image/png", "data": "BASE64_WITHOUT_PREFIX"}}
    ]
  }],
  "generationConfig": {
    "responseModalities": ["IMAGE"],
    "imageConfig": {"aspectRatio": "1:1", "imageSize": "2K"}
  }
}

Read generated bytes from every candidates[].content.parts[].inlineData.data and use inlineData.mimeType as the file type. Robust clients may also accept compatibility aliases inline_data and mime_type. A 200 response with text or a safety result but no image part is not a successful image generation.

Response handling checklist

• GPT-Image-2 and Grok: iterate over data, read b64_json, or download a returned temporary url immediately.
• Gemini: inspect all candidate parts rather than assuming the first part is the image.
• Raise response-body limits for Base64 payloads and never write full image Base64 to normal application logs.
• Use a timeout of at least 120 seconds. Avoid unbounded retries after a timeout because the upstream request may still finish and be billed.

Asynchronous image tasks

If the selected upstream supports asynchronous image tasks, create one with POST /v1/images/tasks:

curl "$BASE_URL/v1/images/tasks" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-image-2","prompt":"A minimalist mountain cafe poster","size":"1024x1024","quality":"medium","n":1}'

Read task_id (or id, depending on the upstream) from the response and poll it:

curl "$BASE_URL/v1/images/tasks/TASK_ID" \
  -H "Authorization: Bearer $API_KEY"

• This endpoint proxies an upstream task API; it is not a MuskAPI-owned durable job queue.
• Query with the same API key/group used to create the task. The task-to-account binding is currently retained for up to 24 hours; after that, or when the original account is unavailable, the task may no longer be queryable.
• Poll every 2 to 5 seconds and download the result immediately after completion.
• Do not assume every provider supports tasks. Treat native Gemini generateContent and ordinary Grok Images calls as synchronous unless the selected channel explicitly advertises task support.

Image storage and history

Recent images and the pending queue on the web image page are saved locally in the browser on a best-effort basis. The page prefers IndexedDB and falls back to localStorage.

• History is not synchronized across browsers, devices, or service nodes.
• Private browsing, insufficient browser storage, cleared site data, or write failures can make history disappear.
• The legacy server-side gallery uses a node-local disk and has no shared-storage consistency guarantee in a multi-node deployment. Do not treat it as durable cloud storage.
• MuskAPI currently does not provide image OSS storage, configurable retention, automatic lifecycle deletion, or user-facing OSS storage/traffic billing.

Download and back up every successful image immediately. Do not rely on browser history, temporary upstream URLs, or the legacy server gallery for long-term storage.

Common errors

Image generation is not enabled for this group

Use an API key whose group allows image generation, or ask the administrator to enable it.

No compatible account or model not found

The group has no available channel supporting the requested model, size, quality, or endpoint. Verify the model ID or retry with a lower size or quality.

Invalid parameters or HTTP 200 without an image

Check for a mixed provider schema: GPT edits are multipart; Grok uses aspect_ratio and JSON image_urls; Gemini uses native contents / generationConfig and returns inlineData. Also confirm that the requested ratio and resolution are currently listed for the model.

The request succeeded but the image is missing from web history

Browser persistence is not reliable storage. Download the image directly from the response b64_json or url; MuskAPI cannot guarantee recovery after the page or browser data has been cleared.