Image Generation

Try image generation

Build a text-to-image request.

Try image editing

Add reference images and an editing prompt.

Use a current public model ID from Models or GET /models. Example IDs and options must match the selected model’s advertised capabilities and limits.

Generate or edit images with the same API key and credit balance you use for text requests. Choose an image model in your Models dashboard, or query the authenticated List models endpoint and find entries with type: image.

Choose an image model

Open Models and choose Images, or find entries with type: image from GET /models. Their limits list prompt length, reference counts, resolutions, aspect ratios and output formats. Image models use image endpoints; text models use /chat/completions. A minimum of zero reference images allows generation from a prompt alone. A positive minimum requires that many reference images. Use the model’s public id in requests.

Generate an image

POST /images/generations

curl
Python

curl https://api.nomask.ai/v1/images/generations \
  -H "Authorization: Bearer $NOMASK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "YOUR_IMAGE_MODEL",
  "prompt": "A quiet mountain lake at sunrise",
  "n": 1,
  "response_format": "b64_json",
  "output_format": "png"
}'

import base64
import requests

response = requests.post(
    "https://api.nomask.ai/v1/images/generations",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
    "model": "YOUR_IMAGE_MODEL",
    "prompt": "A quiet mountain lake at sunrise",
    "n": 1,
    "response_format": "b64_json",
    "output_format": "png"
},
)
response.raise_for_status()
result = response.json()
with open("image.png", "wb") as image:
    image.write(base64.b64decode(result["data"][0]["b64_json"]))

Image requests return one completed JSON response. Streaming is currently unsupported, and n must be 1.

Edit with reference images

POST /images/edits Send a PNG, JPEG or WebP file as multipart image, or repeated image[] fields for multiple references. Check the selected model’s minimum and maximum before uploading.

curl https://api.nomask.ai/v1/images/edits \
  -H "Authorization: Bearer $NOMASK_API_KEY" \
  -F 'model=YOUR_EDITING_MODEL' \
  -F 'prompt=Keep the subject and add warm studio lighting' \
  -F 'image=@reference.png' \
  -F 'n=1' \
  -F 'response_format=b64_json' \
  -F 'output_format=png'

For JSON, send images as an array of base64 image data URLs. The image alias accepts one data URL or an array. Remote image URLs and masks are unsupported. The generation endpoint also accepts JSON references when the model supports them.

{
  "model": "YOUR_EDITING_MODEL",
  "prompt": "Keep the subject and add warm studio lighting",
  "images": [
    "data:image/png;base64,BASE64_IMAGE"
  ],
  "n": 1,
  "response_format": "b64_json",
  "output_format": "png"
}

Request parameters

`model`

Type: string · Required The image model’s public API ID.

`prompt`

Type: string · Required The instruction, within limits.max_prompt_characters.

`n`

Type: integer · Default: 1 Only one output image per request is supported.

`response_format`

Type: string · Default: b64_json Only b64_json is supported. Images are returned inline, without hosted URLs.

`resolution`

Type: string An advertised resolution tier from limits.supported_resolutions. Omit to use the default.

`aspect_ratio`

Type: string An advertised ratio from limits.supported_aspect_ratios. Omit to use the default.

`size`

Type: string An alias accepting auto, an advertised tier or a WIDTHxHEIGHT value that maps to a supported resolution and ratio. Prefer resolution and aspect_ratio; pixel dimensions are not a guarantee of exact output size.

`output_format`

Type: string · Default: png png, jpg, jpeg or webp, within the model’s output formats. jpeg is an alias for jpg. Image requests do not accept chat messages, function tools, reasoning controls, masks or a quality setting.

Response and usage

Generation and editing return the same response structure. This example has no reported token counters:

{
  "created": 1793617200,
  "request_id": "req_example_image_request",
  "model": "YOUR_PER_IMAGE_MODEL",
  "data": [
    {
      "b64_json": "BASE64_IMAGE_BYTES",
      "mime_type": "image/png",
      "width": 1024,
      "height": 1024
    }
  ],
  "usage": {
    "input_tokens": 0,
    "output_tokens": 0,
    "prompt_tokens": 0,
    "completion_tokens": 0,
    "total_tokens": 0,
    "images": 1,
    "tokens_reported": false
  },
  "nomask": {
    "cost_usd": 0.04,
    "model_cost_usd": 0.04,
    "resolution": "1K",
    "aspect_ratio": "auto",
    "output_format": "png",
    "reference_images": 0,
    "pricing_type": "resolution"
  }
}

Decode data[0].b64_json and save the bytes in your application. mime_type, width and height describe the actual returned image. request_id matches the X-Request-Id response header. When token usage is reported, the same response includes the actual counters:

{
  "created": 1793617200,
  "request_id": "req_example_image_request",
  "model": "YOUR_PER_IMAGE_MODEL",
  "data": [
    {
      "b64_json": "BASE64_IMAGE_BYTES",
      "mime_type": "image/png",
      "width": 1024,
      "height": 1024
    }
  ],
  "usage": {
    "input_tokens": 1000,
    "output_tokens": 500,
    "prompt_tokens": 1000,
    "completion_tokens": 500,
    "total_tokens": 1500,
    "images": 1,
    "tokens_reported": true
  },
  "nomask": {
    "cost_usd": 0.04,
    "model_cost_usd": 0.04,
    "resolution": "1K",
    "aspect_ratio": "auto",
    "output_format": "png",
    "reference_images": 0,
    "pricing_type": "resolution"
  }
}

input_tokens and prompt_tokens are the same input count; output_tokens and completion_tokens are the same output count. total_tokens is their sum, and usage.images is the returned image count. If counters are unavailable, tokens_reported is false and token fields are zero. Those zeros are not measured usage. Reported zero usage has tokens_reported: true. nomask.cost_usd and nomask.model_cost_usd are the settled USD charge. pricing_type is resolution for per-image billing or tokens for token billing. Per-image models use the selected resolution’s price; token-priced models use actual input and output counts and require reported usage before a charge can settle. nomask.resolution, aspect_ratio and output_format show the resolved request options; reference_images counts uploaded references. Resolution is null when the model has no resolution tiers. The actual pixel dimensions are in data.

Balance, limits and privacy

API image requests are billed in USD from your credit balance and follow the calling key’s monthly spending limit. Image Studio daily allowances do not apply.
Per-image prices are reserved before generation, then settled once. Failed requests are refunded; abandoned reservations are recovered automatically.
Image requests have requests per minute (RPM) and requests per day (RPD) limits. Usage is shared across your image models and API keys. Text API limits are separate; token limits do not apply to image requests.
Check the model’s rate_limit for requests_per_minute and requests_per_day. Switching models does not reset usage. Daily limits reset at midnight in Africa/Lagos.
API history stores usage metadata without prompts or image bytes. Results are returned inline and are not hosted as downloadable URLs. Save the returned bytes in your own application.

Response	What to check
400 / 413	Model, prompt length, reference count, file size, output options or an unsupported parameter.
402	Your available balance does not cover the request.
409	This idempotency key has already been accepted. Image responses are not cached for replay; keep your original response and use a new key for a new request.
429	Your RPM/RPD allowance or key’s monthly spending limit. Follow `Retry-After` when present. See rate-limit headers for minute and daily balances.
5xx	Image generation could not finish. Keep the response request ID when reporting the failure.

Docs

Getting Started

Text & Chat

Image

Production

Coding Tools

Chat API

Image API

Model API

Account & Usage

Errors & Limits

Image Generation

Try image generation

Try image editing

Choose an image model

Generate an image

Edit with reference images

Request parameters

`model`

`prompt`

`n`

`response_format`

`resolution`

`aspect_ratio`

`size`

`output_format`

Response and usage

Balance, limits and privacy

Try image generation

Try image editing

​Choose an image model

​Generate an image

​Edit with reference images

​Request parameters

​model

​prompt

​n

​response_format

​resolution

​aspect_ratio

​size

​output_format

​Response and usage

​Balance, limits and privacy

Choose an image model

Generate an image

Edit with reference images

Request parameters

`model`

`prompt`

`n`

`response_format`

`resolution`

`aspect_ratio`

`size`

`output_format`

Response and usage

Balance, limits and privacy