> ## 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. # Image API > Discover image models, inspect endpoint metadata and pricing, and generate images through NanoGPT's normalized Image API. ## 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: ```http theme={null} Authorization: Bearer YOUR_API_KEY ``` or: ```http theme={null} x-api-key: YOUR_API_KEY ``` Model discovery routes can be called without authentication. Generation requests require an API key. ## Quickstart ```bash theme={null} curl https://nano-gpt.com/api/v1/images/models ``` ```bash theme={null} curl https://nano-gpt.com/api/v1/images/models/gpt-image-2/endpoints ``` ```bash theme={null} 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: ```http theme={null} GET /api/v1/images/models ``` Response: ```json theme={null} { "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](/api-reference/endpoint/image-api-models) for the endpoint reference. ## Inspect Endpoint Metadata And Pricing Get public endpoint metadata for a model: ```http theme={null} GET /api/v1/images/models/{modelId}/endpoints ``` Example: ```http theme={null} 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: ```json theme={null} { "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](/api-reference/endpoint/image-api-model-endpoints) for the endpoint reference. ## Generate Images Generate images with: ```http theme={null} POST /api/v1/images Content-Type: application/json ``` Text-to-image request: ```json theme={null} { "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: ```json theme={null} { "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](/api-reference/endpoint/image-api-generate) for the endpoint reference. ## Image References `input_references` accepts an array of image references. Supported entries: ```json theme={null} [ "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: ```http theme={null} 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. ```json theme={null} { "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: ```json theme={null} { "provider": { "only": ["openai"] } } ``` Non-empty provider objects return: ```json theme={null} { "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 ```json theme={null} { "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. ```json theme={null} { "error": { "message": "/api/v1/images accepts application/json requests.", "type": "invalid_request_error", "code": "invalid_content_type" }, "code": "invalid_content_type" } ``` ### Invalid Input References ```json theme={null} { "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 ```json theme={null} { "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" } ```