The Claude Image Generation API is Claude Imagine's bearer-key endpoint for text-to-image automation. Send one JSON request from Claude Code, Python, TypeScript, curl, or your backend; choose from five friendly model ids; and receive image URLs with the exact credits used.
Claude orchestrates the workflow, while external image models generate the pixels.
3 signup credits · 5 models · 5 aspect ratios · Task failures refunded
Working requests
Create a key in Claude Imagine settings, save it as CLAUDEIMAGINE_API_KEY, and run any example below. The key is displayed once and stored only as a SHA-256 digest, so copy it when it is created. These examples use GPT Image 2, but changing the friendly model id is the only model-specific code change.
curl
curl https://claudeimagine.com/api/v1/images/generations \
-H "Authorization: Bearer $CLAUDEIMAGINE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"gpt-image-2","prompt":"minimal editorial poster of a glass greenhouse at dawn","aspect_ratio":"4:3"}'A bearer header and JSON prompt are required. model defaults to nano-banana-2 and aspect_ratio is optional, so an even smaller request can send only the prompt.
Python
import json
import os
import urllib.request
payload = json.dumps({
"model": "gpt-image-2",
"prompt": "minimal editorial poster of a glass greenhouse at dawn",
"aspect_ratio": "4:3",
}).encode()
request = urllib.request.Request(
"https://claudeimagine.com/api/v1/images/generations",
data=payload,
headers={
"Authorization": "Bearer " + os.environ["CLAUDEIMAGINE_API_KEY"],
"Content-Type": "application/json",
},
)
with urllib.request.urlopen(request, timeout=130) as response:
print(json.load(response))This version needs no third-party package. The 130-second client timeout is slightly longer than the API's 120-second server wait, allowing the endpoint to return its own completion or still-running response.
TypeScript
const response = await fetch(
"https://claudeimagine.com/api/v1/images/generations",
{
method: "POST",
headers: {
Authorization: "Bearer " + process.env.CLAUDEIMAGINE_API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({
model: "gpt-image-2",
prompt: "minimal editorial poster of a glass greenhouse at dawn",
aspect_ratio: "4:3",
}),
}
);
const result = await response.json();
if (!response.ok) throw new Error(result.error);
console.log(result.images, result.credits_used);Keep the bearer key on the server, not in browser JavaScript. Check response.ok before using the images array because validation, balance, plan, and task states map to different HTTP status codes.
The endpoint is intentionally small. It is not advertised as an OpenAI-compatible API because its request fields, model ids, credit response, and error behavior are Claude Imagine's own contract.
Send Authorization: Bearer followed by a live Claude Imagine key. A missing, invalid, or revoked key returns HTTP 401 before any prompt is processed or credits are checked.
prompt must be a trimmed string from 1 to 2,000 characters. Missing text, empty text, non-string input, or a prompt over the limit returns HTTP 400 without starting a task.
model defaults to nano-banana-2. Friendly values are nano-banana-2, gpt-image-2, seedream-4.5, flux-2-pro, and z-image; an unknown value returns the current allowed list.
aspect_ratio may be 1:1, 4:3, 3:4, 16:9, or 9:16. Omit it to use the model service's default. Unsupported ratios fail validation before billing.
HTTP 200 returns images as an array of URL objects, model as the friendly id requested, and credits_used as the effective price for that account and model.
Each request creates a generation task tied to the authenticated user. The same task appears in Activity, so billing source, model, status, prompt, output, and any refund remain traceable.
Credit prices are per started image generation and are read from the same catalog used by the web generator and MCP server. Model gates are checked before the task starts.
The default friendly model is available on every plan tier. It is the service's general quality-and-price default and accepts the same five text-to-image aspect ratios as the other public API models.
Use model gpt-image-2 for the lower two-credit path. It is available without a subscription and is also covered in the dedicated GPT Image 2 for Claude setup page.
Seedream 4.5 requires an active Pro or Studio subscription. A top-up pack supplies credits but does not change plan tier, so pack-only accounts receive a clear HTTP 403 upgrade message.
Flux 2 Pro also requires Pro or Studio. The endpoint never substitutes a cheaper model when access is missing; it returns the plan-gating message instead.
Z-Image costs one credit on free and Basic accounts. Its effective generation cost is zero for Pro and Studio accounts under the current unlimited Z-Image plan benefit.
API, MCP, Skill, and web requests resolve their model through one catalog and deduct from one account balance. This prevents a documented API price from drifting away from the actual generator charge.
Every non-200 response is JSON with an error field. The status code tells you whether to fix the request, replace credentials, add credits, upgrade the plan, wait, retry, or contact support.
Malformed JSON, an invalid prompt, an unknown model, or an unsupported aspect ratio returns HTTP 400. No generation task starts and no credits are deducted.
A missing bearer header, unknown key, or revoked key returns HTTP 401. Create a new key in settings if the original was lost or revoked; the stored digest cannot reveal it again.
When the remaining balance is below the model's effective cost, the API returns HTTP 402 with the current balance, credits needed, and a pricing link. It does not create a partially funded task.
A locked model or an account that has reached its active-generation limit returns HTTP 403. The message explains the required plan or the current concurrency cap.
A failed task returns HTTP 502 and confirms that credits were refunded. A task marked successful but containing no image URL also returns 502, but explicitly identifies that exceptional support case.
If the task is not complete within the endpoint's 120-second wait, HTTP 504 points to the Activity page. The task remains tracked and can finish after the client request ends.
The API key identifies the credit-bearing Claude Imagine account. Treat it as a server secret even when the calling workflow is a local Claude Code Skill.
The raw API key is displayed only at creation. Copy it immediately into a password manager or environment file; settings can list the key record but cannot recover the original secret.
Claude Imagine stores the key as a SHA-256 digest and looks up that digest during authentication. The database does not need the reusable plaintext key to validate requests.
Do not expose the key in browser JavaScript, public repositories, screenshots, or committed .env files. Call the endpoint from a server, local script, CI secret, or protected agent runtime.
If a key is copied into the wrong place, revoke it in settings and create a replacement. A revoked key immediately fails the same bearer-key lookup with HTTP 401.
A balance check provides a fast error, while the generation service enforces the actual deduction atomically when the task starts. Parallel requests cannot intentionally spend the same credits twice.
API generations are tagged with source api in task and analytics records. That separates HTTP automation from web and MCP usage when you review activity or reconcile credit consumption.
The best integration depends on who should hold authentication and where the final image should appear. You can enable more than one path because they share the same account.
Choose the API for backend jobs, scripts, agent frameworks, CI tasks, and custom interfaces. Your code owns the bearer key, request, status handling, output URL, and optional download.
Choose remote MCP for Claude Code, claude.ai, or Claude Desktop when you want OAuth and in-conversation tools. Claude can list live prices and check credits before calling generate_image.
Choose the public Skill when Claude Code should generate and save a file in the current repository. The included Python script wraps the API without adding third-party dependencies.
Choose the web generator for prompt starters, visible task progress, batch controls, direct downloads, and image-to-image modes. The current API, Skill, and MCP tool remain text-to-image only.
MCP uses OAuth 2.1 with PKCE and dynamic client registration. The API and Skill use a Claude Imagine bearer key. Those are deliberate authentication choices, not interchangeable configuration fields.
Whichever interface starts the task, model prices and account-tier rules come from the same catalog. There is no separate MCP surcharge or API-only credit wallet.
Build against the behavior that exists now. These boundaries keep the quickstart truthful and make future capability changes easy to identify.
The endpoint accepts a prompt, model, and aspect ratio. It does not accept image uploads, masks, image URLs, or editing instructions as structured reference-image inputs.
The path, friendly model ids, response object, credits_used field, and errors are Claude Imagine-specific. Do not point an OpenAI SDK at this endpoint and assume compatibility.
The request waits for a tracked asynchronous task for up to 120 seconds. Handle HTTP 504 as still running rather than treating every timeout as a permanent generation failure.
A successful response returns image URL objects, not inline base64 bytes. Download or proxy the URL if your application needs to persist the file under its own storage policy.
A large credit balance from a top-up pack does not unlock Seedream 4.5 or Flux 2 Pro. Those models check active subscription tier separately from balance.
Claude Imagine is not Anthropic's native Claude API and is not affiliated with, endorsed by, or sponsored by Anthropic, OpenAI, Google, Black Forest Labs, or model owners.
Implementation answers for developers deciding between direct HTTP, a Claude Code Skill, remote MCP, and the web generator.
Want OAuth instead of a bearer key? Follow the remote MCP setup.
Checked August 24, 2026. Anthropic's official vision documentation describes image understanding in the Claude API, while its connector documentation explains how remote MCP tools extend Claude. The endpoint, prices, refunds, and limits above are verified against Claude Imagine's live implementation.
Create one key, keep it server-side, and start with the model that fits the job. Your 3 signup credits can cover one Nano Banana 2 image or one GPT Image 2 image before you choose a recurring plan or one-time pack.