Images

Two endpoints in the format of the OpenAI Images API: POST /v1/images/generations creates images from a description, and POST /v1/images/edits creates them from one or more images. Images come back in the response, in base64: Moon AI keeps no copy and does not provide a hosted URL.

Create an image#Link to the Create an image section

POST https://api.realmoon.ai/v1/images/generations

• Authentication: an sk-moon-… key with the inference scope (see Authentication).
• Body: JSON, 1 MB at most.
• Response: an image object (see Response).

Parameters#Link to the Parameters section

The user, style, moderation, background, output_compression, output_format, partial_images and input_fidelity parameters are accepted and have no effect. Any other parameter is rejected with 400 unknown_parameter. An image sent in image or images is rejected here: use /v1/images/edits.

Example#Link to the Example section

curl https://api.realmoon.ai/v1/images/generations \
  -H "Authorization: Bearer $MOONAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "model": "google/gemini-3.1-flash-image",
        "prompt": "A retro poster of a rocket above Paris",
        "size": "1024x1536"
      }' \
  | jq -r '.data[0].b64_json' | base64 --decode > poster.png

import base64
import os
from openai import OpenAI

client = OpenAI(base_url="https://api.realmoon.ai/v1", api_key=os.environ["MOONAI_API_KEY"])

img = client.images.generate(
    model="google/gemini-3.1-flash-image",
    prompt="A retro poster of a rocket above Paris",
    size="1024x1536",
    # Moon AI-specific parameter: passed through extra_body.
    extra_body={"image_size": "2K"},
)
with open("poster.png", "wb") as f:
    f.write(base64.b64decode(img.data[0].b64_json))

import fs from 'node:fs';
import OpenAI from 'openai';

const client = new OpenAI({ baseURL: 'https://api.realmoon.ai/v1', apiKey: process.env.MOONAI_API_KEY });

const img = await client.images.generate({
  model: 'google/gemini-3.1-flash-image',
  prompt: 'A retro poster of a rocket above Paris',
  size: '1024x1536',
  // Moon AI-specific parameter, sent as is.
  image_size: '2K',
});
fs.writeFileSync('poster.png', Buffer.from(img.data[0].b64_json, 'base64'));

Size and aspect ratio#Link to the Size and aspect ratio section

When you give size without aspect_ratio or image_size:

• the aspect ratio used is the model’s closest match to the width-to-height ratio;
• the size used is 1K if the longest side is 1,100 pixels or less, 2K up to 2,200 pixels, and 4K beyond that (or the model’s largest size).

So the image produced can have slightly different dimensions from size. With no size, aspect_ratio or image_size, the model decides.

Edit an image#Link to the Edit an image section

POST https://api.realmoon.ai/v1/images/edits

• Authentication: an sk-moon-… key with the inference scope.
• Body: multipart/form-data (with the Content-Length header) or JSON, 90 MB at most.
• Response: an image object (see Response).

Parameters#Link to the Parameters section

All the generation parameters apply, plus the images:

An image given as an https:// URL is fetched by the model provider, never by Moon AI.

Example#Link to the Example section

curl https://api.realmoon.ai/v1/images/edits \
  -H "Authorization: Bearer $MOONAI_API_KEY" \
  -F model=google/gemini-3.1-flash-image \
  -F prompt="Same photo, in black and white" \
  -F image=@photo.png

edit = client.images.edit(
    model="google/gemini-3.1-flash-image",
    image=open("photo.png", "rb"),
    prompt="Same photo, in black and white",
)
with open("photo-bw.png", "wb") as f:
    f.write(base64.b64decode(edit.data[0].b64_json))

# Several images: pass a list.
combo = client.images.edit(
    model="google/gemini-3.1-flash-image",
    image=[open("product.png", "rb"), open("setting.png", "rb")],
    prompt="The product from the first image placed in the setting of the second",
)

const edit = await client.images.edit({
  model: 'google/gemini-3.1-flash-image',
  image: fs.createReadStream('photo.png'),
  prompt: 'Same photo, in black and white',
});
fs.writeFileSync('photo-bw.png', Buffer.from(edit.data[0].b64_json, 'base64'));

The same call in JSON, with one image in base64 and one image at a URL:

{
  "model": "google/gemini-3.1-flash-image",
  "prompt": "The product from the first image placed in the setting of the second",
  "images": [
    { "image_url": "data:image/png;base64,iVBORw0KGgo…" },
    { "image_url": "https://example.com/setting.jpg" }
  ]
}

Response#Link to the Response section

Both endpoints return the same object.

{
  "created": 1793577600,
  "model": "google/gemini-3.1-flash-image",
  "data": [
    { "b64_json": "iVBORw0KGgoAAAANSUhEUgAA…", "output_format": "png" }
  ],
  "usage": { "images": 1, "credits": 650 }
}

When you ask for several images and some of them fail, the response contains only the ones that were produced: compare usage.images with n.

Headers: X-Moon-Request-Id, X-Moon-Prompt-Storage: none, X-Moon-Blur: not_applied (Moon Blur does not apply to images or to their description) and Cache-Control: no-store.

Models#Link to the Models section

List as of November 5, 2026; the current list, with prices, comes from GET /v1/models?type=image.

image_size is accepted only by models with several sizes.

Costs#Link to the Costs section

• Before the call, the request holds the most it can cost: max_credits_per_unit (or the value for the requested size) times the number of images, plus the images you send.
• Afterward, you pay the actual cost reported by the provider (or, failing that, the list price), and the rest of the hold is released right away.
• A request that fails, is refused before anything is created, or is cut off by our timeout costs nothing.
• A model that answers with text instead of an image (safety refusal, misunderstood prompt) charges for the text it wrote, and the API responds with 400 content_policy_violation: rephrase the prompt.

See Costs and wallet for holds and settlement.

Limits#Link to the Limits section

• All the images in a request are made at the same time; the request responds within about 90 seconds at most.
• At most 8 image requests in flight at once per workspace (beyond that: 429 too_many_concurrent, Retry-After: 5).

Errors#Link to the Errors section

Key, balance and spend cap errors are in Errors.

See also#Link to the See also section

• Models: the aspect_ratios, image_sizes and max_input_images fields.
• Balance and request cost: look up the cost again with X-Moon-Request-Id.