Skip to main content
POST
/
v1
/
images
/
generations
cURL
curl --request POST \
  --url https://nano-gpt.com/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "prompt": "<string>",
  "model": "hidream",
  "n": 1,
  "size": "<string>",
  "response_format": "b64_json",
  "user": "<string>",
  "imageDataUrl": "data:image/jpeg;base64,/9j/4AAQ...",
  "imageDataUrls": [
    "data:image/jpeg;base64,/9j/4AAQ...",
    "data:image/png;base64,iVBORw0KGgo..."
  ],
  "maskDataUrl": "data:image/png;base64,iVBORw0KGgo...",
  "strength": 0.8,
  "guidance_scale": 7.5,
  "num_inference_steps": 30,
  "seed": 42,
  "kontext_max_mode": false
}
'
{
  "created": 123,
  "data": [
    {
      "url": "https://...signed-url..."
    }
  ],
  "cost": 123,
  "paymentSource": "<string>",
  "remainingBalance": 123
}

Documentation Index

Fetch the complete documentation index at: https://docs.nano-gpt.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

Generate images from text prompts or base64 image inputs using the OpenAI-compatible endpoint. Responses include base64 bytes (b64_json) by default or signed URLs (url) when response_format: "url".

​
Endpoint

  • Method/Path: POST https://nano-gpt.com/v1/images/generations
  • Auth: Authorization: Bearer <API_KEY>
  • Required header: Content-Type: application/json

​
Request Body (JSON)

Core fields:
  • prompt (string, required): Text prompt to generate an image from.
  • model (string, optional): Model ID (default hidream).
  • n (integer, optional): Number of images to generate (default 1).
  • size (string, optional): Requested output size or model-specific resolution value. Use GET /api/v1/image-models?detailed=true and read supported_parameters.resolutions for the selected model’s supported values.
  • response_format (string, optional): b64_json (default) or url.
  • user (string, optional): End-user identifier.
Image inputs (img2img/inpainting):
  • imageDataUrl (string, optional): Base64 data URL for a single input image.
  • imageDataUrls (array, optional): Multiple base64 data URLs for supported models.
  • maskDataUrl (string, optional): Base64 mask data URL for inpainting.
Image-to-image controls (model-specific):
  • strength, guidance_scale, num_inference_steps, seed, kontext_max_mode.
For OpenAI-compatible image editing, use Image Edits.

​
Response

  • Each data[i] contains either b64_json (default) or url (when response_format: "url"), never both.
  • When requesting response_format: "url", the API may still return b64_json if URL generation (upload/presign) fails, as a fallback.
  • Signed URLs expire after a short period (currently ~1 hour). Download promptly for long-term storage.

​
Examples

curl https://nano-gpt.com/v1/images/generations \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "hidream",
    "prompt": "A sunset over a mountain range",
    "n": 1,
    "size": "1024x1024"
  }'

​
Notes & Limits

  • Input images must be provided as base64 data URLs; download and convert remote images before sending.
  • Uploads should be 4 MB or smaller after encoding. Compress or resize large assets before sending.
  • Use GET /api/v1/image-models?detailed=true to discover current image model capabilities and supported resolution values.

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Parameters for image generation

​
prompt
string
required

The text prompt to generate an image from

​
model
string
default:hidream

The model to use for generation

​
n
integer
default:1

Number of images to generate

​
size
string

Requested output size or model-specific resolution value. Use GET /api/v1/image-models?detailed=true and read supported_parameters.resolutions for the selected model's supported values.

Examples:

"1024x1024"

"1376x768"

"auto"

​
response_format
enum<string>
default:b64_json

The format in which the generated images are returned. Use "b64_json" (default) to receive base64-encoded image bytes in data[i].b64_json, or "url" to receive a time-limited, signed download URL in data[i].url (expires after a short period, currently ~1 hour). Note: When requesting "url", the API may still return "b64_json" if URL generation (upload/presign) fails, as a fallback.

Available options:
url,
b64_json
​
user
string

A unique identifier representing your end-user

​
imageDataUrl
string

Base64-encoded image data URL for img2img generation. Single image input for models that support image-to-image transformation. Format: data:image/[type];base64,[data]. Note: Direct URL input is not supported - images must be converted to base64 data URLs before submission.

Example:

"data:image/jpeg;base64,/9j/4AAQ..."

​
imageDataUrls
string<data-url>[]

Array of base64-encoded image data URLs for models supporting multiple image inputs (e.g., flux-kontext, gpt-4o-image, gpt-image-1). Each URL must follow the format: data:image/[type];base64,[data]

Example:
[
  "data:image/jpeg;base64,/9j/4AAQ...",
  "data:image/png;base64,iVBORw0KGgo..."
]
​
maskDataUrl
string

Base64-encoded mask image data URL for inpainting models (e.g., flux-lora/inpainting). White areas indicate regions to edit. Format: data:image/[type];base64,[data]

Example:

"data:image/png;base64,iVBORw0KGgo..."

​
strength
number
default:0.8

Controls how much the output differs from the input image in img2img mode. Lower values produce outputs closer to the input.

Required range: 0 <= x <= 1
​
guidance_scale
number
default:7.5

How closely the model follows the text prompt. Higher values result in images more closely aligned with the prompt.

Required range: 0 <= x <= 20
​
num_inference_steps
integer
default:30

Number of denoising steps. More steps generally produce higher quality but take longer.

Required range: 1 <= x <= 100
​
seed
integer

Random seed for reproducible generation. Use the same seed with the same parameters to get identical results.

Example:

42

​
kontext_max_mode
boolean
default:false

Enable enhanced context mode for flux-kontext model. Provides better understanding of input images.

Response

Image generation response. Each data[i] contains either { url } or { b64_json }. When requesting response_format: "url", the API may fall back to returning { b64_json } if URL generation (upload/presign) fails.

​
created
integer

Unix timestamp of when the image was created

​
data
object[]

List of generated images. Each entry contains either a hosted URL (data[i].url) or base64-encoded bytes (data[i].b64_json), never both.

Example:
{ "url": "https://...signed-url..." }
​
cost
number

Cost of the generation

​
paymentSource
string

Payment source used

​
remainingBalance
number

Remaining balance after the generation