Generate images through Moca Router

Image models do not all accept the same size, quality, format, background, or result representation. List the model IDs visible to the team, then query a candidate with the authenticated capabilities endpoint before constructing optional parameters. A usable image model returns modality: image and the image_generation operation.

# List model IDs available to this team
curl https://staging.mocarouter.com/api/proxy/v1/models \
  -H "Authorization: Bearer $MOCA_ROUTER_API_KEY"

# Inspect one candidate before generating
curl --get https://staging.mocarouter.com/api/proxy/v1/model-capabilities \
  -H "Authorization: Bearer $MOCA_ROUTER_API_KEY" \
  --data-urlencode "model=gemini-2.5-flash-image"

The API rejects unknown fields. Field names follow the OpenAI Images API shape, while accepted values come from the selected model's capability record.

Generate a new idempotency key for each intended image generation. Keep the same key only when retrying an attempt whose delivery result is uncertain.

JavaScript (Node.js 18+)

import { randomUUID } from "node:crypto";
import { writeFile } from "node:fs/promises";

const response = await fetch("https://staging.mocarouter.com/api/proxy/v1/images/generations", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.MOCA_ROUTER_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": randomUUID(),
  },
  body: JSON.stringify({
    model: "gemini-2.5-flash-image",
    prompt: "A quiet reading room overlooking Tokyo at dusk",
  }),
});

const payload = await response.json();
if (!response.ok) {
  throw new Error(payload.error?.message ?? `HTTP ${response.status}`);
}

const image = payload.data[0];
if (image.b64_json) {
  const extension = payload.output_format === "jpeg"
    ? "jpg"
    : (payload.output_format ?? "bin");
  await writeFile("image." + extension, Buffer.from(image.b64_json, "base64"));
} else {
  console.log("Temporary image URL:", image.url);
}

Python

import base64
import os
import uuid

import requests

response = requests.post(
    "https://staging.mocarouter.com/api/proxy/v1/images/generations",
    headers={
        "Authorization": f"Bearer {os.environ['MOCA_ROUTER_API_KEY']}",
        "Content-Type": "application/json",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "model": "gemini-2.5-flash-image",
        "prompt": "A quiet reading room overlooking Tokyo at dusk",
    },
    timeout=180,
)

payload = response.json()
if not response.ok:
    raise RuntimeError(payload.get("error", payload))

image = payload["data"][0]
if "b64_json" in image:
    output_format = payload.get("output_format", "bin")
    extension = "jpg" if output_format == "jpeg" else output_format
    with open(f"image.{extension}", "wb") as file:
        file.write(base64.b64decode(image["b64_json"], validate=True))
else:
    print("Temporary image URL:", image["url"])

Handle both result formats

A successful response uses an OpenAI-compatible data array. Each item contains exactly one of b64_json or url, plus an optional revised_prompt. Usage appears only when the provider reports it.

{
  "created": 1789552800,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAA...",
      "revised_prompt": "A quiet reading room..."
    }
  ],
  "output_format": "png",
  "quality": "standard",
  "size": "1024x1024",
  "usage": {
    "input_tokens": 18,
    "output_tokens": 1290,
    "total_tokens": 1308
  }
}

Diagnostic response headers include x-mocarouter-request-id, and may include x-mocarouter-routed-model and x-mocarouter-provider-request-id. Record these IDs—not image content—when contacting support.

Responses are marked Cache-Control: no-store. Rate-limited responses may include Retry-After and X-RateLimit-* headers.

• Create one random key per intended generation. UUIDs are a good default.
• If the connection times out before you receive a response, retry the identical request with the same key.
• Never reuse a key with a changed prompt or parameter set; the gateway returns 409 idempotency_key_conflict.
• If an identical request is still running, the gateway returns 409 idempotency_request_in_progress. Wait before checking again.
• Successful image bytes are not cached for replay. A repeated completed key returns 410 idempotent_result_unavailable; use a new key only when you intentionally want a new generation and charge.

Image generation is billed separately from text-token quotas. Effective prices are selected from the model's image-unit rules and request dimensions such as size, quality, output format, response format, and background.

• Before upstream dispatch, Moca Router reserves the maximum customer charge for the requested n.
• After a valid provider response, the hold is settled against the actual number of returned images.
• Provider token usage can be recorded for cost accounting and returned in usage, but customer-facing image pricing is exposed as USD per image unit.
• Team, API-key, account, request-per-minute, image-unit-per-minute, concurrency, balance, and budget controls can reject a request before dispatch.

Errors and troubleshooting

Image-route errors use a structured envelope with message, type, param, and code. Authentication middleware errors may use a shorter envelope.

{
  "error": {
    "message": "size is not supported by this model",
    "type": "invalid_request_error",
    "param": "size",
    "code": "unsupported_size"
  }
}

The image generation path processes the prompt and provider response to validate and return the result, but its application database does not store the raw prompt, generated image bytes, provider image URL, or raw idempotency key. It stores operational and billing metadata such as keyed request digests, request state, model, dimensions, usage, cost, and request IDs.

• Do not place API keys, passwords, personal identifiers, or regulated secrets in prompts.
• Avoid logging request bodies, base64 output, or provider URLs in your own application.
• Store only the generated output you actually need and apply your own access and deletion policy.
• Use x-mocarouter-request-id and the idempotency key—not customer content—for support correlation.