Image API - NanoGPT API Documentation

Overview

NanoGPT provides a dedicated Image API for discovering image models, inspecting supported parameters and pricing, and generating images through a normalized endpoint. Use this API when you want one image workflow:

Discover available image models with machine-readable capabilities.
Inspect a model’s public endpoint metadata, supported parameters, pricing, and image-input constraints.
Generate text-to-image and image-to-image outputs through POST /api/v1/images.

Existing image routes remain supported for compatibility:

POST /api/v1/images/generations
POST /api/v1/images/edits
POST /api/v1/images/edit
GET /api/v1/image-models

The dedicated Image API is additive. New integrations should prefer the normalized routes below.

Authentication

Use the same NanoGPT API key authentication as other API routes:

Authorization: Bearer YOUR_API_KEY

or:

x-api-key: YOUR_API_KEY

Model discovery routes can be called without authentication. Generation requests require an API key.

Quickstart

curl https://nano-gpt.com/api/v1/images/models

curl https://nano-gpt.com/api/v1/images/models/gpt-image-2/endpoints

curl https://nano-gpt.com/api/v1/images \
  -H "Content-Type: application/json" \
  -H "x-api-key: $NANOGPT_API_KEY" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A clean product photo of a matte black espresso machine",
    "resolution": "1024x1024",
    "quality": "medium",
    "n": 1
  }'

Discover Image Models

List image models:

GET /api/v1/images/models

Response:

{
  "object": "list",
  "data": [
    {
      "id": "gpt-image-2",
      "name": "GPT Image 2",
      "description": "Model description...",
      "created": 1760000000,
      "owned_by": "openai",
      "architecture": {
        "input_modalities": ["text", "image"],
        "output_modalities": ["image"]
      },
      "supported_parameters": {
        "resolution": {
          "type": "enum",
          "values": ["1024x1024", "1024x768"],
          "default": "1024x1024"
        },
        "n": {
          "type": "range",
          "min": 1,
          "max": 4,
          "default": 1
        },
        "quality": {
          "type": "enum",
          "values": ["low", "medium", "high"],
          "default": "medium"
        },
        "input_references": {
          "type": "range",
          "min": 0,
          "max": 4
        }
      },
      "supports_streaming": false,
      "endpoints": "/api/v1/images/models/gpt-image-2/endpoints",
      "capabilities": {
        "image_generation": true,
        "image_to_image": true,
        "inpainting": false,
        "nsfw": false
      },
      "category": "image"
    }
  ],
  "meta": {
    "count": 201,
    "generated_at": "2026-06-25T00:00:00.000Z"
  }
}

Notes:

id is the model ID to use in POST /api/v1/images.
endpoints is the URL for endpoint and pricing metadata for that model.
supported_parameters is machine-readable and varies by model.
supports_streaming is currently always false.
Model IDs may contain slashes. Prefer using the returned endpoints URL directly.

See List Image Models for the endpoint reference.

Inspect Endpoint Metadata And Pricing

Get public endpoint metadata for a model:

GET /api/v1/images/models/{modelId}/endpoints

Example:

GET /api/v1/images/models/gpt-image-2/endpoints

For model IDs that contain slashes, use the endpoints path returned by GET /api/v1/images/models. Response:

{
  "id": "gpt-image-2",
  "endpoints": [
    {
      "provider_name": "OpenAI",
      "provider_slug": "openai",
      "provider_tag": null,
      "supported_parameters": {
        "resolution": {
          "type": "enum",
          "values": ["1024x1024", "1024x768"],
          "default": "1024x1024"
        },
        "n": {
          "type": "range",
          "min": 1,
          "max": 4,
          "default": 1
        }
      },
      "allowed_passthrough_parameters": [],
      "supports_streaming": false,
      "pricing": [
        {
          "billable": "output_image",
          "unit": "image",
          "cost_usd": 0.06551,
          "resolution": "1024x1024"
        }
      ],
      "input_reference_constraints": {
        "max_items": 4,
        "route": {
          "min_width": 8,
          "min_height": 8,
          "max_bytes": 31457280,
          "formats": ["png", "jpeg", "webp"],
          "source": "route-preflight"
        }
      }
    }
  ]
}

Notes:

NanoGPT currently returns one public endpoint per model.
provider_tag is null because provider selection is not exposed yet.
allowed_passthrough_parameters is an empty array for now.
pricing uses public NanoGPT pricing, not provider at-cost rates.
input_reference_constraints is included when the model supports image inputs.

See Get Image Model Endpoints for the endpoint reference.

Generate Images

Generate images with:

POST /api/v1/images
Content-Type: application/json

Text-to-image request:

{
  "model": "gpt-image-2",
  "prompt": "A clean product photo of a matte black espresso machine on a white counter",
  "resolution": "1024x1024",
  "quality": "medium",
  "n": 1
}

Image-to-image request:

{
  "model": "gpt-image-2",
  "prompt": "Make this look like a polished studio product photo",
  "input_references": [
    {
      "type": "image_url",
      "image_url": {
        "url": "https://example.com/reference.png"
      }
    }
  ],
  "resolution": "1024x1024",
  "quality": "medium",
  "n": 1
}

Use n to request the number of output images. Internally, n is normalized to NanoGPT’s existing nImages parameter. If both are supplied, nImages takes precedence. See Generate Images for the endpoint reference.

Image References

input_references accepts an array of image references. Supported entries:

[
  "https://example.com/image.png",
  "data:image/png;base64,...",
  {
    "type": "image_url",
    "image_url": {
      "url": "https://example.com/image.png"
    }
  }
]

Do not mix input_references with legacy image aliases such as imageDataUrl, imageDataUrls, image_url, or images in the same request. The route returns conflicting_image_inputs if both styles are supplied.

Supported Parameter Discovery

Parameter support varies by model. Always check supported_parameters from:

GET /api/v1/images/models

Common fields include:

model
prompt
n
resolution
aspect_ratio
quality
output_format
seed
input_references

NanoGPT exposes many model-specific parameters. Treat them as discoverable via supported_parameters, not as globally supported fields.

Unsupported Features For Now

Streaming

stream: true is not supported yet.

{
  "error": {
    "message": "stream is not supported for /api/v1/images yet. Use non-streaming requests or /api/v1/images/generations.",
    "type": "invalid_request_error",
    "code": "unsupported_stream",
    "parameter": "stream"
  },
  "code": "unsupported_stream"
}

Provider Selection

Provider selection and provider passthrough are not supported yet on POST /api/v1/images. Do not send provider routing or provider passthrough options:

{
  "provider": {
    "only": ["openai"]
  }
}

Non-empty provider objects return:

{
  "error": {
    "message": "Provider selection and provider passthrough options are not supported for /api/v1/images yet.",
    "type": "invalid_request_error",
    "code": "unsupported_provider_options",
    "parameter": "provider"
  },
  "code": "unsupported_provider_options"
}

Empty provider objects are ignored, but clients should not rely on that behavior.

Migration Notes

Use the dedicated Image API when building new image integrations. It provides model discovery, endpoint metadata, public pricing metadata, image-input constraints, and normalized JSON generation in one workflow. Use the legacy routes when you need their existing compatibility behavior:

Use POST /api/v1/images/generations or POST /v1/images/generations for OpenAI-compatible image generation request shapes.
Use POST /api/v1/images/edits or POST /api/v1/images/edit for OpenAI-compatible image editing.
Use GET /api/v1/image-models if your integration already depends on the older image model list format.

Do not assume field names are interchangeable between the normalized Image API and legacy endpoints. For example, POST /api/v1/images uses input_references; older routes support aliases such as imageDataUrl and imageDataUrls.

Error Reference

Missing Model

{
  "error": {
    "message": "model is required for /api/v1/images.",
    "type": "invalid_request_error",
    "code": "missing_model",
    "parameter": "model"
  },
  "code": "missing_model"
}

Invalid Content Type

POST /api/v1/images accepts JSON only.

{
  "error": {
    "message": "/api/v1/images accepts application/json requests.",
    "type": "invalid_request_error",
    "code": "invalid_content_type"
  },
  "code": "invalid_content_type"
}

Invalid Input References

{
  "error": {
    "message": "input_references must be an array of image URL strings or image_url objects.",
    "type": "invalid_request_error",
    "code": "invalid_input_references",
    "parameter": "input_references"
  },
  "code": "invalid_input_references"
}

Conflicting Image Inputs

{
  "error": {
    "message": "Use input_references or image input aliases, not both.",
    "type": "invalid_request_error",
    "code": "conflicting_image_inputs",
    "parameter": "input_references"
  },
  "code": "conflicting_image_inputs"
}

​Overview

​Authentication

​Quickstart

​Discover Image Models

​Inspect Endpoint Metadata And Pricing

​Generate Images

​Image References

​Supported Parameter Discovery

​Unsupported Features For Now

​Streaming

​Provider Selection

​Migration Notes

​Error Reference

​Missing Model

​Invalid Content Type

​Invalid Input References

​Conflicting Image Inputs