Image API

Generate an image

Generate one image from a prompt, optionally with references supported by the model. Use a current image model ID and its advertised prompt, reference-count, resolution and aspect-ratio limits. Accepts JSON base64 data URLs or multipart PNG/JPEG/WebP files. Remote image URLs, masks, quality controls and streaming are unsupported. Reference bytes total at most 25 MiB; JSON bodies are limited to 40 MiB. Paid requests debit your NoMask balance.

POST

images

generations

Generate an image

curl --request POST \
  --url https://api.nomask.ai/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "model": "your-image-model-id",
  "prompt": "A quiet mountain lake at sunrise",
  "n": 1,
  "response_format": "b64_json",
  "output_format": "png"
}
'

import requests

url = "https://api.nomask.ai/v1/images/generations"

payload = {
    "model": "your-image-model-id",
    "prompt": "A quiet mountain lake at sunrise",
    "n": 1,
    "response_format": "b64_json",
    "output_format": "png"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    model: 'your-image-model-id',
    prompt: 'A quiet mountain lake at sunrise',
    n: 1,
    response_format: 'b64_json',
    output_format: 'png'
  })
};

fetch('https://api.nomask.ai/v1/images/generations', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "created": 1793617200,
  "request_id": "req_example",
  "model": "your-image-model-id",
  "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"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "code": "<string>",
    "param": "<string>"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "code": "<string>",
    "param": "<string>"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "code": "<string>",
    "param": "<string>"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "code": "<string>",
    "param": "<string>"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "code": "<string>",
    "param": "<string>"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "code": "<string>",
    "param": "<string>"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "code": "<string>",
    "param": "<string>"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "code": "<string>",
    "param": "<string>"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "code": "<string>",
    "param": "<string>"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "code": "<string>",
    "param": "<string>"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "code": "<string>",
    "param": "<string>"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "code": "<string>",
    "param": "<string>"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "code": "<string>",
    "param": "<string>"
  }
}

Authorizations

Authorization

string

header

required

Create a NoMask API key at https://nomask.ai/api/keys. Keep it private; enter only your own key when sending a request.

Headers

Idempotency-Key

string

Optional duplicate protection for 24 hours. A reused accepted key returns 409; image bytes are not cached for replay.

Required string length: 1 - 255

Pattern: ^[!-~]+$

Body

Reference images must be PNG, JPEG or WebP; decoded references total at most 25 MiB. JSON body limit is 40 MiB. Each image must be at most 16384 pixels per side and 40 million pixels.

model

string

required

Current public image model ID from GET /models.

Required string length: 1 - 150

Example:

"your-image-model-id"

prompt

string

required

Nonempty UTF-8 prompt, within this model's limits.max_prompt_characters.

Minimum string length: 1

Example:

"A quiet mountain lake at sunrise"

enum<integer>

default:1

One output image.

Available options:

1

response_format

enum<string>

default:b64_json

Images are returned inline; hosted URL responses are unavailable.

Available options:

b64_json

resolution

string

An advertised tier from limits.supported_resolutions. Omit to use the model default.

aspect_ratio

string

An advertised value from limits.supported_aspect_ratios. Omit to use the model default.

size

string

default:auto

Alias accepting auto, an advertised resolution tier, or WIDTHxHEIGHT that maps to a supported tier and aspect ratio. Conflicting explicit options are rejected; exact pixel dimensions are not guaranteed.

output_format

enum<string>

default:png

Output format. jpeg is normalized to jpg.

Available options:

png,

jpg,

jpeg,

webp

format

enum<string>

Alias used when output_format is absent.

Available options:

png,

jpg,

jpeg,

webp

stream

enum<boolean>

default:false

Images return completed JSON only.

Available options:

false

user

string

Accepted for client compatibility; it does not affect image generation.

image

Single reference data URL or a list. Use either image or images, never both.

Pattern: ^data:image/(png|jpeg|webp);base64,

Example:

"data:image/png;base64,BASE64_IMAGE_BYTES"

images

Reference data URL(s). The model controls the minimum and maximum count.

Pattern: ^data:image/(png|jpeg|webp);base64,

Example:

"data:image/png;base64,BASE64_IMAGE_BYTES"

Response

Successful response. Example values are illustrative.

created

integer<int64>

required

Unix timestamp.

request_id

string

required

Matches the X-Request-Id header.

model

string

required

Public image model ID.

data

object[]

required

Required array length: 1 element

Show child attributes

usage

object

required

Show child attributes

nomask

object

required

Show child attributes

Generate an image

curl --request POST \
  --url https://api.nomask.ai/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "model": "your-image-model-id",
  "prompt": "A quiet mountain lake at sunrise",
  "n": 1,
  "response_format": "b64_json",
  "output_format": "png"
}
'

import requests

url = "https://api.nomask.ai/v1/images/generations"

payload = {
    "model": "your-image-model-id",
    "prompt": "A quiet mountain lake at sunrise",
    "n": 1,
    "response_format": "b64_json",
    "output_format": "png"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    model: 'your-image-model-id',
    prompt: 'A quiet mountain lake at sunrise',
    n: 1,
    response_format: 'b64_json',
    output_format: 'png'
  })
};

fetch('https://api.nomask.ai/v1/images/generations', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "created": 1793617200,
  "request_id": "req_example",
  "model": "your-image-model-id",
  "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"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "code": "<string>",
    "param": "<string>"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "code": "<string>",
    "param": "<string>"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "code": "<string>",
    "param": "<string>"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "code": "<string>",
    "param": "<string>"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "code": "<string>",
    "param": "<string>"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "code": "<string>",
    "param": "<string>"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "code": "<string>",
    "param": "<string>"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "code": "<string>",
    "param": "<string>"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "code": "<string>",
    "param": "<string>"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "code": "<string>",
    "param": "<string>"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "code": "<string>",
    "param": "<string>"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "code": "<string>",
    "param": "<string>"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "code": "<string>",
    "param": "<string>"
  }
}

Docs

Getting Started

Text & Chat

Image

Production

Coding Tools

Chat API

Image API

Model API

Account & Usage

Errors & Limits

Generate an image

Authorizations

Headers

Body

Response