Image Generation (OpenAI-Compatible) - NanoGPT API Documentation

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
}
'

import requests

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

payload = {
    "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
}
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: '<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
  })
};

fetch('https://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://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' => '<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
  ]),
  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://nano-gpt.com/v1/images/generations"

	payload := strings.NewReader("{\n  \"prompt\": \"<string>\",\n  \"model\": \"hidream\",\n  \"n\": 1,\n  \"size\": \"<string>\",\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://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\": \"<string>\",\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://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\": \"<string>\",\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://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
}
'

import requests

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

payload = {
    "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
}
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: '<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
  })
};

fetch('https://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://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' => '<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
  ]),
  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://nano-gpt.com/v1/images/generations"

	payload := strings.NewReader("{\n  \"prompt\": \"<string>\",\n  \"model\": \"hidream\",\n  \"n\": 1,\n  \"size\": \"<string>\",\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://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\": \"<string>\",\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://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\": \"<string>\",\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://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"
  }'

curl https://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"
  }'

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://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.

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

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.

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

Generate Images Image Edits

​Overview

​Endpoint

​Request Body (JSON)

​Response

​Examples

​Notes & Limits

Authorizations

Headers

Body

Response

Overview

Endpoint

Request Body (JSON)

Response

Examples

Notes & Limits