Image Generation (OpenAI-Compatible)

cURL

curl --request POST \
  --url https://api.nano-gpt.com/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "prompt": "<string>",
  "model": "hidream",
  "n": 1,
  "size": "1024x1024",
  "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
}
'

import requests

url = "https://api.nano-gpt.com/v1/images/generations"

payload = {
    "prompt": "<string>",
    "model": "hidream",
    "n": 1,
    "size": "1024x1024",
    "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
}
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({
    prompt: '<string>',
    model: 'hidream',
    n: 1,
    size: '1024x1024',
    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
  })
};

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

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.nano-gpt.com/v1/images/generations",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'prompt' => '<string>',
    'model' => 'hidream',
    'n' => 1,
    'size' => '1024x1024',
    '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
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.nano-gpt.com/v1/images/generations"

	payload := strings.NewReader("{\n  \"prompt\": \"<string>\",\n  \"model\": \"hidream\",\n  \"n\": 1,\n  \"size\": \"1024x1024\",\n  \"response_format\": \"b64_json\",\n  \"user\": \"<string>\",\n  \"imageDataUrl\": \"data:image/jpeg;base64,/9j/4AAQ...\",\n  \"imageDataUrls\": [\n    \"data:image/jpeg;base64,/9j/4AAQ...\",\n    \"data:image/png;base64,iVBORw0KGgo...\"\n  ],\n  \"maskDataUrl\": \"data:image/png;base64,iVBORw0KGgo...\",\n  \"strength\": 0.8,\n  \"guidance_scale\": 7.5,\n  \"num_inference_steps\": 30,\n  \"seed\": 42,\n  \"kontext_max_mode\": false\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.nano-gpt.com/v1/images/generations")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"prompt\": \"<string>\",\n  \"model\": \"hidream\",\n  \"n\": 1,\n  \"size\": \"1024x1024\",\n  \"response_format\": \"b64_json\",\n  \"user\": \"<string>\",\n  \"imageDataUrl\": \"data:image/jpeg;base64,/9j/4AAQ...\",\n  \"imageDataUrls\": [\n    \"data:image/jpeg;base64,/9j/4AAQ...\",\n    \"data:image/png;base64,iVBORw0KGgo...\"\n  ],\n  \"maskDataUrl\": \"data:image/png;base64,iVBORw0KGgo...\",\n  \"strength\": 0.8,\n  \"guidance_scale\": 7.5,\n  \"num_inference_steps\": 30,\n  \"seed\": 42,\n  \"kontext_max_mode\": false\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.nano-gpt.com/v1/images/generations")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"prompt\": \"<string>\",\n  \"model\": \"hidream\",\n  \"n\": 1,\n  \"size\": \"1024x1024\",\n  \"response_format\": \"b64_json\",\n  \"user\": \"<string>\",\n  \"imageDataUrl\": \"data:image/jpeg;base64,/9j/4AAQ...\",\n  \"imageDataUrls\": [\n    \"data:image/jpeg;base64,/9j/4AAQ...\",\n    \"data:image/png;base64,iVBORw0KGgo...\"\n  ],\n  \"maskDataUrl\": \"data:image/png;base64,iVBORw0KGgo...\",\n  \"strength\": 0.8,\n  \"guidance_scale\": 7.5,\n  \"num_inference_steps\": 30,\n  \"seed\": 42,\n  \"kontext_max_mode\": false\n}"

response = http.request(request)
puts response.read_body

{
  "created": 123,
  "data": [
    {
      "url": "https://...signed-url..."
    }
  ],
  "cost": 123,
  "paymentSource": "<string>",
  "remainingBalance": 123
}

POST

images

generations

cURL

curl --request POST \
  --url https://api.nano-gpt.com/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "prompt": "<string>",
  "model": "hidream",
  "n": 1,
  "size": "1024x1024",
  "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
}
'

import requests

url = "https://api.nano-gpt.com/v1/images/generations"

payload = {
    "prompt": "<string>",
    "model": "hidream",
    "n": 1,
    "size": "1024x1024",
    "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
}
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({
    prompt: '<string>',
    model: 'hidream',
    n: 1,
    size: '1024x1024',
    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
  })
};

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

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.nano-gpt.com/v1/images/generations",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'prompt' => '<string>',
    'model' => 'hidream',
    'n' => 1,
    'size' => '1024x1024',
    '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
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.nano-gpt.com/v1/images/generations"

	payload := strings.NewReader("{\n  \"prompt\": \"<string>\",\n  \"model\": \"hidream\",\n  \"n\": 1,\n  \"size\": \"1024x1024\",\n  \"response_format\": \"b64_json\",\n  \"user\": \"<string>\",\n  \"imageDataUrl\": \"data:image/jpeg;base64,/9j/4AAQ...\",\n  \"imageDataUrls\": [\n    \"data:image/jpeg;base64,/9j/4AAQ...\",\n    \"data:image/png;base64,iVBORw0KGgo...\"\n  ],\n  \"maskDataUrl\": \"data:image/png;base64,iVBORw0KGgo...\",\n  \"strength\": 0.8,\n  \"guidance_scale\": 7.5,\n  \"num_inference_steps\": 30,\n  \"seed\": 42,\n  \"kontext_max_mode\": false\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.nano-gpt.com/v1/images/generations")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"prompt\": \"<string>\",\n  \"model\": \"hidream\",\n  \"n\": 1,\n  \"size\": \"1024x1024\",\n  \"response_format\": \"b64_json\",\n  \"user\": \"<string>\",\n  \"imageDataUrl\": \"data:image/jpeg;base64,/9j/4AAQ...\",\n  \"imageDataUrls\": [\n    \"data:image/jpeg;base64,/9j/4AAQ...\",\n    \"data:image/png;base64,iVBORw0KGgo...\"\n  ],\n  \"maskDataUrl\": \"data:image/png;base64,iVBORw0KGgo...\",\n  \"strength\": 0.8,\n  \"guidance_scale\": 7.5,\n  \"num_inference_steps\": 30,\n  \"seed\": 42,\n  \"kontext_max_mode\": false\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.nano-gpt.com/v1/images/generations")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"prompt\": \"<string>\",\n  \"model\": \"hidream\",\n  \"n\": 1,\n  \"size\": \"1024x1024\",\n  \"response_format\": \"b64_json\",\n  \"user\": \"<string>\",\n  \"imageDataUrl\": \"data:image/jpeg;base64,/9j/4AAQ...\",\n  \"imageDataUrls\": [\n    \"data:image/jpeg;base64,/9j/4AAQ...\",\n    \"data:image/png;base64,iVBORw0KGgo...\"\n  ],\n  \"maskDataUrl\": \"data:image/png;base64,iVBORw0KGgo...\",\n  \"strength\": 0.8,\n  \"guidance_scale\": 7.5,\n  \"num_inference_steps\": 30,\n  \"seed\": 42,\n  \"kontext_max_mode\": false\n}"

response = http.request(request)
puts response.read_body

{
  "created": 123,
  "data": [
    {
      "url": "https://...signed-url..."
    }
  ],
  "cost": 123,
  "paymentSource": "<string>",
  "remainingBalance": 123
}

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". For new integrations that do not need OpenAI-compatible request shapes, use the dedicated Image API. It supports image model discovery, endpoint metadata, public pricing metadata, and normalized generation through POST /api/v1/images.

Endpoint

Method/Path: POST https://api.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.

Generation controls (model-specific):

strength, guidance_scale, num_inference_steps, kontext_max_mode.
seed is an optional model-specific hint that may improve reproducibility where supported. Identical results are not guaranteed. Check the selected model’s supported_parameters metadata before using this field.

GPT Image output controls (gpt-image-1, gpt-image-1.5, gpt-image-2, and the GPT Image 2.5 Flare and Sunburst models):

quality (string, optional): Model-specific quality level, for example low, medium, or high. GPT Image 2.5 also accepts xhigh and max.
output_format (string, optional): png, jpeg, or webp.
output_compression (integer, optional): 0–100. Applies to jpeg and webp output only.
background (string, optional, not supported by gpt-image-2): auto (default), opaque, or transparent. transparent requires output_format png or webp. If the prompt describes a backdrop, the model may draw it instead of leaving the background transparent. Requests with opaque or transparent are only routed to providers that support the setting, so they never fall back to one that would ignore it.

See Supported Parameter Discovery for the discovery workflow. If a model/provider route offers a stronger reproducibility guarantee, rely only on documentation for that specific route. 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://api.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"
  }'

curl https://api.nano-gpt.com/v1/images/generations \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "hidream",
    "prompt": "A neon city skyline at night",
    "n": 1,
    "size": "1024x1024",
    "response_format": "url"
  }'

curl https://api.nano-gpt.com/v1/images/generations \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-image-2.5/flare/text-to-image",
    "prompt": "A glossy red game controller icon, isolated object",
    "n": 1,
    "size": "1024x1024",
    "background": "transparent",
    "output_format": "png"
  }'

import base64
import requests

API_KEY = "YOUR_API_KEY"

with open("input.jpg", "rb") as f:
    encoded = base64.b64encode(f.read()).decode("utf-8")
    image_data_url = f"data:image/jpeg;base64,{encoded}"

response = requests.post(
    "https://api.nano-gpt.com/v1/images/generations",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    json={
        "model": "flux-kontext",
        "prompt": "Transform this image into a watercolor painting",
        "n": 1,
        "size": "1024x1024",
        "imageDataUrl": image_data_url,
    },
)

result = response.json()

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. For seed and other model-specific fields, also consult the Image API supported-parameter guidance.

Authorizations

Authorization

string

header

required

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

Headers

x-x402

enum<string>

Set to true on unauthenticated accountless x402 quote requests. Without this header, unauthenticated requests return 401 missing_api_key.

Available options:

true

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

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

Optional model-specific seed that may improve reproducibility where supported by the model/provider route. Identical results are not guaranteed. Check the selected model's supported_parameters metadata before using this field.

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.

Option 1
Option 2

Show child attributes

Example:

{ "url": "https://...signed-url..." }

cost

number

Cost of the generation

paymentSource

string

Payment source used

remainingBalance

number

Remaining balance after the generation

Get Started

Endpoint Examples

API Reference

Miscellaneous

Partner

Integrations

Overview

Endpoint

Request Body (JSON)

Response

Examples

Notes & Limits

Authorizations

Headers

Body

Response

​Overview

​Endpoint

​Request Body (JSON)

​Response

​Examples

​Notes & Limits

Authorizations

Headers

Body

Response

Overview

Endpoint

Request Body (JSON)

Response

Examples

Notes & Limits