Create an image

Send a prompt and get back a PNG plus a small provenance file that records exactly how it was made. Ask for transparency and the alpha channel is generated with the image, not cut out afterwards.

Input

A prompt of up to 4,000 characters; no file

Outputs

image.png and generation.json

Sizes

1:1 1024 × 1024 · 4:3 1152 × 864 · 3:4 864 × 1152

Transparency

Optional RGBA output generated with alpha, not segmented afterwards

Duration

Asynchronous; one-hour deadline including queueing and execution

Send the options as JSON. The response is the new job; poll it until its status is final, then download the files in result.files.

# idempotency_key is required: repeating the same request returns the same job
curl https://api.mcpbytes.com/v1/tools/create_image/jobs \
  -H "Authorization: Bearer $MCPBYTES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "options": {
      "prompt": "a ceramic teapot with a blue glaze",
      "transparent_background": true,
      "seed": 42
    },
    "idempotency_key": "image-example-001"
  }'

{
  "tool": "create_image",
  "status": "queued",
  "input_kind": "parameters",
  "options": {
    "prompt": "a ceramic teapot with a blue glaze",
    "preset": "standard",
    "aspect_ratio": "1:1",
    "transparent_background": true,
    "seed": 42
  },
  "workflow": {
    "stage": "Generating visuals",
    "deadline": "2026-09-22T04:54:31.021Z",
    "cancel_pending": false,
    "refund_pending": false
  },
  "capabilities": {
    "can_cancel": true
  },
  "result": null
}

# JOB_ID is the id from the create response; poll until status is final
curl "https://api.mcpbytes.com/v1/jobs/$JOB_ID" \
  -H "Authorization: Bearer $MCPBYTES_API_KEY"

# Once status is succeeded, download the image from result.files[].url
curl -fsSLo image.png "$IMAGE_URL"

{
  "tool": "create_image",
  "status": "succeeded",
  "credits_charged": 20,
  "compute_ms": 40083,
  "result": {
    "files": [
      {
        "name": "image.png",
        "bytes": 1110043,
        "content_type": "image/png",
        "url": "https://api.mcpbytes.com/blob/dl/…"
      },
      {
        "name": "generation.json",
        "bytes": 1329,
        "content_type": "application/json",
        "url": "https://api.mcpbytes.com/blob/dl/…"
      }
    ]
  }
}

Jobs of this tool take minutes. While one runs, workflow.stage says what is happening and workflow.deadline when it must finish. Cancel it with POST /v1/jobs/{id}/cancel while capabilities.can_cancel is true.

More on statuses, downloads and retention in Jobs & files.

No file. Send the options in a JSON body, {"options": {…}}, or as arguments of the MCP tool. Keep private text such as prompts out of URLs.

Put options in the options object of the JSON body, or pass them as arguments of the MCP tool. Leave an option out to use its default.

A succeeded job lists its files in result.files, each with a download url.

Download links last up to 24 hours, capped by output retention; read the job again for fresh links. Text and fine detail in generated images are best-effort; transparent output relies on the model's own alpha channel, so a busy prompt can leave background elements attached to the object.

• Send the prompt in the JSON body or as MCP arguments, never in a URL.
• preset reference_3d frames one isolated object from a three-quarter view with neutral lighting. Pass its image.png to create_3d_model_from_image as job_file.
• With transparent_background, the alpha channel is part of the generated image, so a busy prompt can leave background elements attached to the object.
• Text and fine detail in generated images are best-effort.
• The same seed reproduces an image within the same profile version; generation.json records the seed and settings.

Your agent calls create_image. Connect it to https://api.mcpbytes.com/mcp/image for this tool, or to https://api.mcpbytes.com/mcp for every tool.

claude mcp add --transport http mcpbytes \
  https://api.mcpbytes.com/mcp/image

codex mcp add mcpbytes --url https://api.mcpbytes.com/mcp/image \
  --bearer-token-env-var MCPBYTES_API_KEY

{
  "mcpServers": {
    "mcpbytes": {
      "url": "https://api.mcpbytes.com/mcp/image",
      "headers": {
        "Authorization": "Bearer ${env:MCPBYTES_API_KEY}"
      }
    }
  }
}

Arguments

The tool's options are flat arguments. Besides them:

What the agent sees

Setup for every client, and how agents upload files and read results: Connect over MCP.

The MCPBytes skill teaches agents this tool, in references/create_image.md. Agents without MCP run it through the REST API with the skill's script, which reads your key from MCPBYTES_API_KEY:

printf '{"prompt": "a ceramic teapot with a blue glaze",
  "transparent_background": true}' > options.json
python scripts/mcpbytes.py run create_image \
  --options-json options.json --out image/
python scripts/mcpbytes.py job j_...

20 credits per job. The price is charged before paid processing starts, and a canceled job is refunded. A job that fails costs nothing: its charge is refunded.

One credit balance pays for every tool, and a new account starts with free credits. See Credits & prices or buy credits.

GET /v1/me returns your limits and current usage; Limits & errors explains what happens when one is reached.

A failed job comes back with error.code, error.message and often error.hint. Codes are stable. Inputs that fail with a validation error will fail again unchanged.

Requests can also fail before a job starts, with an HTTP status: see HTTP errors.

• Create a 3D model from an imageTurn the image into a textured model: pass image.png as job_file.create_3d_model_from_image