# Embeddings Source: https://docs.nano-gpt.com/api-reference/embeddings Complete guide to text embeddings API ## Overview NanoGPT provides a fully OpenAI-compatible embeddings API that offers access to both OpenAI's industry-leading embedding models and a curated selection of alternative embedding models at competitive prices. Our API supports 20+ embedding models (and this list changes over time); use `GET /api/v1/embedding-models` for the source-of-truth list. ## Quick Start ```python theme={null} from openai import OpenAI # Initialize client pointing to NanoGPT client = OpenAI( api_key="YOUR_NANOGPT_API_KEY", base_url="https://api.nano-gpt.com/api/v1" ) # Create embedding response = client.embeddings.create( input="Your text to embed", model="text-embedding-3-small" ) embedding = response.data[0].embedding print(f"Embedding has {len(embedding)} dimensions") ``` ## Available Models ### OpenAI Models | Model | Dimensions | Max Tokens | Price/1M tokens | Features | | - | - | - | - | - | | `text-embedding-3-small` | 1536 | 8191 | \$0.02 | Dimension reduction support, most cost-effective | | `text-embedding-3-large` | 3072 | 8191 | \$0.13 | Dimension reduction support, highest performance | | `text-embedding-ada-002` | 1536 | 8191 | \$0.10 | Legacy model, no dimension reduction | ### Alternative Models #### Multilingual Models | Model | Dimensions | Price/1M tokens | Description | | - | - | - | - | | `BAAI/bge-m3` | 1024 | \$0.01 | Excellent multilingual support | #### Language-Specific Models | Model | Language | Dimensions | Price/1M tokens | | - | - | - | - | | `BAAI/bge-base-en-v1.5` | English | 768 | \$0.005 | | `BAAI/bge-large-en-v1.5` | English | 1024 | \$0.01 | #### Specialized Models | Model | Use Case | Dimensions | Price/1M tokens | | - | - | - | - | | `Qwen/Qwen3-Embedding-0.6B` | General | 1024 | \$0.01 | | `Qwen/Qwen3-Embedding-4B` | General | 2560 | \$0.02 | | `Qwen/Qwen3-Embedding-8B` | General | 4096 | \$0.01 | | `gemini-embedding-001` | General | 3072 | \$0.15 | ### Zero Data Retention (ZDR) When ZDR-only routing is on for your account, API key, or team, embedding requests are accepted only for models with a Zero Data Retention route: * `Qwen/Qwen3-Embedding-0.6B` * `Qwen/Qwen3-Embedding-4B` * `qwen/qwen3-embedding-8b` * `BAAI/bge-m3` * `BAAI/bge-large-en-v1.5` * `BAAI/bge-base-en-v1.5` These requests use only providers that declare zero data retention. Other embedding models, including the OpenAI and Gemini models, return HTTP 400 with code `zero_data_retention` while ZDR-only routing is on. Without ZDR-only routing, ZDR-capable models may also be served by providers that retain data. [`GET /api/v1/embedding-models`](/api-reference/endpoint/embedding-models) reports this as `zero_data_retention` on each model. ## API Endpoints ### Create Embeddings **Endpoint:** `POST https://api.nano-gpt.com/api/v1/embeddings` Create embeddings for one or more text inputs. ### Discover Embedding Models **Endpoint:** `GET https://api.nano-gpt.com/api/v1/embedding-models` List all available embedding models with detailed information. ## Advanced Features ### Batch Processing Process multiple texts efficiently in a single request: ```python theme={null} texts = [ "First text to embed", "Second text to embed", "Third text to embed" ] response = client.embeddings.create( input=texts, # Pass array of strings model="text-embedding-3-small" ) # Access embeddings by index for i, data in enumerate(response.data): print(f"Text {i}: {len(data.embedding)} dimensions") ``` ### Dimension Reduction Reduce embedding dimensions for faster similarity comparisons (supported models only): ```python theme={null} # Reduce dimensions to 256 for faster processing response = client.embeddings.create( input="Your text here", model="text-embedding-3-small", dimensions=256 # Reduce from 1536 to 256 ) ``` Supported models for dimension reduction: * `text-embedding-3-small` * `text-embedding-3-large` * `Qwen/Qwen3-Embedding-0.6B` ### Base64 Encoding For more efficient data transfer, request base64-encoded embeddings: ```python theme={null} response = client.embeddings.create( input="Your text here", model="text-embedding-3-small", encoding_format="base64" # Returns base64-encoded bytes ) ``` ## Use Cases ### Semantic Search Build powerful search systems that understand meaning: ```python theme={null} import numpy as np from sklearn.metrics.pairwise import cosine_similarity # Create embeddings for your documents documents = ["Document 1 text", "Document 2 text", "Document 3 text"] doc_embeddings = [] for doc in documents: response = client.embeddings.create(input=doc, model="text-embedding-3-small") doc_embeddings.append(response.data[0].embedding) # Create embedding for search query query = "Search query text" query_response = client.embeddings.create(input=query, model="text-embedding-3-small") query_embedding = query_response.data[0].embedding # Calculate similarities similarities = cosine_similarity([query_embedding], doc_embeddings)[0] # Find most similar documents top_matches = np.argsort(similarities)[::-1][:3] for idx in top_matches: print(f"Document {idx}: {similarities[idx]:.3f} similarity") ``` ### RAG (Retrieval Augmented Generation) Enhance LLM responses with relevant context: ```python theme={null} # 1. Embed and store your knowledge base knowledge_base = [ {"text": "Company founded in 2020...", "embedding": None}, {"text": "Product features include...", "embedding": None}, ] for item in knowledge_base: response = client.embeddings.create( input=item["text"], model="text-embedding-3-small" ) item["embedding"] = response.data[0].embedding # 2. For a user query, find relevant context user_query = "When was the company founded?" query_response = client.embeddings.create( input=user_query, model="text-embedding-3-small" ) query_embedding = query_response.data[0].embedding # 3. Find most relevant facts (implement similarity search) # relevant_facts = find_similar_texts(query_embedding, knowledge_base, top_k=3) # 4. Use retrieved context with chat completion chat_response = client.chat.completions.create( model="gpt-4", messages=[ {"role": "system", "content": f"Use this context to answer: {relevant_facts}"}, {"role": "user", "content": user_query} ] ) ``` ### Clustering & Classification Group similar texts or classify content: ```python theme={null} from sklearn.cluster import KMeans # Create embeddings for texts texts = ["Text 1", "Text 2", "Text 3", ...] embeddings = [] for text in texts: response = client.embeddings.create(input=text, model="text-embedding-3-small") embeddings.append(response.data[0].embedding) # Cluster embeddings kmeans = KMeans(n_clusters=5) clusters = kmeans.fit_predict(embeddings) # Each text now has a cluster assignment for text, cluster_id in zip(texts, clusters): print(f"'{text}' belongs to cluster {cluster_id}") ``` ### Duplicate Detection Find similar or duplicate content: ```python theme={null} def find_duplicates(texts, threshold=0.95): embeddings = [] # Generate embeddings for text in texts: response = client.embeddings.create( input=text, model="text-embedding-3-small" ) embeddings.append(response.data[0].embedding) # Calculate pairwise similarities similarities = cosine_similarity(embeddings) # Find duplicates duplicates = [] for i in range(len(texts)): for j in range(i+1, len(texts)): if similarities[i][j] > threshold: duplicates.append((i, j, similarities[i][j])) return duplicates ``` ## Model Selection Guide ### By Use Case | Use Case | Recommended Model | Rationale | | - | - | - | | General English text | `text-embedding-3-small` | Best price/performance ratio | | Maximum accuracy | `text-embedding-3-large` | Highest quality embeddings | | Multilingual content | `BAAI/bge-m3` | Excellent cross-language performance | | Code embeddings | `qwen/qwen3-embedding-8b` | Strong code retrieval with a 32K-token context | | Budget-conscious | `BAAI/bge-large-en-v1.5` | Just \$0.01/1M tokens | | Chinese content | `BAAI/bge-m3` | Strong Chinese and multilingual retrieval | | Fast similarity search | Models with dimension reduction | Can reduce dimensions for speed | ### By Requirements **Need fastest search?** * Use models supporting dimension reduction * Reduce to 256-512 dimensions * Trade small accuracy loss for 2-4x speed improvement **Need highest accuracy?** * Use `text-embedding-3-large` * Keep full 3072 dimensions * Best for critical applications **Processing many languages?** * Use `BAAI/bge-m3` for general multilingual * Use `qwen/qwen3-embedding-8b` for higher-quality multilingual retrieval **Working with code?** * Use `qwen/qwen3-embedding-8b` * Strong code retrieval with a 32K-token context ## Best Practices ### Performance Optimization 1. **Batch Requests**: Send up to 2048 texts in a single request 2. **Use Dimension Reduction**: Reduce dimensions when exact precision isn't critical 3. **Cache Embeddings**: Store computed embeddings to avoid re-processing 4. **Choose Appropriate Models**: Don't use 3072-dimension models if 768 suffices ### Cost Optimization 1. **Monitor Usage**: Track the `usage` field in responses 2. **Start Small**: Begin with `text-embedding-3-small` before upgrading 3. **Implement Caching**: Avoid re-embedding identical content 4. **Batch Processing**: Reduce API call overhead ### Quality Optimization 1. **Preprocess Text**: Clean and normalize text before embedding 2. **Consider Context**: Include relevant context in the text to embed 3. **Test Different Models**: Compare performance for your specific use case 4. **Use Appropriate Similarity Metrics**: Cosine similarity for most cases ## Integration Examples ### JavaScript/TypeScript ```javascript theme={null} import OpenAI from 'openai'; // Initialize client const openai = new OpenAI({ apiKey: 'YOUR_NANOGPT_API_KEY', baseURL: 'https://api.nano-gpt.com/api/v1' }); // Create embedding const response = await openai.embeddings.create({ input: "Your text to embed", model: "text-embedding-3-small" }); const embedding = response.data[0].embedding; console.log(`Embedding has ${embedding.length} dimensions`); ``` ### cURL ```bash theme={null} curl https://api.nano-gpt.com/api/v1/embeddings \ -H "Authorization: Bearer YOUR_NANOGPT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "input": "Your text to embed", "model": "text-embedding-3-small" }' ``` ### Direct API Usage ```python theme={null} import requests import json headers = { "Authorization": "Bearer YOUR_NANOGPT_API_KEY", "Content-Type": "application/json" } data = { "input": "Your text to embed", "model": "text-embedding-3-small" } response = requests.post( "https://api.nano-gpt.com/api/v1/embeddings", headers=headers, json=data ) result = response.json() embedding = result["data"][0]["embedding"] ``` ## Rate Limits & Error Handling ### Rate Limits Rate limits vary by endpoint and account. See [Rate Limits](/api-reference/miscellaneous/rate-limits). ### Error Codes | Code | Description | Solution | | - | - | - | | 401 | Invalid or missing API key | Check your API key | | 400 | Invalid request parameters | Verify model name and input format | | 400 (`zero_data_retention`) | ZDR-only routing is on and the model has no Zero Data Retention route | Use a model with `zero_data_retention: true` | | 429 | Rate limit exceeded | Implement exponential backoff | | 500 | Server error | Retry with exponential backoff | ### Error Response Format ```json theme={null} { "error": { "message": "Invalid model specified", "type": "invalid_request_error", "param": "model", "code": null } } ``` For a general guide across NanoGPT APIs, see [Error Handling](/api-reference/miscellaneous/error-handling). ## Migration from OpenAI Switching from OpenAI to NanoGPT is seamless: ```python theme={null} # OpenAI client = OpenAI(api_key="sk-...") # NanoGPT (just change base_url and api_key) client = OpenAI( api_key="YOUR_NANOGPT_API_KEY", base_url="https://api.nano-gpt.com/api/v1" ) # All other code remains exactly the same! ``` ## Pricing Summary | Price Range | Models | Best For | | - | - | - | | \$0.005-0.02/1M | BAAI models, Qwen3 | Budget applications | | \$0.02/1M | text-embedding-3-small | Balanced performance | | \$0.10/1M | ada-002 | Legacy compatibility | | \$0.13/1M | text-embedding-3-large | Maximum performance | | \$0.15-0.20/1M | Gemini embeddings | Image input with Gemini Embedding 2 | ## Additional Resources * [Embeddings Endpoint Reference](/api-reference/endpoint/embeddings) * [Embedding Models List](/api-reference/endpoint/embedding-models) * [Text Generation Guide](/api-reference/text-generation) * [Quickstart Guide](/quickstart) # AI Detection Source: https://docs.nano-gpt.com/api-reference/endpoint/ai-detection POST https://api.nano-gpt.com/api/v1/ai-detection AI-text and plagiarism detection endpoint ## Overview Use `POST /api/v1/ai-detection` to run AI-text detection or plagiarism detection on a text input. > [!TIP] > > The same checks run in the browser without code, at the same prices: the [AI text detector](https://nano-gpt.com/ai-detection/text), [plagiarism checker](https://nano-gpt.com/ai-detection/plagiarism), [AI image detector](https://nano-gpt.com/ai-detection/image) and [AI video detector](https://nano-gpt.com/ai-detection/video). ## Endpoint ```text theme={null} POST https://api.nano-gpt.com/api/v1/ai-detection ``` ## Authentication An API key is required. * `Authorization: Bearer YOUR_API_KEY` * `x-api-key: YOUR_API_KEY` ## Request Body ```json theme={null} { "text": "Text to analyze...", "mode": "ai" } ``` ## Parameters | Field | Type | Required | Default | Description | | - | - | - | - | - | | `text` | string | Yes | - | Text to analyze. | | `mode` | string | No | `ai` | Detection mode. Allowed values: `ai`, `plagiarism`. | ## Modes | Mode | Description | | - | - | | `ai` | AI-text detection. | | `plagiarism` | Plagiarism detection. | ## Response ```json theme={null} { "object": "ai_detection.result", "mode": "ai", "model": "pangram-ai-detection", "content": "Human-readable summary", "result": { "score": 0.12 }, "word_count": 250, "usage": { "prompt_tokens": 300, "completion_tokens": 50, "total_tokens": 350 }, "pricing": { "amount": 0.01, "currency": "USD" } } ``` ## Example ```bash theme={null} curl -X POST https://api.nano-gpt.com/api/v1/ai-detection \ -H "Authorization: Bearer $NANOGPT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "text": "Text to analyze...", "mode": "ai" }' ``` ## Common Errors | Code | Description | | - | - | | `missing_api_key` | API key is required. | | `invalid_json` | Request body is not valid JSON. | | `invalid_mode` | `mode` is not `ai` or `plagiarism`. | | `missing_text` | `text` is required. | | `model_not_allowed` | Detection model is not available for the account or route. | | `paid_features_disabled` | Paid API features are disabled for the account. | | `insufficient_balance` | Account balance is too low for the request. | # AI Image Detection Source: https://docs.nano-gpt.com/api-reference/endpoint/ai-detection-image POST https://nano-gpt.com/api/v1/ai-detection/image Check whether an image was made or edited with AI ## Overview Use `POST /api/v1/ai-detection/image` to check whether an image is AI-generated. Send the image as base64 or as a direct link to the image file. Detection is run by Pangram. > [!TIP] > > To check an image without code, use the [AI image detector](https://nano-gpt.com/ai-detection/image) on nano-gpt.com. It uses the same detectors and prices. ## Endpoint ```text theme={null} POST https://nano-gpt.com/api/v1/ai-detection/image ``` ## Authentication An API key is required. Browser sessions are not accepted. * `Authorization: Bearer YOUR_API_KEY` * `x-api-key: YOUR_API_KEY` ## Request Body Send a link: ```json theme={null} { "image_url": "https://example.com/photo.jpg", "model": "pangram-image-1" } ``` Or send the image itself: ```json theme={null} { "image": "data:image/png;base64,iVBORw0KGgo...", "model": "pangram-image-flash-1" } ``` ## Parameters Send exactly one of `image` or `image_url`. | Field | Type | Required | Default | Description | | - | - | - | - | - | | `image` | string | One of `image` / `image_url` | - | Base64-encoded image, or a `data:image/png;base64,...` data URL. A data URL's type must match the file's bytes. | | `image_url` | string | One of `image` / `image_url` | - | Public `http` or `https` link to the image file. | | `model` | string | No | `pangram-image-1` | Detection model. Allowed values: `pangram-image-1`, `pangram-image-flash-1`. | ## Models and Pricing | Model | Price per image | | - | - | | `pangram-image-1` | \$0.3125 | | `pangram-image-flash-1` | \$0.0625 | Your balance and any API key spend limits must cover the price before the image is read. You are charged only when a result is returned; a detector failure is not charged. If you disconnect after the image reaches the detector, the check still finishes and is charged. For API keys with an allowed-model list, the list must include `pangram-image-detection` (for `pangram-image-1`) or `pangram-image-flash-detection` (for `pangram-image-flash-1`). ## Image Rules * Formats: PNG, JPEG or WebP. * Size: up to 32 MiB (33,554,432 bytes). * The JSON request body is limited to 4,400,000 bytes, so base64 images above about 3.3 MB must be sent with `image_url`. * `image_url` must be a direct link to the image file, not a web page that shows it. Links with a username or password are refused. The download times out after 30 seconds. * Link downloads count against the same per-account and per-IP request and byte quotas as other NanoGPT remote file fetches. * Up to 10 AI detection checks can run at once per account. This limit is shared with text detection. ## Response ```json theme={null} { "object": "ai_detection.image", "model": "pangram-image-1", "prediction": "Likely AI", "ai_likelihood": 0.8, "confidence": "High", "detection_source": "model", "heatmap": null, "metadata": {}, "thumbnail": null, "version": "detector version", "cost_usd": 0.3125, "pricing": { "amount": 0.3125, "currency": "USD" } } ``` | Field | Type | Description | | - | - | - | | `object` | string | Always `ai_detection.image`. | | `model` | string | Model used. | | `prediction` | string | One of `AI Detected`, `Likely AI`, `Unsure`, `Likely No AI`, `No AI`, `Partially AI`. | | `ai_likelihood` | number or null | Likelihood that the image is AI-generated, from 0 to 1. | | `confidence` | string or null | `Low`, `Medium` or `High`. | | `detection_source` | string | `model` when the detector judged the pixels, `c2pa` when the result comes from the file's C2PA content credentials. | | `heatmap` | object or null | `{ "grid": number[][], "patch_stride": number }`. `grid` holds an AI score from 0 to 1 for each image patch, row by row. | | `metadata` | object | File metadata found by the detector, such as Content Credentials (`c2pa`), camera and software. | | `thumbnail` | object or null | `{ "data_url": string, "width": number, "height": number }`. | | `version` | string or null | Detector version. | | `cost_usd` | number | Price of the check in USD. | | `pricing` | object | Amount charged and the balance it was charged to (`USD` or `XNO`). | The request returns when the check finishes. The server stops waiting for the detector about 280 seconds after the request starts and returns `504` with code `timeout`. ## Example ```bash theme={null} curl -sS -X POST "https://nano-gpt.com/api/v1/ai-detection/image" \ -H "Authorization: Bearer $NANOGPT_API_KEY" \ -H "Content-Type: application/json" \ -d '{"image_url":"https://example.com/photo.jpg","model":"pangram-image-1"}' ``` Send a local file as base64: ```bash theme={null} printf '{"image":"%s"}' "$(base64 < photo.png | tr -d '\n')" > request.json curl -sS -X POST "https://nano-gpt.com/api/v1/ai-detection/image" \ -H "Authorization: Bearer $NANOGPT_API_KEY" \ -H "Content-Type: application/json" \ --data-binary @request.json ``` ## Common Errors Errors use this shape: ```json theme={null} { "error": { "message": "Use a PNG, JPEG or WebP image.", "code": "unsupported_image_type" } } ``` | Status | Code | Description | | - | - | - | | 400 | `invalid_json` | Request body is not valid JSON. | | 400 | `invalid_request` | Neither or both of `image` and `image_url` were sent. | | 400 | `invalid_model` | `model` is not `pangram-image-1` or `pangram-image-flash-1`. | | 400 | `invalid_image` | `image` is not valid base64 or a valid base64 data URL. | | 400 | `invalid_image_url` | The link is not a public `http`/`https` URL, or no image could be loaded from it. | | 401 | `missing_api_key` | API key is required. | | 401 | `invalid_api_key` | API key is not valid. | | 402 | `insufficient_balance` | Balance is too low for the check. | | 403 | `paid_features_disabled` | Paid models are disabled for API use on this subscription. | | 403 | `model_not_allowed` | The API key's allowed-model list does not include this detection model. | | 403 | `zdr_provider_required` | The API key or request requires Zero Data Retention (ZDR), for example `"provider": { "zdr": true }`. AI detection is not available on ZDR requests. | | 413 | `request_body_too_large` | JSON body is over 4,400,000 bytes. | | 413 | `image_too_large` | Image is over 32 MiB. | | 413 | `file_too_large` | The detector refused the file as too large. | | 415 | `unsupported_image_type` | Image is not PNG, JPEG or WebP, or a data URL's type does not match the file. | | 422 | `invalid_image` | The detector could not read the image. | | 422 | `unsafe_content` | The file can't be checked. | | 429 | `link_rate_limited` | Too many link fetches. Try again later. | | 429 | `too_many_concurrent_requests` | 10 AI detection checks are already running for this account. Check `Retry-After`. | | 429 | API key limit code | An API key spend limit was reached, for example `daily_usd_limit_exceeded`. Check `Retry-After`. | | 502 | `upstream_error`, `upstream_task_failed`, `upstream_malformed_result`, `upstream_missing_task_id` | The detector failed. Not charged. | | 503 | `link_quota_unavailable` | Link checks are temporarily unavailable. | | 503 | `service_unavailable`, `service_busy` | The detector is unavailable or busy. Try again later. | | 504 | `timeout` | The detector did not finish in time. | # AI Video Detection Source: https://docs.nano-gpt.com/api-reference/endpoint/ai-detection-video POST https://nano-gpt.com/api/v1/ai-detection/video Check whether a video was made with AI, frame by frame ## Overview Use `POST /api/v1/ai-detection/video` to check whether a video is AI-generated. Send a direct link to an MP4, MOV or WebM file up to 2 minutes long. The result covers the whole video, time segments and individual frames. Detection is run by Pangram. > [!TIP] > > To upload a video file instead of sending a link, use the [AI video detector](https://nano-gpt.com/ai-detection/video) on nano-gpt.com. It uses the same detector and price. ## Endpoint ```text theme={null} POST https://nano-gpt.com/api/v1/ai-detection/video ``` ## Authentication An API key is required. Browser sessions are not accepted. * `Authorization: Bearer YOUR_API_KEY` * `x-api-key: YOUR_API_KEY` ## Request Body ```json theme={null} { "video_url": "https://example.com/clip.mp4" } ``` ## Parameters | Field | Type | Required | Default | Description | | - | - | - | - | - | | `video_url` | string | Yes | - | Public `http` or `https` link to the video file. | There is one video detection model; the request takes no `model` field. ## Pricing | Item | Amount | | - | - | | Price | \$0.0625 per second of video, rounded up to whole seconds | | Maximum charge | \$7.50 (a 2-minute video) | | Required before the download | \$7.50 of balance and API key spend limit | The server downloads the video only after your balance and any API key spend limits cover $7.50, the price of the longest video it accepts. The charge is then based on the duration the detector reports, or the duration the server measured when the detector reports none, and is never more than $7.50. For example, an 11.1-second video is billed as 12 seconds: \$0.75. You are charged only when a result is returned; a detector failure is not charged. If you disconnect after the video reaches the detector, the check still finishes and is charged. For API keys with an allowed-model list, the list must include `pangram-video-detection`. ## Video Rules * `video_url` must be a direct link to the video file, not a web page that plays it. Links with a username or password are refused. * The link must return a successful response with a `Content-Type` of `video/mp4`, `video/quicktime` or `video/webm`. A `text/*` response, such as an HTML page, is refused. * The file must start with an MP4/MOV or WebM container header. A file that is not a video is refused even when the server labels it as one. * Size: up to 500 MiB (524,288,000 bytes). * Length: up to 2 minutes (120 seconds after rounding up to whole seconds). The server reads the length from the file before charging. * The download must finish within 5 minutes. * Link downloads count against the same per-account and per-IP request and byte quotas as other NanoGPT remote file fetches. * Up to 2 video checks can run at once per account. The server keeps a private copy of the video only for the check. The copy is removed when the check ends and permanently deleted within about two hours. ## Response ```json theme={null} { "object": "ai_detection.video", "duration_ms": 11100, "cost_usd": 0.75, "stage": "STAGE_SUCCESS", "schema_version": "1.1", "headline": "AI Detected", "prediction": "AI Detected", "prediction_short": "ai", "version": "detector version", "source": { "content_type": "video/mp4", "size_bytes": 4194304, "duration_ms": 11100, "fps": 30, "width": 1280, "height": 720 }, "sampling": { "fps": 3 }, "frames": [ { "frame_id": 0, "timestamp_ms": 0, "result": { "prediction": "AI Detected", "ai_likelihood": 0.97, "confidence": "High", "detection_source": "model", "version": "detector version", "heatmap": null, "metadata": {}, "thumbnail": null } } ], "segments": [ { "id": 0, "range": { "start_ms": 0, "end_ms": 11100 }, "prediction_short": "ai", "prediction": "AI Detected", "frame_ids": [0] } ], "frames_processed": 34, "total_frames": 34, "fraction_ai": 1, "fraction_human": 0, "fraction_mixed": 0, "pricing": { "amount": 0.75, "currency": "USD" } } ``` The example is shortened to one frame. | Field | Type | Description | | - | - | - | | `object` | string | Always `ai_detection.video`. | | `duration_ms` | number | Billed duration in milliseconds. | | `cost_usd` | number | Price of the check in USD. | | `stage` | string | `STAGE_SUCCESS`. | | `schema_version` | string | Result schema version. | | `headline` | string | Short summary of the result. | | `prediction` | string | Overall verdict. | | `prediction_short` | string | `no_ai`, `mixed`, `ai` or `unsure`. | | `version` | string | Detector version. | | `source` | object | The checked file: `content_type`, `size_bytes`, `duration_ms`, `fps`, `width`, `height`. | | `sampling` | object | `fps`: frames sampled per second of video. | | `frames` | array | Sampled frames. Each has `frame_id`, `timestamp_ms` and a `result` with the same fields as an [image detection](/api-reference/endpoint/ai-detection-image) result: `prediction`, `ai_likelihood`, `confidence`, `detection_source`, `version`, `heatmap`, `metadata`, `thumbnail`. | | `segments` | array | Time ranges with one verdict each: `id`, `range` (`start_ms`, `end_ms`), `prediction`, `prediction_short` (`human`, `likely_human`, `unsure`, `likely_ai`, `ai` or `mixed`) and the `frame_ids` in the range. | | `frames_processed` | number | Number of sampled frames analyzed. | | `total_frames` | number | Number of frames sampled for analysis. | | `fraction_ai`, `fraction_human`, `fraction_mixed` | number | Share of the video judged AI, human or mixed, from 0 to 1. Other `fraction_*` fields may appear. | | `pricing` | object | Amount charged and the balance it was charged to (`USD` or `XNO`). | The request returns when the check finishes, which can take several minutes. Set your client timeout to at least 30 minutes. The server stops waiting for the detector about 29 minutes after the request starts and returns `504` with code `timeout`. ## Example ```bash theme={null} curl -sS -X POST "https://nano-gpt.com/api/v1/ai-detection/video" \ -H "Authorization: Bearer $NANOGPT_API_KEY" \ -H "Content-Type: application/json" \ --max-time 1800 \ -d '{"video_url":"https://example.com/clip.mp4"}' ``` ## Common Errors Errors use this shape: ```json theme={null} { "error": { "message": "Videos can be up to 2 minutes long.", "code": "video_too_long" } } ``` | Status | Code | Description | | - | - | - | | 400 | `invalid_json` | Request body is not valid JSON. | | 400 | `invalid_video_url` | `video_url` is missing, is not a public `http`/`https` URL, or the video could not be downloaded. | | 401 | `missing_api_key` | API key is required. | | 401 | `invalid_api_key` | API key is not valid. | | 402 | `insufficient_balance` | Balance does not cover the \$7.50 required before the download. | | 403 | `paid_features_disabled` | Paid models are disabled for API use on this subscription. | | 403 | `model_not_allowed` | The API key's allowed-model list does not include `pangram-video-detection`. | | 403 | `zdr_provider_required` | The API key or request requires Zero Data Retention (ZDR), for example `"provider": { "zdr": true }`. AI detection is not available on ZDR requests. | | 413 | `request_body_too_large` | JSON body is over 4,400,000 bytes. | | 413 | `video_too_large` | Video is over 500 MiB. | | 413 | `file_too_large` | The detector refused the file as too large. | | 415 | `not_a_video_file` | The link returns a web page or other non-video file. | | 415 | `unsupported_video_type` | The video is not MP4, MOV or WebM. | | 422 | `unreadable_duration` | The server could not read the video's length. Try an MP4 file. | | 422 | `video_too_long` | Video is longer than 2 minutes. | | 422 | `invalid_video` | The detector could not read the video. | | 422 | `unsafe_content` | The file can't be checked. | | 429 | `link_rate_limited` | Too many link fetches. Try again later. | | 429 | `too_many_concurrent_requests` | 2 video checks are already running for this account. Check `Retry-After`. | | 429 | API key limit code | An API key spend limit was reached, for example `daily_usd_limit_exceeded`. Check `Retry-After`. | | 502 | `upstream_error`, `upstream_task_failed`, `upstream_malformed_result`, `upstream_missing_task_id` | The detector failed. Not charged. | | 503 | `link_quota_unavailable` | Link checks are temporarily unavailable. | | 503 | `storage_unavailable`, `ai_detection_input_cleanup_unavailable` | Temporary video storage is unavailable. Retry. | | 503 | `service_unavailable`, `service_busy` | The detector is unavailable or busy. Try again later. | | 504 | `timeout` | The detector did not finish in time. | # Audio Models Source: https://docs.nano-gpt.com/api-reference/endpoint/audio-models GET https://api.nano-gpt.com/api/v1/audio-models List available text-to-speech and speech-to-text models ## Overview Use `GET /api/v1/audio-models` to discover the currently available audio models. The response includes both text-to-speech (TTS) and speech-to-text (STT) models. This endpoint is cacheable. Refresh it periodically and do not hardcode audio model capabilities in your client. ## Endpoint ```text theme={null} GET https://api.nano-gpt.com/api/v1/audio-models ``` ## Authentication Authentication is optional. * `Authorization: Bearer YOUR_API_KEY` * `x-api-key: YOUR_API_KEY` ## Query Parameters | Parameter | Type | Default | Description | | - | - | - | - | | `detailed` | boolean | `true` | Include names, descriptions, pricing, capabilities, and supported parameters. | | `type` | string | `all` | Filter by audio model type. Allowed values: `all`, `tts`, `stt`. | ## Response ```json theme={null} { "object": "list", "data": [ { "id": "tts-model-id", "object": "model", "name": "Display name", "description": "Model description", "architecture": { "modality": "audio", "input_modalities": ["text"], "output_modalities": ["audio"] }, "pricing": { "currency": "USD" }, "capabilities": { "text_to_speech": true, "speech_to_text": false }, "supported_parameters": {} } ], "meta": { "count": 1, "generated_at": "2026-05-07T12:00:00.000Z" } } ``` When `type` is not `all`, `meta` may include the active filter. ## Model Types | Type | Description | | - | - | | `tts` | Text-to-speech models for `POST /api/v1/audio/speech` and related TTS endpoints. | | `stt` | Speech-to-text models for transcription endpoints. | | `all` | Both TTS and STT models. | ## Example ```bash theme={null} curl "https://api.nano-gpt.com/api/v1/audio-models?type=stt&detailed=true" \ -H "x-api-key: $NANOGPT_API_KEY" ``` ## Notes * Supported parameters vary by model, including voices, formats, streaming support, file formats, language support, diarization, timestamps, and max input size. * Use this endpoint instead of hardcoding audio model capabilities. * The response is cacheable, but model availability can change. # v1/audio/transcriptions (STT) Source: https://docs.nano-gpt.com/api-reference/endpoint/audio-transcriptions POST https://api.nano-gpt.com/api/v1/audio/transcriptions OpenAI-compatible speech-to-text transcription endpoint ## Overview NanoGPT provides a drop-in OpenAI-compatible endpoint for speech-to-text (STT) transcription. ## Endpoint ```text theme={null} POST https://api.nano-gpt.com/api/v1/audio/transcriptions ``` ## Authentication Use either header: * `Authorization: Bearer YOUR_API_KEY` * `x-api-key: YOUR_API_KEY` ## Request Formats ### 1) Multipart upload (OpenAI-compatible) Send `multipart/form-data` with: * `file` (required): audio (or video for supported models) * `model` (required): STT model ID * `language` (optional): language code (default: auto-detect) ```bash theme={null} curl -X POST https://api.nano-gpt.com/api/v1/audio/transcriptions \ -H "Authorization: Bearer YOUR_API_KEY" \ -F file=@audio.mp3 \ -F model=Whisper-Large-V3 \ -F language=en ``` ### 2) JSON with URL ```json theme={null} { "model": "Whisper-Large-V3", "file_url": "https://example.com/audio.mp3", "language": "en" } ``` NanoGPT accepts `file_url` or `audio_url` for URL-based transcription. ## Supported Models (Examples) Model availability changes; use `GET /api/v1/models?detailed=true` for discovery. | Model | Notes | | - | - | | `Whisper-Large-V3` | High-accuracy transcription | | `Wizper` | Fast processing | | `Elevenlabs-STT` | Speaker diarization + audio event tagging | | `gpt-4o-mini-transcribe` | Improved accuracy vs Whisper (OpenAI-family) | | `openai-whisper-with-video` | Accepts video files (MP4, MOV, etc.) | ### Voice Cloning (via the same endpoint) Some special model IDs run voice-cloning workflows instead of returning plain transcription text: * `qwen-voice-clone` — returns a reusable speaker embedding URL * `minimax-voice-clone` — returns a reusable custom voice ID (and/or preview output) ## Response ```json theme={null} { "text": "The transcribed text goes here.", "language": "en", "duration": 45.2 } ``` ## Supported Formats * Audio: MP3, OGG, WAV, M4A, AAC * Video (model-dependent): MP4, MOV, AVI, MKV, WEBM ## Example (Python, OpenAI SDK) ```python theme={null} from openai import OpenAI client = OpenAI( base_url="https://api.nano-gpt.com/api/v1", api_key="YOUR_API_KEY" ) with open("audio.mp3", "rb") as audio_file: transcript = client.audio.transcriptions.create( model="Whisper-Large-V3", file=audio_file ) print(transcript.text) ``` ## See Also * NanoGPT transcription workflows: `api-reference/endpoint/transcribe.mdx` * Full STT guide and model list: `api-reference/speech-to-text.mdx` # Batch API Source: https://docs.nano-gpt.com/api-reference/endpoint/batches Run Chat Completions, Responses, and native Anthropic Message Batches asynchronously ## Overview The NanoGPT Batch API runs many independent requests asynchronously at a lower token price than the equivalent synchronous calls. It is a good fit for classification, summarization, evals, synthetic data, document processing, and image analysis where immediate results are not required. Choose a workflow: * **File-backed API:** upload JSONL, create a batch, poll its status, then download output and error files. This OpenAI-compatible workflow is best for large or reusable inputs. * **Inline API:** send the requests in the batch creation body and receive the results when polling the completed batch. This is simpler for smaller jobs. * **[Anthropic Message Batches](#anthropic-message-batches):** send native Claude requests with the official Anthropic SDK or HTTP API. Requests run directly through Anthropic at batch token rates, with native JSONL results. The file-backed and inline workflows support rows targeting `/v1/chat/completions`, `/v1/responses`, or `/v1/embeddings`. Native Message Batches use a separate `/v1/messages/batches` endpoint. > [!NOTE] > > All rows in one batch must use the same endpoint and the same model. Batch requests are non-streaming and the only supported completion window is `24h`. ## Authentication and base URLs All requests require an API key: ```http theme={null} Authorization: Bearer $NANOGPT_API_KEY ``` Use the dedicated API host for batch operations: | Workflow | Base URL | | - | - | | File-backed | `https://api.nano-gpt.com/api/v1` | | Inline | `https://api.nano-gpt.com/api/beta` | | Anthropic SDK | `https://api.nano-gpt.com/api` (the SDK appends `/v1/messages/batches`) | Use `api.nano-gpt.com` for uploads. The main website host can reject larger multipart requests before they reach the Batch API. ## Supported row endpoints Each row in a file-backed or inline batch must target one of these endpoints: * `/v1/chat/completions` * `/v1/responses` * `/v1/embeddings` Completions, image generation, audio, video, transcription, TTS, moderation, and other endpoints cannot be used as batch rows. For native Anthropic request bodies, use [Message Batches](#anthropic-message-batches); `/v1/messages` is not a supported row endpoint for `/api/v1/batches`. ## Model support ### Chat Completions batches `/v1/chat/completions` batches support OpenAI, Claude, and Gemini models, and open-source models such as `openai/gpt-oss-120b`, `moonshotai/kimi-k3`, `z-ai/glm-5.2`, and `deepseek/deepseek-v4-pro`. Always submit the canonical NanoGPT model slug; upstream routing is handled automatically. Open-source model rows run through NanoGPT's normal routing as individual requests, started at about one row per second, so they behave like synchronous requests: they cost the same or less, can choose a provider with the request's `provider` field, and accept `tools` and `response_format`. They do not accept NanoGPT add-ons such as web search, scraping, memory, characters, or BYOK, and every token limit they set must be greater than 0. Rows for OpenAI, Claude, and Gemini models run on the upstream batch API and do not accept `tools`, `functions`, `response_format`, or `structured_outputs`. The `:thinking` suffix is accepted where a thinking variant is configured. Claude thinking aliases are also accepted for compatible models; a numeric thinking budget must be lower than `max_tokens`. For the live list, call [`GET /api/v1/models?detailed=true`](/api-reference/endpoint/models) and select models whose `supported_batch_endpoints` include `/v1/chat/completions`. Model availability changes. Validate a small batch before submitting a large job; an unsupported model returns an `unsupported_model` error. ### Responses batches `/v1/responses` batches currently support direct OpenAI models only. The `openai/` prefix is accepted. `gpt-5.2-pro` and `gpt-5.4-pro`, including dated snapshots, are not available through the upstream Responses Batch API and are rejected. Responses rows support function and custom tools, structured text output, and remote or data-URL image inputs. Provider-hosted tools and stateful Responses features are not supported in batches. ### Embeddings batches `/v1/embeddings` batches support `text-embedding-3-small`, `text-embedding-3-large`, and `text-embedding-ada-002`. The `openai/` prefix is accepted. Other embedding models return an `unsupported_model` error that names the supported models. For the live list, call `GET /api/v1/embedding-models` and select models whose `supported_batch_endpoints` include `/v1/embeddings`. Embedding batches with content moderation accept at most 10,000 rows, though a row can hold several inputs. Embedding inputs are checked by the same content moderation as other OpenAI-model batches. One flagged line rejects the whole batch with a 400 that names the lines. Zero Data Retention keys and teams, and EU inference keys, cannot create batches. An API key's model and provider allowlists also apply: a key whose allowlist does not permit these models, or the provider that serves them, gets a 403. ## File-backed API ### Endpoints * `POST /files` * `GET /files` * `GET /files/{file_id}` * `GET /files/{file_id}/content` * `DELETE /files/{file_id}` * `POST /batches` * `GET /batches` * `GET /batches/{batch_id}` * `POST /batches/{batch_id}/cancel` ### JSONL rules Each non-empty line must be a JSON object with: * a unique, non-empty `custom_id` * `method: "POST"` * `url` set to `/v1/chat/completions`, `/v1/responses`, or `/v1/embeddings` * a `body` object containing the model and endpoint-specific input All rows must use the same endpoint and model. `stream: true` is rejected. Chat Completions rows require a non-empty `messages` array and a positive `max_tokens` or `max_completion_tokens`. They support text and compatible `image_url` content. Image URLs may use HTTP, HTTPS, or base64 data URLs for PNG, JPEG, GIF, and WebP images. For Gemini models, NanoGPT downloads each HTTP or HTTPS image link when the file is uploaded and stores the image in the batch file, so the model never fetches the link itself. A link must reach a public PNG, JPEG, GIF, or WebP image of at most 30 MB; a web page, another file type, or a private address is refused with `media_url_not_fetchable` and the line number. The image's own bytes decide its type, so an image served as a generic download works. Images larger than 3,072 pixels on a side are scaled down, and one still over 5 MB is re-encoded as JPEG. One file can link up to 1,000 different images, and all of them must download within about 75 seconds, so send larger sets as several files or as base64 data URLs. Stored images count toward the 200 MiB file limit. ### YouTube videos with Gemini Batches for `google/gemini-3.8-flash`, `google/gemini-3.7-flash`, `google/gemini-3.5-flash`, `google/gemini-3-flash-preview`, and `google/gemini-3.1-pro-preview` also accept public YouTube links as `video_url` parts in user messages: ```jsonl theme={null} {"custom_id":"video-1","method":"POST","url":"/v1/chat/completions","body":{"model":"google/gemini-3.8-flash","messages":[{"role":"user","content":[{"type":"text","text":"Summarize this video in one sentence."},{"type":"video_url","video_url":{"url":"https://www.youtube.com/watch?v=jNQXAC9IVRw"}}]}],"max_tokens":256}} ``` Links must use HTTPS and point at a public video: watch, `youtu.be`, Shorts, live, and embed links work. Each request can link up to two videos. Other video sources, `start_offset` and `end_offset`, and YouTube links sent as `image_url` are rejected. Gemini's batch upstreams can't read YouTube links, so when any row in a batch has one, every row in that batch runs through NanoGPT's normal routing, like open-source model rows. These rows cost the same as synchronous requests, without the 50% batch discount. A video's length isn't known until the model reads it, so each video row reserves the model's full input limit of 1,048,576 tokens at creation. The unused part of the reservation is released when the batch settles. Responses rows require a non-empty `input` and an integer `max_output_tokens` of at least `16`. Embeddings rows require `model` and `input`, and take no output cap. `input` is a string or an array of up to 2,048 strings; token arrays and multimodal input are rejected. Rows may also set `dimensions` (`text-embedding-3-small` and `text-embedding-3-large` only), `encoding_format` (`float` or `base64`), and `user`. NanoGPT does not forward `user`. Any other field is rejected. Each input can be at most 8,191 tokens, and each row at most 300,000 tokens. One batch can hold at most 50,000 inputs across all of its rows. Embedding results are much larger than their input, and result files can be at most 200 MiB. NanoGPT estimates the size at upload and rejects a batch that would not fit with an `embedding_result_too_large` error. At full size, that is about 5,600 inputs per batch with `text-embedding-3-small` or `text-embedding-ada-002` and about 2,800 with `text-embedding-3-large`. To fit more, use `encoding_format: "base64"`, which makes results about 4.5 times smaller, or request fewer `dimensions`, or split the job into several batches. ### Chat Completions example ```jsonl theme={null} {"custom_id":"request-1","method":"POST","url":"/v1/chat/completions","body":{"model":"gpt-4.1-mini","messages":[{"role":"user","content":"Summarize this in one sentence: Batch APIs are useful for offline jobs."}],"max_tokens":64}} {"custom_id":"request-2","method":"POST","url":"/v1/chat/completions","body":{"model":"gpt-4.1-mini","messages":[{"role":"user","content":"Classify this review as positive or negative: I loved the product."}],"max_tokens":16}} ``` ### Responses example ```jsonl theme={null} {"custom_id":"response-1","method":"POST","url":"/v1/responses","body":{"model":"gpt-4.1-mini","input":"Extract three keywords from: Batch APIs process independent prompts asynchronously.","max_output_tokens":64}} {"custom_id":"response-2","method":"POST","url":"/v1/responses","body":{"model":"gpt-4.1-mini","input":"Reply with a JSON object containing a one-sentence summary.","text":{"format":{"type":"json_schema","name":"summary","strict":true,"schema":{"type":"object","properties":{"summary":{"type":"string"}},"required":["summary"],"additionalProperties":false}}},"max_output_tokens":128}} ``` ### Embeddings example ```jsonl theme={null} {"custom_id":"doc-1","method":"POST","url":"/v1/embeddings","body":{"model":"text-embedding-3-small","input":"Batch APIs process independent requests asynchronously."}} {"custom_id":"doc-2","method":"POST","url":"/v1/embeddings","body":{"model":"text-embedding-3-small","input":["First passage.","Second passage."],"dimensions":512,"encoding_format":"base64"}} ``` Each successful output row holds a standard embeddings response in `response.body`. Match rows by `custom_id`, and use each item's `index` to match vectors to the strings in that row's `input`. ```json theme={null} {"id":"batch_req_abc","custom_id":"doc-1","response":{"status_code":200,"request_id":"req_abc","body":{"object":"list","data":[{"object":"embedding","index":0,"embedding":[0.0023,-0.0093]}],"model":"text-embedding-3-small","usage":{"prompt_tokens":8,"total_tokens":8}}},"error":null} ``` ### Upload the file ```bash theme={null} curl https://api.nano-gpt.com/api/v1/files \ -H "Authorization: Bearer $NANOGPT_API_KEY" \ -F purpose=batch \ -F file=@batch.jsonl ``` ### Create the batch Set `endpoint` to the same endpoint used by every JSONL row: ```bash theme={null} curl https://api.nano-gpt.com/api/v1/batches \ -H "Authorization: Bearer $NANOGPT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "input_file_id": "file_abc123", "endpoint": "/v1/responses", "completion_window": "24h" }' ``` ### Poll, cancel, and download ```bash theme={null} # Retrieve one batch curl https://api.nano-gpt.com/api/v1/batches/batch_abc123 \ -H "Authorization: Bearer $NANOGPT_API_KEY" # Best-effort cancellation curl -X POST https://api.nano-gpt.com/api/v1/batches/batch_abc123/cancel \ -H "Authorization: Bearer $NANOGPT_API_KEY" # Download JSONL output curl https://api.nano-gpt.com/api/v1/files/file_output123/content \ -H "Authorization: Bearer $NANOGPT_API_KEY" ``` Batch statuses are `validating`, `in_progress`, `finalizing`, `completed`, `failed`, `expired`, `cancelling`, and `cancelled`. A completed batch normally has an `output_file_id`; row failures may also produce an `error_file_id`. ### List and delete files Uploaded input files count toward a staged storage allowance of 1 GiB and 100 files per API key until a batch starts from them. An upload that would exceed it returns `429` with `batch_file_storage_quota_exceeded` and the space in use. Delete input files you no longer need, and output or error files you have downloaded: ```bash theme={null} # List files, newest first (purpose, limit 1-10000, order asc|desc, after=) curl "https://api.nano-gpt.com/api/v1/files?purpose=batch&limit=100" \ -H "Authorization: Bearer $NANOGPT_API_KEY" # Delete a file curl -X DELETE https://api.nano-gpt.com/api/v1/files/file_abc123 \ -H "Authorization: Bearer $NANOGPT_API_KEY" ``` The list follows the OpenAI format (`object`, `data`, `first_id`, `last_id`, `has_more`), so `client.files.list()` and `client.files.delete()` in the OpenAI SDKs work with these routes. Deletion returns `{"id": "file_abc123", "object": "file", "deleted": true}` and removes the file's stored content; batches keep the file ID, but the file can no longer be retrieved, downloaded, or used to create a batch. A file used by a batch that is still running or settling returns `409` with `file_in_use`; retry after the batch finishes, or cancel it first. Files of inline batches and native Message Batches stay with their batch and also return `409`. ## Inline API Inline batches accept up to 10,000 requests, 20 MiB of normalized input, and 250,000 aggregate requested output tokens. Embeddings batches have no output tokens; their estimated results must instead fit in 50 MiB, or about 1,400 inputs at full size with `text-embedding-3-small`, and more with `encoding_format: "base64"` or fewer `dimensions`. Use the file-backed API for larger inputs. ### Endpoints * `POST /batches` * `GET /batches` * `GET /batches/{batch_id}` * `POST /batches/{batch_id}/cancel` All inline routes use the `https://api.nano-gpt.com/api/beta` base URL. ### Create an inline batch ```bash theme={null} curl https://api.nano-gpt.com/api/beta/batches \ -H "Authorization: Bearer $NANOGPT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "endpoint": "/v1/responses", "model": "gpt-4.1-mini", "requests": [ { "custom_id": "response-1", "body": { "input": "Summarize this text in one sentence." } } ] }' ``` Creation returns `202 Accepted`. Poll `GET /api/beta/batches/{batch_id}` and read `results` after completion. Cancel an active job with `POST /api/beta/batches/{batch_id}/cancel`. The batch-level model is inherited by every request body. If an inline row omits its endpoint-specific output cap, NanoGPT applies a 4096-token default. File-backed rows must always include the output cap explicitly. Embeddings rows have no output cap, so no default is applied. ```bash theme={null} curl https://api.nano-gpt.com/api/beta/batches \ -H "Authorization: Bearer $NANOGPT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "endpoint": "/v1/embeddings", "model": "text-embedding-3-small", "requests": [ { "custom_id": "doc-1", "body": { "input": "First passage." } }, { "custom_id": "doc-2", "body": { "input": ["Second passage.", "Third passage."] } } ] }' ``` ## List batches Use the authenticated list route for the workflow you want to inspect. Each route returns only batches visible to the supplied API key, ordered newest first. Native Message Batches have their own [list route and cursor names](#list-native-message-batches). | Workflow | Endpoint | | - | - | | Inline | `GET https://api.nano-gpt.com/api/beta/batches` | | All batches (OpenAI-compatible) | `GET https://api.nano-gpt.com/api/v1/batches` | Both routes support the same filters and bidirectional cursor pagination: | Parameter | Description | | - | - | | `limit` | Page size from 1 to 100. Defaults to 20. | | `after` | Return the next page of batches older than this batch ID. Pass the current page's `last_id`. | | `before` | Return the adjacent page of batches newer than this batch ID, still ordered newest first. Pass the current page's `first_id`. | | `status` | Filter by one or more statuses. Repeat the parameter or provide comma-separated values. | | `created_after` | Return batches created strictly after this boundary. | | `created_before` | Return batches created strictly before this boundary. | `after` and `before` cannot be combined. Cursors are batch IDs, not arbitrary tokens. Creation boundaries accept Unix timestamps in seconds or timezone-qualified ISO 8601/RFC 3339 timestamps with no more than millisecond precision. Supported status values are `validating`, `in_progress`, `finalizing`, `completed`, `failed`, `expired`, `cancelling`, and `cancelled`. ### Filter inline batches ```bash theme={null} curl "https://api.nano-gpt.com/api/beta/batches?limit=20&status=in_progress,completed" \ -H "Authorization: Bearer $NANOGPT_API_KEY" ``` You can also filter by a strict creation-time range: ```bash theme={null} curl "https://api.nano-gpt.com/api/beta/batches?created_after=2026-09-01T00:00:00Z&created_before=2026-09-02T00:00:00Z" \ -H "Authorization: Bearer $NANOGPT_API_KEY" ``` ### Filter all batches ```bash theme={null} curl "https://api.nano-gpt.com/api/v1/batches?limit=50&status=failed&created_after=1788192000" \ -H "Authorization: Bearer $NANOGPT_API_KEY" ``` ### Response and pagination Both endpoints return the standard list envelope: ```json theme={null} { "object": "list", "data": [], "first_id": null, "last_id": null, "has_more": false } ``` * `data` is always ordered newest first. * `first_id` and `last_id` are `null` for an empty page. * To fetch older batches, send `after=` with the same filters. * To return to the adjacent newer page, send `before=` with the same filters. * `has_more` indicates that more records exist in the direction being paged. For example: ```bash theme={null} # Fetch the next, older page curl "https://api.nano-gpt.com/api/v1/batches?limit=20&status=completed&after=batch_older_cursor" \ -H "Authorization: Bearer $NANOGPT_API_KEY" # Return to the adjacent newer page curl "https://api.nano-gpt.com/api/v1/batches?limit=20&status=completed&before=batch_newer_cursor" \ -H "Authorization: Bearer $NANOGPT_API_KEY" ``` > [!WARNING] > > Inline list responses contain metadata only. `results` is always `null`, including for completed batches. Retrieve `GET /api/beta/batches/{batch_id}` to obtain a completed inline batch's results. Inline list items include `id`, `object`, `endpoint`, `model`, `completion_window`, `status`, `created_at`, `finalized_at`, `request_counts`, `usage`, `error`, and a `results` field that is always `null`. The OpenAI-compatible list includes both inline and file-backed jobs. Its items retain the standard batch shape, including `input_file_id`, `output_file_id`, `error_file_id`, lifecycle timestamps, `request_counts`, `metadata`, `usage`, and `errors` where applicable. ### Listing errors Both list routes return: * `401` for missing or invalid authentication. * `400` when `after` and `before` are both present. * `400` for an unknown or inaccessible cursor. The inline-only route also rejects a cursor that identifies a non-inline batch. A cursor does not need to match the active filters; it only supplies the page boundary. * `400` for an unsupported `status` value. * `400` for an invalid creation timestamp or a reversed creation-time range. ## Anthropic Message Batches Use native Anthropic request shapes for asynchronous Claude jobs, including custom tools, thinking, prompt caching, images, and documents where the selected model supports them. Submit up to 100,000 requests for one supported Claude model per batch. Requests go directly to Anthropic and use batch token pricing, paid from your NanoGPT balance. The official Anthropic SDK works with a NanoGPT API key and `baseURL: 'https://api.nano-gpt.com/api'` (Python: `base_url`). It appends `/v1/messages/batches`. The shorter `/v1/messages/batches` alias also works with `https://api.nano-gpt.com` as the SDK base URL. ### Native endpoints | Method | URL path | Purpose | | - | - | - | | POST | `/api/v1/messages/batches` | Create a batch | | GET | `/api/v1/messages/batches` | List native Message Batches | | GET | `/api/v1/messages/batches/{id}` | Retrieve status and request counts | | POST | `/api/v1/messages/batches/{id}/cancel` | Request cancellation | | GET | `/api/v1/messages/batches/{id}/results` | Download native result JSONL | | DELETE | `/api/v1/messages/batches/{id}` | Delete an ended batch from NanoGPT's native API | All routes also accept the `/v1/messages/batches` prefix. Authenticate with `x-api-key` or `Authorization: Bearer` using your NanoGPT API key. ### Create a native batch Send a `requests` array containing `custom_id` and native Messages `params`. No file upload is required. ```bash theme={null} curl https://api.nano-gpt.com/api/v1/messages/batches \ -H "x-api-key: $NANOGPT_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: example-anthropic-batch-001" \ -d '{ "requests": [{ "custom_id": "summary-1", "params": { "model": "anthropic/claude-sonnet-5.5", "max_tokens": 1024, "messages": [{ "role": "user", "content": "Explain when batch processing is useful." }] } }] }' ``` Or use `@anthropic-ai/sdk`: ```ts theme={null} import Anthropic from '@anthropic-ai/sdk'; const client = new Anthropic({ apiKey: process.env.NANOGPT_API_KEY, baseURL: 'https://api.nano-gpt.com/api', }); const batch = await client.messages.batches.create({ requests: [{ custom_id: 'summary-1', params: { model: 'anthropic/claude-sonnet-5.5', max_tokens: 1024, messages: [{ role: 'user', content: 'Explain when batch processing is useful.' }], }, }], }, { headers: { 'Idempotency-Key': 'example-anthropic-batch-001' } }); // Retrieve periodically until processing_status is "ended". const current = await client.messages.batches.retrieve(batch.id); if (current.processing_status === 'ended' && current.results_url) { for await (const row of await client.messages.batches.results(batch.id)) { console.log(row.custom_id, row.result); } } ``` Choose a new `Idempotency-Key` for each distinct batch. Reuse the same key and body when retrying a submission; a different payload with the same key returns 409. A stored creation failure can also be replayed, so use a new key for a new submission after correcting that failure. The header is optional, but recommended for retries. ### Native request limits and compatibility * Send 1–100,000 requests with unique, non-empty `custom_id` values. * Use the same supported Claude model for every request. Thinking controls may vary by request. Support for a model on synchronous `/v1/messages` does not imply native batch support. * Haiku 5.5 accepts `anthropic/claude-haiku-5.5`, `claude-haiku-5-5`, and `anthropic/claude-haiku-latest`. Use `thinking: { "type": "adaptive" }` with `output_config: { "effort": "medium" }` to set its default thinking behavior explicitly; fixed `budget_tokens` controls are unsupported by Haiku 5.5. * Haiku 5.5 also accepts `thinking: { "type": "disabled" }` at `low`, `medium`, or `high` effort. Disabled thinking with `xhigh` or `max` is rejected. * Each `params` requires `model`, `messages`, and a positive integer `max_tokens` within the model's output limit. NanoGPT's maximum accepted cap is 1,000,000; model limits can be lower. The first message must have the `user` role; use the top-level `system` field for a system prompt. * The request body and stored normalized input must each fit within 200 MiB. Normalization can make the stored input larger than the original body. * The completion window is 24 hours. Streaming generation is unsupported; result downloads use JSONL. * Native custom tools and tool-result history, thinking, `output_config`, and prompt-cache controls are supported where the selected model supports them. Use native `thinking` controls, not OpenAI `reasoning` or `reasoning_effort` fields. * Images accept URL or base64 sources; documents accept URL, base64, or plaintext sources. Provider-managed file references, containers, MCP servers, hosted tools, and video blocks are rejected. * URL or base64 documents reserve enough balance for a full context window because their token count is unknown before processing. Final billing still uses actual token usage. * Caller `anthropic-beta` flags are forwarded alongside any flags required by the request. A beta header does not enable fields rejected by NanoGPT's batch validation. * Keys or teams requiring Zero Data Retention cannot create batches because batch processing retains input. Native Message Batches use the official Anthropic SDK. NanoGPT's general-purpose SDKs do not expose these batch methods. ### Native status, results, cancellation, and deletion Creation returns a `message_batch` object. Poll retrieval until `processing_status` is `ended`; the other states are `in_progress` and `canceling`. An ended batch can contain unsuccessful requests, so inspect `request_counts` and each result: * `request_counts` contains `processing`, `succeeded`, `errored`, `canceled`, and `expired`. * `results_url` is available when results can be downloaded. Results are native JSONL rows with `custom_id` and `result`; match by `custom_id` and inspect `result.type`, rather than assuming input order or success. * Results requested before they are available return 409. Download available results before provider archival; an ended status alone does not guarantee results remain available. * Cancellation is best-effort. Requests that complete can still incur usage charges. * Delete only after processing ends. Deletion hides the batch from NanoGPT's native API; it does not reverse billing or promise deletion of Anthropic's retained data. ### List native Message Batches `GET /api/v1/messages/batches` returns native batches visible to the supplied API key, newest first, with `data`, `has_more`, `first_id`, and `last_id`. Use `limit` from 1 to 100 (default 20), `after_id=` for older batches, or `before_id=` for newer batches. Do not combine both cursor parameters. Use the native list for native Message Batches; the `/api/v1/batches` list uses the OpenAI-compatible representation. ## Responses Batch restrictions Responses Batch is stateless and executes directly through the upstream batch service. NanoGPT forces `store: false` and rejects: * `previous_response_id`, `conversation`, and `background: true` * reusable `prompt` references * `input_file`, `item_reference`, video inputs, and `input_image.file_id` * provider-hosted tools; function and custom tools remain supported * NanoGPT-only features such as Advisor, memory, scraping, retention overrides, provider or BYOK controls, caching controls, and billing overrides Remote HTTP(S) image URLs and image data URLs are accepted. Structured output through the Responses `text.format` field is supported. ## Billing Batch jobs use NanoGPT account balance and do not use subscription included tokens. At creation, NanoGPT checks the balance against a conservative maximum-liability estimate based on the input and output caps. Completed usage is charged once after the batch reaches a terminal state. If there is no billable usage, no usage charge is created. * **OpenAI, Claude, and Gemini models, and some fine-tuned models:** token usage is priced 50% below the equivalent synchronous request. Non-token charges, where supported, keep their normal rate. A Gemini batch with a [YouTube video](#youtube-videos-with-gemini) is the exception: its rows are charged like open-source model rows. * **Other open-source models:** each row is charged exactly what the same synchronous request costs, including the automatic routing price, your subscriber discount, and the price of any provider you select. Rows are priced in USD, and a batch never costs more than the amount reserved when it was created. * **Open-source models with a batch price:** some models, such as `moonshotai/kimi-k3`, have a lower batch price for rows that use automatic routing. An alias such as `moonshotai/kimi-latest` uses the batch price of the model it points to. A row that sets `provider` pays that provider's normal price instead. A row never costs more than the same synchronous request. * **Embedding models:** input tokens are priced 50% below the synchronous embedding price: $0.01, $0.065, and $0.05 per million tokens for `text-embedding-3-small`, `text-embedding-3-large`, and `text-embedding-ada-002`. There are no output tokens. At creation, NanoGPT holds the estimated input cost plus 20%, with a $0.0001 minimum, then charges the tokens reported for successful rows. Failed rows are not charged. Each model page shows its Batch API price. Use the live pricing page or pricing API as the source of truth. ## Common errors * **Unsupported endpoint:** file-backed and inline rows must use `/v1/chat/completions`, `/v1/responses`, or `/v1/embeddings`, consistently across all rows. Native Claude requests use `/v1/messages/batches`. * **Missing output cap:** add `max_tokens` or `max_completion_tokens` for Chat Completions, or `max_output_tokens >= 16` for Responses. * **Mixed model:** every row must use the same model. * **Streaming unsupported:** remove `stream: true`. * **Unsupported Responses model:** choose a direct OpenAI model supported by the upstream Batch API. * **Unsupported Responses field:** remove stateful features, provider-hosted tools, file references, or NanoGPT-only extensions. * **Unsupported embeddings input:** `input` must be a string or an array of strings. Token arrays and multimodal input return `unsupported_input_format`. * **Embedding results too large:** `embedding_result_too_large` (file-backed) or `inline_result_too_large` (inline). Use `encoding_format: "base64"`, fewer `dimensions`, or smaller batches. # List All Batches Source: https://docs.nano-gpt.com/api-reference/endpoint/batches-list GET /api/v1/batches List all authenticated batches with filters and bidirectional cursor pagination This OpenAI-compatible list includes both inline and file-backed jobs. Items retain the standard batch shape, including file IDs, lifecycle timestamps, request counts, metadata, usage, and errors where applicable. See the [Batch API guide](/api-reference/endpoint/batches#list-batches) for pagination examples, filter rules, and error behavior. # Character Models Source: https://docs.nano-gpt.com/api-reference/endpoint/character-models GET /v1/character-models ## Overview `/api/v1/character-models` returns approved public characters that are enabled for API use in a model-list-compatible shape. Use this endpoint when you want to sync available public characters into tools that already understand model list responses. ## Endpoint ``` GET https://api.nano-gpt.com/api/v1/character-models ``` Query parameters: | Field | Type | Description | | - | - | - | | `detailed` | boolean | Include slug and extended character metadata | | `cursor` | string | Pagination cursor | | `limit` | number | Page size | ## Example ```bash theme={null} curl "https://api.nano-gpt.com/api/v1/character-models?detailed=true" ``` Response: ```json theme={null} { "object": "list", "data": [ { "id": "11111111-1111-1111-1111-111111111111", "object": "model", "created": 1760000000, "owned_by": "nanogpt", "character": { "character_id": "11111111-1111-1111-1111-111111111111", "slug": "helpful-guide", "base_model_id": "deepseek-ai/DeepSeek-V3-0324", "content_rating": "sfw", "tags": ["writing"], "rating_avg": 4.8, "rating_count": 12 } } ], "next_cursor": null } ``` Pass the returned `character.character_id` as `character_id` to the Responses API. # Characters Source: https://docs.nano-gpt.com/api-reference/endpoint/characters GET /v1/characters ## Overview Characters are reusable AI personas with a base model, system prompt, optional first message, tags, content rating, and visibility controls. The website uses these same endpoints for importing, publishing, browsing, rating, and adapting character cards. ## Authentication Use either header for private writes: * `Authorization: Bearer YOUR_API_KEY` * `x-api-key: YOUR_API_KEY` Public catalog reads do not require authentication. Private reads and writes require the owning session or API key. ## List Public Characters ``` GET https://api.nano-gpt.com/api/v1/characters ``` Query parameters: | Field | Type | Description | | - | - | - | | `q` | string | Search name, summary, and description | | `tags` | string or repeated string | Filter by one or more tag slugs | | `content_rating_max` | string | `sfw`, `suggestive`, `nsfw`, or `explicit` | | `sort` | string | `new`, `top_rated`, or `trending_simple` | | `cursor` | string | Pagination cursor from the previous response | | `limit` | number | Page size | Only approved public characters are returned. ## Create Character ``` POST https://api.nano-gpt.com/api/v1/characters ``` ```json theme={null} { "name": "Helpful Guide", "summary": "A concise assistant for technical writing", "description": "Helps plan, edit, and tighten technical docs.", "base_model_id": "deepseek-ai/DeepSeek-V3-0324", "system_prompt": "You are a concise technical writing assistant.", "first_message": "What are we editing today?", "visibility": "private", "allow_api": false, "creator_content_rating": "sfw", "tags": ["writing", "productivity"] } ``` Visibility values: | Value | Behavior | | - | - | | `private` | Only the owner can see and use it | | `unlisted` | Usable by direct ID or slug when permitted, not listed publicly | | `public` | Submitted to moderation before public discovery | Public submissions are created with `moderation_status: pending` and become discoverable only after approval. ## Manage Your Characters ``` GET /api/v1/characters/mine GET /api/v1/characters/{idOrSlug} PATCH /api/v1/characters/{idOrSlug} DELETE /api/v1/characters/{idOrSlug} ``` `DELETE` archives the character instead of hard-deleting it. `PATCH` accepts the same core fields as create. Editing an approved public character sends it back to pending moderation. ## Reviews And Reports ``` PUT /api/v1/characters/{idOrSlug}/review POST /api/v1/characters/{idOrSlug}/report ``` Review body: ```json theme={null} { "rating": 5, "review_text": "Optional review text with at least 10 characters." } ``` Reviews require an authenticated account with either an active subscription or more than \$1 in account balance. USD balance and Nano balance converted to USD both count toward this threshold. Report body: ```json theme={null} { "reason": "Policy concern", "details": "Optional extra context." } ``` ## Runtime Usage The Responses API accepts `character_id`: ```json theme={null} { "character_id": "character-uuid-or-slug", "input": "Introduce yourself" } ``` When `character_id` is supplied, NanoGPT applies the character's base model, instructions, and sampler defaults unless explicitly overridden by the request. For non-owner API usage, the character must be public, approved, and have API access enabled. # Chat Completion Source: https://docs.nano-gpt.com/api-reference/endpoint/chat-completion POST /v1/chat/completions Creates a chat completion for the provided messages. The NanoGPT Advisor extension is available for non-streaming, platform-billed pay-as-you-go API-key requests that do not use client tools, structured output, inline moderation, BYOK, accountless payment, memory, or server-side content enhancements. > [!NOTE] > > These examples use the direct API host, `https://api.nano-gpt.com`. It has no IPv6 address, so clients with only IPv6 should use `https://nano-gpt.com` with the same paths. See [API Hosts](/api-reference/miscellaneous/api-hosts). > [!NOTE] > > **API host:** Use `https://api.nano-gpt.com/api/v1` as the base URL for OpenAI-compatible clients. The direct API host allows larger attachments and longer-running requests than the website host. See [API Hosts](/api-reference/miscellaneous/api-hosts). > [!NOTE] > > Decision models (Jev, Liquid D1, PPLX Decider v1.2, Clef and Clef Flash) use `response_format: {"type":"questions","questions":{...}}`, accept only non-streaming user text, and return the answer object as JSON text in `choices[0].message.content`. `usage.estimated_cost` is returned by default; send `include_usage: true` for the exact `usage.cost`. See [Decisions](/api-reference/endpoint/decisions) for complete examples and limitations. > [!NOTE] > > The subscription base URL, `https://api.nano-gpt.com/api/subscription/v1/chat/completions` (swap `/api/v1` for `/api/subscription/v1`), is billed the same way as `/api/v1`: subscription-included models use your subscription, and requests it does not cover can be billed to your balance. To keep an API key limited to your subscription, save the key as **Subscription only** in its [billing mode](/api-reference/miscellaneous/billing-override#api-key-billing-settings); requests the subscription does not cover are then rejected instead of billed. > [!NOTE] > > Provider selection is available for supported open-source models. `X-Provider` or body `provider` explicitly selects or constrains providers for the request and is always billed pay-as-you-go at the selected provider's price, including provider-selection markup. The body `provider` field accepts either the existing string form or a structured routing object with `order`, `only`, `ignore`, `sort`, `quantizations`, `min_quantization`, `max_price`, `allow_fallbacks`, and `require_parameters`. Provider-selection-capable models also support routing preference suffixes such as `:fast` and `:cheap`. For subscription users, explicit provider selection bypasses subscription coverage for that request; `X-Billing-Mode: paygo` is only needed when forcing pay-as-you-go without an explicit provider or when saved provider preferences should apply to subscription-included traffic. See [Provider Selection](/api-reference/miscellaneous/provider-selection), [Model Suffixes](/api-reference/miscellaneous/model-suffixes), and [Pay-As-You-Go Billing Override](/api-reference/miscellaneous/billing-override). > [!NOTE] > > **Accountless x402 payments**: Non-streaming `POST /api/v1/chat/completions` requests can be quoted without an account or API key on supported deployments when the initial quote request includes `x-x402: true`. Streaming chat has implementation coverage but is not part of the stable public accountless contract. This endpoint supports accountless x402 payments where listed by `GET /api/v1/x402/endpoints`, including Lightning L402 when advertised. See [Accountless x402 API Payments](/api-reference/miscellaneous/x402) for the full flow. > [!NOTE] > > **Advisor extension:** Non-streaming pay-as-you-go API-key requests can include an `advisor` object so the executor model can consult one different model before returning its final answer. Use `mode: "auto"` to let the executor decide or `mode: "required"` to require a consultation attempt. Each completed model phase is billed separately. Advisor is a NanoGPT extension, not part of the standard OpenAI request schema. See [Advisor](/api-reference/miscellaneous/advisor). > [!NOTE] > > **Billing after a disconnect:** Save the server-generated `X-Request-ID` response header before consuming a stream. With the same API key, [Request Billing](/api-reference/endpoint/request-billing) can return the recorded primary charge and token usage for 24 hours from its accounting timestamp. Refunds and separately billed extras are excluded. Billing may be delayed; a missing record does not mean zero cost. ## Page map Use the jump list below to navigate the long-form reference quickly. > [accordion] Basics > > * [Advisor extension](#advisor-extension) > * [Tool calling](#tool-calling) > * [Overview](#overview) > * [Provider Routing Suffixes](#provider-routing-suffixes) > * [Provider Routing Object](#provider-routing-object) > * [Model Fallbacks](#model-fallbacks) > [accordion] Sampling & decoding > > * [Sampling & Decoding Controls](#sampling-decoding-controls) > * [Temperature & Nucleus](#temperature-nucleus) > * [Length & Stopping](#length-stopping) > * [Penalties & Repetition Guards](#penalties-repetition-guards) > * [Logit Shaping & Reproducibility](#logit-shaping-reproducibility) > * [Sampling example request](#example-request-1) > [accordion] Structured outputs > > * [Structured Outputs (response_format)](#structured-outputs-response-format) > * [Supported Formats](#supported-formats) > * [JSON Object Mode](#json-object-mode) > * [JSON Schema Mode](#json-schema-mode-structured-outputs) > * [Schema Requirements](#schema-requirements) > * [Example Request](#example-request-2) > * [Example Response](#example-response) > * [Vercel AI SDK](#usage-with-vercel-ai-sdk) > [accordion] Web search > > * [Web Search](#web-search) > * [Native search](#native-search) > * [Limit native search](#limit-native-search) > * [Option A: model suffixes](#option-a-model-suffixes) > * [Option B: request body configuration](#option-b-request-body-configuration-recommended) > * [Option C: OpenAI web_search_options](#option-c-openai-web_search_options) > * [Provider-specific options](#provider-specific-options-set-inside-the-web-search-object) > * [Examples](#examples) > * [Pricing by provider](#pricing-by-provider) > * [Bring your own key (BYOK)](#bring-your-own-key-byok) > [accordion] Images & caching > > * [Image Input](#image-input) > * [Video Input](#video-input) > * [Supported Forms](#supported-forms) > * [Message Shape](#message-shape) > * [cURL - Image URL](#curl-image-url-non-streaming) > * [cURL - Base64 Data URL](#curl-base64-data-url-non-streaming) > * [cURL - Streaming SSE](#curl-streaming-sse) > * [Caching (Implicit and Explicit Controls)](#caching-implicit-and-explicit-controls) > * [Cache-Capable Provider Routing](#cache-capable-provider-routing) > * [Cache Consistency](#explicit-prompt-cache-consistency) > * [Troubleshooting](#troubleshooting) > [accordion] Memory & reasoning > > * [Context Memory](#context-memory) > * [Custom Context Size Override](#custom-context-size-override) > * [Reasoning Streams](#reasoning-streams) > * [Endpoint variants](#endpoint-variants) > * [Streaming payload format](#streaming-payload-format) > * [Showing or hiding reasoning](#showing-or-hiding-reasoning) > * [Reasoning Effort](#reasoning-effort) > * [Model suffix: reasoning effort](#model-suffix-reasoning-effort) > * [Model suffix: :reasoning-exclude](#model-suffix-reasoning-exclude) > * [Legacy delta field compatibility](#legacy-delta-field-compatibility) > [accordion] Other > > * [Service tiers (Flex and Fast/Priority)](#service-tiers-priority) > * [Compressed Request Bodies](#compressed-request-bodies) > * [YouTube Transcripts](#youtube-transcripts) > * [Performance Benchmarks](#performance-benchmarks) > * [Important Notes](#important-notes) ## Advisor extension * `advisor` (optional object): Configures one different, client-selected model that the executor may consult. The initial version is limited to non-streaming, pay-as-you-go API-key requests and cannot be combined with client tools or structured output. See [Advisor](/api-reference/miscellaneous/advisor) for the full request contract, billing, privacy, response metadata, and limitations. ## Tool calling The `/api/v1/chat/completions` endpoint supports OpenAI-compatible function calling. You can describe callable functions in the `tools` array, control when the model may invoke them, and continue the conversation by echoing `tool` role messages that reference the assistant's chosen call. ### Request parameters * `tools` (optional array): Each entry must be `{ "type": "function", "function": { "name": string, "description"?: string, "parameters"?: JSON-Schema object } }`. Only `function` tools are accepted. A request can declare up to 1,024 tools, and the serialized `tools` array can be up to 1 MiB (1,048,576 bytes). Some models accept fewer tools; GPT-4o Mini accepts 128. Too many tools returns a 400 with `too_many_tools`, an oversized catalog returns `tool_spec_too_large`, and a malformed entry returns `invalid_tool_spec` or `invalid_tool_spec_parse`. * `tool_choice` (optional string or object): Defaults to `auto`. Set `"none"` to guarantee no tool calls (the server also drops the `tools` payload upstream), `"required"` to force the next response to be a tool call, or `{ "type": "function", "function": { "name": "your_function" } }` to pin the exact function. * `parallel_tool_calls` (optional boolean): When `true` the flag is forwarded to providers that support issuing multiple tool calls in a single turn. Models that ignore the flag fall back to sequential calls. * `max_tool_calls` (optional integer): Caps the built-in tool calls, such as [native web search](#limit-native-search), that the model makes in one response. With native search on GPT-5+ and o-series models it defaults to 5 (not on instant chat variants or deep-research models); set it lower or higher to change that. It applies to requests NanoGPT sends to OpenAI's Responses API, including fallback routes; other routes ignore it. * `messages[].tool_calls` (assistant role): Persist the tool call metadata returned by the model so future turns can see which functions were invoked. Each item uses the OpenAI shape `{ id, type: "function", function: { name, arguments } }`. * `messages[]` with `role: "tool"`: Respond to the model by sending `{ "role": "tool", "tool_call_id": "", "content": "" }`. The server drops any tool response that references an unknown `tool_call_id`, so keep the IDs in sync. * Validation behavior: If you send `tool_choice: "none"` with a `tools` array the request is accepted but the tools are omitted before hitting the model; invalid schemas or oversize payloads return the error codes above. ### Example request ```http theme={null} POST /api/v1/chat/completions { "model": "google/gemini-3-flash-preview", "messages": [ { "role": "user", "content": "What's the temperature in San Francisco right now?" } ], "tools": [ { "type": "function", "function": { "name": "lookup_weather", "description": "Fetch the current weather for a city.", "parameters": { "type": "object", "properties": { "city": { "type": "string" }, "unit": { "type": "string", "enum": ["c", "f"] } }, "required": ["city"] } } } ], "tool_choice": "auto", "parallel_tool_calls": true } ``` ### Example assistant/tool turn ```json theme={null} { "role": "assistant", "content": null, "tool_calls": [ { "id": "call_abc123", "type": "function", "function": { "name": "lookup_weather", "arguments": "{\"city\":\"San Francisco\",\"unit\":\"f\"}" } } ] } ``` ```json theme={null} { "role": "tool", "tool_call_id": "call_abc123", "content": "{\"city\":\"San Francisco\",\"temperatureF\":58,\"conditions\":\"foggy\"}" } ``` Streaming responses emit delta events that mirror OpenAI's `tool_calls` schema, so consumers can reuse their existing parsing logic without changes. ## Overview The Chat Completion endpoint provides OpenAI-compatible chat completions. ## Provider Routing Suffixes Provider-selection-capable models support routing preference suffixes such as `:fast` and `:cheap`. See [Provider Selection > Per-Request Routing Preference](/api-reference/miscellaneous/provider-selection#per-request-routing-preference) for the full list and billing rules, or [Model Suffixes](/api-reference/miscellaneous/model-suffixes) for all suffix composition rules. ## Provider Routing Object The `provider` request body field accepts either a provider ID string or a structured object for routing controls: ```json theme={null} { "model": "model-id", "provider": { "order": ["provider-a", "provider-b"], "only": ["provider-b"], "ignore": ["provider-c"], "sort": "price", "quantizations": ["fp8", "fp16"], "min_quantization": "fp8", "max_price": { "prompt": 0.5, "completion": 2 }, "allow_fallbacks": false, "require_parameters": true }, "messages": [ { "role": "user", "content": "Hello" } ] } ``` Use [Provider Selection > Provider Routing Object](/api-reference/miscellaneous/provider-selection#provider-routing-object) for field semantics, validation behavior, and provider discovery. That page also covers [performance cutoffs](/api-reference/miscellaneous/provider-selection#performance-cutoffs). ## Model Fallbacks Send `models` to list other models to try if one fails before any output is sent. `model` goes first, and `models` can also be sent alone. A request can try at most 4 models. The model that answered is billed, and so is a failed attempt its provider charged for. See [Model fallbacks](/api-reference/miscellaneous/provider-selection#model-fallbacks). ## Sampling & Decoding Controls The `/api/v1/chat/completions` endpoint accepts a full set of sampling and decoding knobs. All fields are optional; omit any you want to leave at provider defaults. ### Temperature & Nucleus | Parameter | Range/Default | Description | | - | - | - | | `temperature` | 0–2 (provider default) | Classic randomness control; higher values explore more. If omitted, NanoGPT does not force a value and the routed provider/model default applies. | | `top_p` | 0–1 (default 1) | Nucleus sampling that trims to the smallest set above `top_p` cumulative probability. | | `top_k` | 1+ | Sample only from the top-k tokens each step. | | `top_a` | provider default | Blends temperature and nucleus behavior; set only if a model calls for it. | | `min_p` | 0–1 | Require each candidate token to exceed a probability floor. | | `tfs` | 0–1 | Tail free sampling; 1 disables. | | `eta_cutoff` / `epsilon_cutoff` | provider default | Drop tokens once they fall below the tail thresholds. | | `typical_p` | 0–1 | Entropy-based nucleus sampling; keeps tokens whose surprise matches expected entropy. | | `mirostat_mode` | 0/1/2 | Enable Mirostat sampling; set tau/eta when active. | | `mirostat_tau` / `mirostat_eta` | provider default | Target entropy and learning rate for Mirostat. | ### Length & Stopping | Parameter | Range/Default | Description | | - | - | - | | `max_tokens` | 1+ (provider default) | Upper bound on generated tokens. If omitted, NanoGPT does not enforce an explicit default and the routed provider/model default applies. | | `min_tokens` | 0+ (default 0) | Minimum completion length when provider supports it. | | `stop` | string or string\[] | Stop sequences passed upstream. | | `stop_token_ids` | int\[] | Stop generation on specific token IDs (limited provider support). | | `include_stop_str_in_output` | boolean (default false) | Keep the stop sequence in the final text where supported. | | `ignore_eos` | boolean (default false) | Continue even if the model predicts EOS internally. | ### Penalties & Repetition Guards | Parameter | Range/Default | Description | | - | - | - | | `frequency_penalty` | -2 – 2 (default 0) | Penalize tokens proportional to prior frequency. | | `presence_penalty` | -2 – 2 (default 0) | Penalize tokens based on whether they appeared at all. | | `repetition_penalty` | 0–2 (default 1) | Penalize tokens that already appear in the conversation, on most providers including the prompt. 1 turns it off and values above 1 discourage repeats. Values below 1 encourage repetition and can cause misspelled words and endless loops, especially with long prompts. Unlike the two penalties above, the neutral value is 1, not 0. | | `no_repeat_ngram_size` | 0+ | Forbid repeating n-grams of the given size (limited support). | | `custom_token_bans` | int\[] | Fully block listed token IDs. | ### Logit Shaping & Reproducibility | Parameter | Range/Default | Description | | - | - | - | | `logit_bias` | object | Map token IDs to additive logits (OpenAI-compatible). | | `logprobs` | boolean or int | Return token-level logprobs where supported. | | `prompt_logprobs` | boolean | Request logprobs on the prompt when available. | | `seed` | integer | Optional integer forwarded on model/provider routes that support seeded sampling. This may improve reproducibility but does not guarantee identical output. Results can change if NanoGPT selects a different automatic or fallback route, or if the provider changes its backend. | #### Reproducibility guidance Seeded generation is best-effort. To reduce avoidable variation: * Keep the exact model, messages, tools, and sampling settings unchanged. * Select a specific provider where possible. * Disable automatic fallbacks where supported when route consistency matters. * Use a low or zero `temperature` where supported. * Do not treat seeded output as byte-identical. Record provider, route, and system-fingerprint metadata when NanoGPT exposes reliable values. NanoGPT will publish a seed-support matrix when reliable route-level capability data is available. Until then, do not infer seed support from endpoint compatibility alone. ### Usage notes * Parameters can be combined (e.g., `temperature` + `top_p` + `top_k`), but overly narrow settings may lead to early stops. * Invalid ranges yield a 400 before reaching the provider. * Provider defaults apply to any omitted field. ### Example request ```bash theme={null} curl -X POST https://api.nano-gpt.com/api/v1/chat/completions \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "google/gemini-3-flash-preview", "messages": [ {"role": "user", "content": "Write a creative story about space exploration"} ], "temperature": 0.8, "top_p": 0.9, "top_k": 40, "tfs": 0.8, "typical_p": 0.95, "mirostat_mode": 2, "mirostat_tau": 5, "mirostat_eta": 0.1, "max_tokens": 500, "frequency_penalty": 0.3, "presence_penalty": 0.1, "repetition_penalty": 1.1, "stop": ["###"], "seed": 42 }' ``` ## Structured Outputs (response_format) The `/api/v1/chat/completions` endpoint supports OpenAI-compatible structured outputs via the `response_format` parameter. This ensures the model returns valid JSON matching your specified schema. ### Supported Formats | Type | Description | | - | - | | `json_object` | Forces the model to return valid JSON | | `json_schema` | Forces the model to return JSON matching a specific schema | | `text` | Default text output (no constraint) | | `questions` | Decision models only: typed Choice, Score and yes/no answers. See [Decisions](/api-reference/endpoint/decisions). | ### JSON Object Mode Request valid JSON output without a specific schema: ```json theme={null} { "model": "openai/gpt-5.1", "messages": [{"role": "user", "content": "List 3 colors as JSON"}], "response_format": {"type": "json_object"} } ``` ### JSON Schema Mode (Structured Outputs) Request JSON that conforms to a specific schema: ```json theme={null} { "model": "openai/gpt-5.1", "messages": [{"role": "user", "content": "What is 2+2?"}], "response_format": { "type": "json_schema", "json_schema": { "name": "math_answer", "strict": true, "schema": { "type": "object", "properties": { "answer": {"type": "number"}, "explanation": {"type": "string"} }, "required": ["answer", "explanation"], "additionalProperties": false } } } } ``` ### Schema Requirements When using `strict: true`: * All properties must be listed in `required` * Set `additionalProperties: false` * NanoGPT automatically transforms optional properties to be nullable for OpenAI compatibility ### Supported Models JSON schema mode works with most models including: * OpenAI models (GPT-5.1, GPT-5.2, etc.) * Anthropic Claude models * Google Gemini models * Many open-source models ### Example Request ```bash cURL theme={null} curl -X POST https://api.nano-gpt.com/api/v1/chat/completions \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "openai/gpt-5.1", "messages": [ {"role": "user", "content": "Generate a person profile"} ], "response_format": { "type": "json_schema", "json_schema": { "name": "person", "strict": true, "schema": { "type": "object", "properties": { "name": {"type": "string"}, "age": {"type": "number"}, "skills": { "type": "array", "items": {"type": "string"} } }, "required": ["name", "age", "skills"], "additionalProperties": false } } }, "stream": false }' ``` ```python Python theme={null} import requests response = requests.post( "https://api.nano-gpt.com/api/v1/chat/completions", headers={ "Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json" }, json={ "model": "openai/gpt-5.1", "messages": [ {"role": "user", "content": "Generate a person profile"} ], "response_format": { "type": "json_schema", "json_schema": { "name": "person", "strict": True, "schema": { "type": "object", "properties": { "name": {"type": "string"}, "age": {"type": "number"}, "skills": { "type": "array", "items": {"type": "string"} } }, "required": ["name", "age", "skills"], "additionalProperties": False } } } } ) data = response.json() print(data["choices"][0]["message"]["content"]) # Output: {"name": "Alice Chen", "age": 28, "skills": ["Python", "Machine Learning", "Data Analysis"]} ``` ```javascript JavaScript theme={null} const response = await fetch("https://api.nano-gpt.com/api/v1/chat/completions", { method: "POST", headers: { "Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json" }, body: JSON.stringify({ model: "openai/gpt-5.1", messages: [ { role: "user", content: "Generate a person profile" } ], response_format: { type: "json_schema", json_schema: { name: "person", strict: true, schema: { type: "object", properties: { name: { type: "string" }, age: { type: "number" }, skills: { type: "array", items: { type: "string" } } }, required: ["name", "age", "skills"], additionalProperties: false } } } }) }); const data = await response.json(); console.log(data.choices[0].message.content); // Output: {"name": "Alice Chen", "age": 28, "skills": ["Python", "Machine Learning", "Data Analysis"]} ``` ### Example Response ```json theme={null} { "id": "chatcmpl-abc123", "object": "chat.completion", "created": 1769278225, "model": "openai/gpt-5.1", "choices": [ { "index": 0, "message": { "role": "assistant", "content": "{\"name\":\"Alice Chen\",\"age\":28,\"skills\":[\"Python\",\"Machine Learning\",\"Data Analysis\"]}" }, "finish_reason": "stop" } ] } ``` ### Usage with Vercel AI SDK The `response_format` parameter is compatible with Vercel AI SDK's `generateObject`: ```typescript theme={null} import { generateObject } from 'ai'; import { createOpenAI } from '@ai-sdk/openai'; import { z } from 'zod'; const nanogpt = createOpenAI({ baseURL: 'https://api.nano-gpt.com/api/v1', apiKey: 'YOUR_API_KEY', }); const { object } = await generateObject({ model: nanogpt('openai/gpt-5.1'), schema: z.object({ name: z.string(), age: z.number(), skills: z.array(z.string()), }), prompt: 'Generate a person profile', }); console.log(object); // { name: "Alice Chen", age: 28, skills: ["Python", "Machine Learning", "Data Analysis"] } ``` ### Usage Notes * Works with both streaming and non-streaming requests * The `name` field in `json_schema` is required and should describe the output * Response content is a JSON string; parse it with `JSON.parse()` in your application * Some provider-specific limitations may apply; if you encounter issues with a specific model, try an alternative ## Web Search Enable web search in three ways: a model suffix, a `web_search` field in the request body, or OpenAI's `web_search_options`. * `web_search` accepts an object or a boolean. `true` turns search on with the default provider. * `webSearch` and the legacy `linkup` object are accepted as aliases. If a request sends more than one, `web_search` wins, then `webSearch`, then `linkup`. * If the body object has `enabled: true`, its settings override the suffix's settings field by field; settings it leaves out keep the suffix's values. * On GPT-5+ and o-series models, an enabled body without `provider` selects native search even when the suffix names another provider. Set `provider` to keep a different one. * `web_search: false` (or `enabled: false`) does not switch off search requested by an `:online` suffix. Remove the suffix to turn search off. ### Native search Native search uses the model's own built-in web search instead of a separate search provider. It is available on GPT-5 and later and o-series (o1, o3, o4) models, Claude 4 and later, Gemini 3 and later, and Grok 4.20 and later. Image, multi-agent, and `:free` variants are not supported. * GPT-5+ and o-series models use native search by default whenever web search is on. To use another provider, set `provider` or use a suffix such as `:online/linkup`. * Other models, including older GPT models, use Linkup by default. Request native search with `"provider": "native"` or the `:online/native` suffix. * If you request native search on a model without it, the request searches with the suffix's provider or Linkup instead. * Native requests on Claude, Gemini, or Grok can fail with `400` and code `native_web_search_unavailable` when your provider restrictions leave no route that can run native search. On GPT models, such restrictions can instead leave the request answering without a search. * With your own provider keys (BYOK), native search runs on OpenAI keys (GPT and o-series models) and Anthropic keys (Claude). The searches are billed to your provider account, not by NanoGPT. Other BYOK routes use Linkup instead. On Anthropic, an organization admin can turn web search off; requests then fail with Anthropic's `400` error. * The model decides how many searches to run, up to a limit. On GPT-5+ and o-series models the limit is 5 by default (instant chat variants and deep-research models excepted); change it with `max_tool_calls` (see [Limit native search](#limit-native-search)). On Claude, NanoGPT normally caps this at 2 (`low`), 3 (`medium`, the default), or 5 (`high`) searches per request, and skips native search when `tool_choice` is `none` or when you define your own function named `web_search`. * Each search the model runs is billed once at the native rate (see [Pricing by provider](#pricing-by-provider)), even when it covers several queries. On GPT-5+ and o-series models, NanoGPT does not bill opening a page, searching within a page, or calls stopped by `max_tool_calls`. Every search that ran is billed, whether or not the answer shows source links. With your own OpenAI key (BYOK), OpenAI bills the searches to your account instead. Where a route reports no count, NanoGPT may bill an estimate: 1 search for `low`, 2 otherwise. * The search results are added to the model's input and billed at the model's input token rate, on top of the search fees. On larger models this is often most of the cost: a GPT-5.5 answer that searches several times can read tens of thousands of input tokens. #### Limit native search On GPT-5+ and o-series models, the top-level `max_tool_calls` field caps how many built-in tool calls the model can make while answering. Searches, page opens, and searches within a page all count toward the cap, so a response bills at most that many searches (one search can cover several queries). Once it is reached, the model answers with what it has found; further calls are not run and not billed. Without `max_tool_calls`, NanoGPT sends a cap of 5. A lower value is kept. To allow more searches, set a higher value; each extra search is billed at the normal per-search rate. The instant chat variants and deep-research models get no default cap. The cap applies when NanoGPT sends the request to OpenAI, including with your own OpenAI key (BYOK) and on fallback routes. OpenRouter accepts at most 30. ```json theme={null} { "model": "openai/gpt-5.5:online", "max_tool_calls": 3, "messages": [ { "role": "user", "content": "Which commercial cleaning companies in Leeds would you recommend?" } ] } ``` `max_tool_calls` has no effect on Claude, Gemini, or Grok native search; on Claude, `search_context_size` sets the cap. For a fixed search fee per request, use another provider, such as `:online/linkup`; model token charges still apply. If you need full direct control over the search call itself (`query`, `outputType`, date/domain filters, or structured schema output), use [Direct Web Search API (`POST /api/web`)](/api-reference/endpoint/web-search). | Use case | Recommended endpoint | | - | - | | Model should answer with web context in one call | `POST /api/v1/chat/completions` | | You need raw/structured web payload control | `POST /api/web` | ### Option A: model suffixes Append one of these to your `model` value: * `:online` (default web search, standard depth; native search on GPT-5+ and o-series models) * `:online/native` (the model's own search; see [Native search](#native-search)) * `:online/linkup` (Linkup, standard) * `:online/linkup-deep` (Linkup, deep) * `:online/tavily` (Tavily, standard) * `:online/tavily-deep` (Tavily, deep) * `:online/brave` (Brave, standard) * `:online/brave-deep` (Brave, deep) * `:online/sofya` (Sofya, standard) * `:online/exa-fast` (Exa, fast) * `:online/exa-auto` (Exa, auto) * `:online/exa-neural` (Exa, neural) * `:online/exa-deep` (Exa, deep) * `:online/exa-instant` (Exa, instant) * `:online/exa-deep-reasoning` (Exa, deep-reasoning) * `:online/kagi` (Kagi, standard, search) * `:online/kagi-web` (Kagi, standard, web) * `:online/kagi-news` (Kagi, standard, news) * `:online/kagi-search` (Kagi, deep, search) * `:online/perplexity` (Perplexity, standard) * `:online/perplexity-deep` (Perplexity, deep) * `:online/valyu` (Valyu, standard, all sources) * `:online/valyu-deep` (Valyu, deep, all sources) * `:online/valyu-web` (Valyu, standard, web only) * `:online/valyu-web-deep` (Valyu, deep, web only) * `:online/firecrawl` (Firecrawl, standard) * `:online/firecrawl-deep` (Firecrawl, deep) `:online` without an explicit provider uses the default: native search on GPT-5+ and o-series models, Linkup on other models. ### Option B: request body configuration (recommended) Send a `web_search` object in the request body. `webSearch` and the legacy `linkup` object are accepted as aliases. This works with or without a model suffix and controls web search across all providers. `"web_search": true` is shorthand for `{ "enabled": true }`. `web_search` fields: * `enabled` (boolean, required to activate web search) * `provider` (string): `native` | `linkup` | `tavily` | `brave` | `sofya` | `exa` | `kagi` | `perplexity` | `valyu` | `firecrawl` * `depth` (string): * Linkup/Tavily/Brave/Perplexity/Valyu/Firecrawl: `standard` or `deep` * Sofya: `standard` * Exa: `fast`, `auto`, `neural`, `deep`, `instant`, `deep-reasoning` (use `standard` if you want `auto`) * Kagi: `standard` or `deep` (`search` source only) * `search_context_size` or `searchContextSize` (string, native search): `low` | `medium` | `high` (default: `medium`; OpenAI deep-research models always use `medium`) * `user_location` or `userLocation` (object, native search on GPT-5+ and o-series models): `{ type: "approximate", country, city, region, timezone }`. It may be ignored when a fallback route serves the request. * `searchType` (string, Valyu only): `all` | `web` * `kagiSource` or `kagi_source` (string, Kagi only): `web` | `news` | `search` Shorthand and legacy alias examples: ```json theme={null} { "web_search": true } ``` ```json theme={null} { "linkup": { "enabled": true, "provider": "tavily" } } ``` ### Option C: OpenAI `web_search_options` Requests written for OpenAI's Chat Completions API can send `web_search_options`. It turns on web search with the default provider: native search on GPT-5+ and o-series models, Linkup on other models. ```json theme={null} { "model": "openai/gpt-6.1-sol", "messages": [{ "role": "user", "content": "What changed in the news today?" }], "web_search_options": { "search_context_size": "low", "user_location": { "type": "approximate", "approximate": { "country": "US", "city": "Austin", "region": "Texas" } } } } ``` * `search_context_size` (`low` | `medium` | `high`) is passed to native search. It never selects deep search. * `user_location` is passed to native search on GPT-5+ and o-series models. * If the request also sends `web_search`, `webSearch`, or `linkup`, those settings are used and `web_search_options` is ignored. * With an `:online/` suffix, the suffix's provider is kept. * Models that already search on their own, such as search-preview and deep-research models, ignore `web_search_options`. The NanoGPT help model rejects a non-empty `web_search_options` object. #### Provider-specific options (set inside the web search object) ##### Perplexity ```json theme={null} { "maxResults": 1-20, "maxTokensPerPage": number, "maxTokens": 1-1000000, "country": "string", "searchDomainFilter": ["domain1.com", "domain2.com"], "searchLanguageFilter": ["en", "de"] } ``` Limits: `searchDomainFilter` max 20 entries; `searchLanguageFilter` max 10 entries (ISO 639-1). ##### Valyu ```json theme={null} { "searchType": "all" | "web", "fastMode": boolean, "maxNumResults": 1-50, "maxPrice": number, "relevanceThreshold": 0-1, "responseLength": "short" | "medium" | "large" | "max" | number, "countryCode": "US", "includedSources": ["source1.com"], "excludedSources": ["source2.com"], "urlOnly": boolean, "category": "string" } ``` `countryCode` uses a 2-letter ISO country code. ##### Tavily ```json theme={null} { "maxResults": 0-20, "includeAnswer": boolean | "basic" | "advanced", "includeRawContent": boolean | "markdown" | "text", "includeImages": boolean, "includeImageDescriptions": boolean, "includeFavicon": boolean, "topic": "general" | "news" | "finance", "timeRange": "day" | "week" | "month" | "year", "startDate": "YYYY-MM-DD", "endDate": "YYYY-MM-DD", "chunksPerSource": 1-3, "country": "string" } ``` ##### Exa ```json theme={null} { "numResults": 1-100, "category": "company" | "research paper" | "news" | "pdf" | "github" | "tweet" | "personal site" | "people" | "financial report", "userLocation": "US", "additionalQueries": ["query2"], "startCrawlDate": "ISO 8601", "endCrawlDate": "ISO 8601", "startPublishedDate": "ISO 8601", "endPublishedDate": "ISO 8601", "includeText": ["pattern"], "excludeText": ["pattern"], "livecrawl": "never" | "fallback" | "always" | "preferred", "livecrawlTimeout": number, "subpages": number, "subpageTarget": "string" | ["strings"] } ``` ##### Sofya Sofya search returns extracted page content rather than snippets alone. Chat completions use its Search operation. For explicit query options and Sofya's Fetch, Extract, and Research operations, use the [Direct Web Search API](/api-reference/endpoint/web-search#sofya-operations). ##### Native search ```json theme={null} { "provider": "native", "search_context_size": "low" | "medium" | "high", "user_location": { "type": "approximate", "country": "US", "city": "San Francisco", "region": "California", "timezone": "America/Los_Angeles" } } ``` `user_location` applies to GPT-5+ and o-series models only. ### Examples ```python Python theme={null} import requests import json BASE_URL = "https://api.nano-gpt.com/api/v1" API_KEY = "YOUR_API_KEY" headers = { "Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json" } # Suffix-based standard web search data = { "model": "openai/gpt-6.1-sol:online", "messages": [ {"role": "user", "content": "What are the latest developments in AI?"} ] } response = requests.post( f"{BASE_URL}/chat/completions", headers=headers, json=data ) # Request-body configuration (Exa neural) data_search = { "model": "openai/gpt-6.1-sol", "messages": [ {"role": "user", "content": "Provide a comprehensive analysis of recent AI breakthroughs"} ], "web_search": { "enabled": True, "provider": "exa", "depth": "neural", "numResults": 10 } } ``` ```javascript JavaScript theme={null} const BASE_URL = "https://api.nano-gpt.com/api/v1"; const API_KEY = "YOUR_API_KEY"; // Suffix-based standard web search const response = await fetch(`${BASE_URL}/chat/completions`, { method: 'POST', headers: { 'Authorization': `Bearer ${API_KEY}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ model: 'openai/gpt-6.1-sol:online', messages: [ { role: 'user', content: 'What are the latest developments in AI?' } ] }) }); // Request-body configuration (Exa neural) const searchResponse = await fetch(`${BASE_URL}/chat/completions`, { method: 'POST', headers: { 'Authorization': `Bearer ${API_KEY}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ model: 'openai/gpt-6.1-sol', messages: [ { role: 'user', content: 'Provide a comprehensive analysis of recent AI breakthroughs' } ], web_search: { enabled: true, provider: 'exa', depth: 'neural', numResults: 10 } }) }); ``` ```bash cURL theme={null} # Suffix-based standard web search curl -X POST https://api.nano-gpt.com/api/v1/chat/completions \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "openai/gpt-6.1-sol:online", "messages": [ {"role": "user", "content": "What are the latest developments in AI?"} ] }' # Request-body configuration (Exa neural) curl -X POST https://api.nano-gpt.com/api/v1/chat/completions \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "openai/gpt-6.1-sol", "messages": [ {"role": "user", "content": "Provide a comprehensive analysis of recent AI breakthroughs"} ], "web_search": { "enabled": true, "provider": "exa", "depth": "neural", "numResults": 10 } }' ``` ### Pricing by provider | Provider | Standard | Deep | Notes | | - | - | - | - | | Linkup | \$0.006 | \$0.06 | Default provider | | Tavily | \$0.008 | \$0.016 | Good value, free tier available | | Exa | \$0.005 base | + \$0.001/page | For contents retrieval | | Kagi Web/News | \$0.002 | N/A | Cheapest for enrichment | | Kagi Search | \$0.025 | N/A | Full search mode | | Perplexity | \$0.005 | N/A | Flat rate | | Valyu | \~\$0.0015/result | Variable | Dynamic pricing | | Brave | \$0.005 | \$0.005 | Flat rate | | Sofya | \$0.01575 | N/A | Extracted page content; standard depth only | | Firecrawl | \~\$0.0105 | \~\$0.018 | \$0.0015 per Firecrawl credit used; standard is about 7 credits, deep about 12 | | Native | Per search + tokens | N/A | GPT and Claude $0.01, Gemini $0.014, Grok \$0.005 per search, plus model token costs. GPT searches default to at most 5 per request; change with `max_tool_calls` | For standard NanoGPT usage, provider credentials are handled automatically. ### Bring your own key (BYOK) BYOK lets you route requests through your own upstream provider credentials. * Configure keys once: [https://nano-gpt.com/byok](https://nano-gpt.com/byok) * Opt in per request via `x-use-byok: true` or `byok.enabled: true` * Optionally force the provider via `x-byok-provider` or `byok.provider` * BYOK usage includes a **5% platform fee** (your provider bills you directly for usage) See: [Bring Your Own Key (BYOK)](/api-reference/miscellaneous/byok) #### Web search BYOK Web search BYOK availability is provider-dependent and can change over time. See the BYOK reference for the current support matrix. ### Advanced behavior (optional) * **Provider routing**: For GPT-5+ and o-series models, web search without an explicit provider uses native search. If you set `web_search.provider` or use an explicit `:online/` suffix, that provider is used instead, unless an enabled body without `provider` is also sent (see [Web Search](#web-search)). * **Model suffix normalization**: `:online` (and provider/depth suffixes) are stripped from the model name before routing to the base model; the suffix only controls search behavior. * **Query formation (providers other than native)**: The search query is derived from your latest user message and may include the previous user message if the latest is short. If you need full control over the query or raw results, use the Web Search endpoint (`/api/web`). * **`scraping: true` URL handling**: When enabled, NanoGPT scans messages for public `http(s)` URLs, ignores local/private URLs, de-duplicates, and caps at 5. If no eligible URLs are found, scraping is skipped. Inline scraping in chat is billed at **\$0.0015 per successfully scraped URL**. For explicit URL lists and the standalone endpoint price (**\$0.001 per URL**), use `/scrape-urls`. With your own Firecrawl, Berrycrawl or Linkup key saved, page reads run on your key at no NanoGPT charge; send `scraping: { "enabled": true, "byok": false }` to use NanoGPT's keys instead. See [Page reading keys](/api-reference/miscellaneous/byok#page-reading-keys). ## Image Input Send images using the OpenAI‑compatible chat format. Provide image parts alongside text in the `messages` array. ### Supported Forms * Remote URL: `{"type":"image_url","image_url":{"url":"https://..."}}` * Base64 data URL: `{"type":"image_url","image_url":{"url":"data:image/png;base64,...."}}` Notes: * For many or large images, send HTTPS URLs. A base64 data URL puts the whole image in the request body, about a third larger than the image file. Request bodies on `https://api.nano-gpt.com` are limited to 32 MiB (compressed and decompressed), and large bodies take longer to upload and process before the model starts. A URL keeps the request small; the image is fetched separately. * URLs must be public HTTPS addresses that load without a login or cookies. Some upstreams reject non‑HTTPS URLs. * Use base64 data URLs for local or private images, and for models that accept only inline images. Those models return an `unsupported_parameter` error saying that no available route supports remote image URLs. * The number of images a request can carry varies by route, and images in conversation history count. * On `https://nano-gpt.com`, a request body over about 4.5 MB gets HTTP 413, compressed or not, before it reaches the API. For larger requests, use `https://api.nano-gpt.com/api/v1`. * Resize large images before sending them. Most vision models scale images down before reading them, so full-resolution photos, screenshots and video frames mostly add upload time. About 1,500 pixels on the longest side, saved as JPEG or WebP, is usually enough. * For video, send the clip as [`video_url`](#video-input) to a model that supports video input, or sample fewer frames, instead of sending hundreds of frames as images. * Accepted mime types: `image/png`, `image/jpeg`, `image/jpg`, `image/webp`. * Inline markdown images in plain text (e.g., `![alt](data:image/...;base64,...)`) are auto‑normalized into structured parts server‑side. ### Message Shape ```json theme={null} { "role": "user", "content": [ { "type": "text", "text": "What is in this image?" }, { "type": "image_url", "image_url": { "url": "https://example.com/image.jpg" } } ] } ``` ### cURL — Image URL (non‑streaming) ```bash theme={null} curl -sS \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -X POST https://api.nano-gpt.com/api/v1/chat/completions \ --data '{ "model": "google/gemini-3-flash-preview", "messages": [ { "role": "user", "content": [ {"type": "text", "text": "Describe this image in three words."}, {"type": "image_url", "image_url": {"url": "https://upload.wikimedia.org/wikipedia/commons/3/3f/Fronalpstock_big.jpg"}} ] } ], "stream": false }' ``` ### cURL — Base64 Data URL (non‑streaming) Embed your image as a data URL. Replace `...BASE64...` with your image bytes. ```bash theme={null} curl -sS \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -X POST https://api.nano-gpt.com/api/v1/chat/completions \ --data '{ "model": "google/gemini-3-flash-preview", "messages": [ { "role": "user", "content": [ {"type": "text", "text": "What is shown here?"}, {"type": "image_url", "image_url": {"url": "data:image/png;base64,...BASE64..."}} ] } ], "stream": false }' ``` ### cURL — Streaming SSE See also: [Streaming Protocol (SSE)](/api-reference/miscellaneous/streaming-protocol). ```bash theme={null} curl -N \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -H "Accept: text/event-stream" \ -X POST https://api.nano-gpt.com/api/v1/chat/completions \ --data '{ "model": "google/gemini-3-flash-preview", "messages": [ { "role": "user", "content": [ {"type": "text", "text": "Two words only."}, {"type": "image_url", "image_url": {"url": "https://example.com/image.jpg"}} ] } ], "stream": true, "stream_options": { "include_usage": true } }' ``` The response streams `data: { ... }` lines until a final terminator. Usage metrics appear only when requested: set `stream_options.include_usage` to `true` for streaming responses, or send `"include_usage": true` on non-streaming calls. `usage: {"include": true}` also works. On a non-streaming call, any of these makes the response wait briefly for billing, so `usage.cost` is usually present. *Note: Prompt-caching helpers implicitly force `include_usage`, so cached requests still receive usage data without extra flags.* ## Video Input Send video clips to a compatible text or multimodal model using the canonical `video_url` content part. The URL may be a public HTTPS URL or a `data:video/*;base64,...` URL: ```json theme={null} { "model": "google/gemini-3.1-flash-lite", "messages": [{ "role": "user", "content": [ { "type": "text", "text": "Describe this clip." }, { "type": "video_url", "video_url": { "url": "https://cdn.example.com/clip.mp4", "detail": "auto" } } ] }] } ``` Compatibility aliases (`input_video`, direct `video`, and safely identifiable `input_file`/`file` blocks) are accepted, but new integrations should emit `video_url`. See the [Video Input guide](/api-reference/miscellaneous/video-input) for model discovery, source validation, limits, errors, YouTube behavior, and the Responses and Messages shapes. ### Caching (Implicit and Explicit Controls) For the full guide (supported models, thresholds, pricing, and usage fields), see [Prompt Caching](/api-reference/miscellaneous/prompt-caching). NanoGPT automatically applies implicit caching on providers/models that support it (including OpenAI, Gemini, and many open-source provider/model routes), so most requests do not need caching flags. Set top-level `caching: true` or append `:caching` / `:cache` / `:cached` to the model when you want NanoGPT to route the request to any available provider that supports prompt/input caching. This is capability-based routing: you do not need to choose a provider. If no cache-capable provider is available for the model, the request fails rather than silently using a non-caching provider. Use explicit prompt-caching controls (`prompt_caching`, `promptCaching`, and body-level `cache_control` alias, plus inline `cache_control`) when you need Claude-specific cache boundaries, TTL selection, or `prompt_caching.stickyProvider` consistency control. Top-level `caching: true` does not add Anthropic-style `cache_control` markers or configure cache TTLs. #### Cache-Capable Provider Routing Top-level `caching: true` is provider routing, not prompt-cache annotation. It requires the routed provider to be marked as prompt-caching capable for the requested provider-selection model. ```json theme={null} { "model": "model-id", "caching": true, "messages": [ { "role": "user", "content": "Hello" } ] } ``` `caching: true` prefers the provider from your previous matching request (soft affinity). `stickyProvider` defaults to `false`; set it to `true` to disable cross-provider fallback. Neither setting guarantees a cache hit. To disable cross-provider fallback for a cache-capable request, set `stickyprovider: true`: ```json theme={null} { "model": "model-id", "caching": true, "stickyprovider": true, "messages": [ { "role": "user", "content": "Hello" } ] } ``` Top-level fields: | Parameter | Type | Default | Description | | - | - | - | - | | `caching` | boolean | `false` | Require a cache-capable provider for this request. If none is usable for the model, the request fails. | | `stickyprovider` | boolean | `false` | Set `true` to disable cross-provider fallback. `false` allows fallback while keeping soft affinity for explicit cache-capable routing. | | `stickyProvider` | boolean | Alias | CamelCase alias for top-level `stickyprovider`. Use `stickyprovider` in examples. | Equivalent model suffix: ```json theme={null} { "model": "moonshotai/kimi-k2.6:thinking:caching", "messages": [ { "role": "user", "content": "Hello" } ] } ``` For `caching: true`, routing works as follows: 1. Filter to providers that are available, not excluded by preferences, and marked as prompt-caching capable. 2. Prefer the previously recorded provider for the same cache-relevant request shape when still usable. 3. Try eligible saved provider preferences, then choose using prices and recent aggregate cache-read observations. Price ranking takes precedence over cache-affinity selection. See [routing and caching combinations](/api-reference/miscellaneous/provider-selection#price-caps-and-cache-reuse), including how `max_price` can infer price ranking. The `prompt_caching` / `promptCaching` helper accepts these options: | Parameter | Type | Default | Description | | - | - | - | - | | `enabled` | boolean | — | Set `true` to enable or `false` to disable explicit caching; `ttl` alone does not enable it. | | `ttl` | string | `"5m"` | Cache time-to-live: `"5m"` or `"1h"`. Only the exact string `"1h"` selects one hour. | | `cut_after_message_index` / `cutAfterMessageIndex` | integer | — | Zero-based last message index eligible for automatic cache-boundary placement. Existing inline markers are preserved. | | `stickyProvider` | boolean | `false` | When `true`, disable automatic failover to preserve explicit prompt-cache consistency. Returns 503 error instead of switching services. | ```python theme={null} headers = { "Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json" } payload = { "model": "anthropic/claude-sonnet-4.6", "messages": [ { "role": "system", "content": [ { "type": "text", "text": "Reference handbook + rules of engagement.", "cache_control": {"type": "ephemeral", "ttl": "5m"} } ] }, {"role": "user", "content": "Live request goes here"} ] } requests.post("https://api.nano-gpt.com/api/v1/chat/completions", headers=headers, json=payload) ``` * Each `cache_control` marker caches the full prefix up to that block. Choose reusable prefix boundaries; you do not need a marker on every static chunk. The request supports at most four breakpoints across system, tools, and messages. * Explicit TTL controls are `5m` and `1h` for Claude caching flows. See [Prompt Caching](/api-reference/miscellaneous/prompt-caching#pricing). * `anthropic-beta: prompt-caching-2024-07-31` is an optional compatibility alternative. Callers using the helper or inline markers do not also need this header; NanoGPT handles upstream cache settings. * For implicit-caching providers, no explicit `cache_control` markers are required. * Supported explicit cache controls on Chat Completions use pay-as-you-go billing, including markers supplied automatically by clients. See [subscription billing for prompt caching](/api-reference/miscellaneous/prompt-caching#subscription-billing-for-chat-completions) and the [OpenCode caching guide](/integrations/opencode#claude-prompt-caching). For a simpler experience, send the helper fields and NanoGPT will place cache boundaries before forwarding upstream: ```ts theme={null} await client.chat.completions.create( { model: 'anthropic/claude-opus-5.5', messages: [ { role: 'system', content: 'Static rubric lives here.' }, { role: 'user', content: 'Additional reusable context.' }, { role: 'user', content: 'This turn is not cached.' }, ], prompt_caching: { enabled: true, ttl: '1h', cut_after_message_index: 1, }, }, ); ``` `cut_after_message_index` is zero-based and limits automatic boundary placement; it does not remove existing inline markers after that index. If omitted, NanoGPT selects boundaries automatically. Use inline `cache_control` blocks when you need to place individual boundaries. See [Prompt Caching](/api-reference/miscellaneous/prompt-caching) for marker and TTL precedence. ### Explicit Prompt Cache Consistency NanoGPT automatically fails over to backup services when the primary service is temporarily unavailable. While this ensures high availability, it can break your prompt cache because **each backend service maintains its own separate cache**. If cache consistency is more important than availability for your use case, you can enable the `stickyProvider` option: ```json theme={null} { "model": "anthropic/claude-sonnet-4.6", "messages": [...], "prompt_caching": { "enabled": true, "ttl": "5m", "stickyProvider": true } } ``` **Behavior:** * **`stickyProvider: false` (default)** — If an eligible backup is available, NanoGPT can retry there. That service may need to create its own cache. * **`stickyProvider: true`** — NanoGPT returns a 503 instead of failing over. The original cache remains subject to its TTL; this setting does not guarantee it will still exist when the service recovers. **When to use `stickyProvider: true`:** * You have very large cached contexts where cache misses are expensive * You prefer to retry failed requests yourself rather than pay for cache rebuilds * Cost predictability is more important than request success rate **When to use `stickyProvider: false` (default):** * You prefer requests to always succeed when possible * Occasional cache misses are acceptable * You're using shorter contexts where cache rebuilds are inexpensive **Error response when stickyProvider blocks a failover:** ```json theme={null} { "error": { "message": "Service is temporarily unavailable. Fallback disabled to preserve prompt cache consistency. Switching services would invalidate your cached tokens. Remove stickyProvider option or retry later.", "status": 503, "type": "service_unavailable", "code": "fallback_blocked_for_cache_consistency" } } ``` ### Troubleshooting * 400 unsupported image: ensure the image is a valid PNG/JPEG/WebP, not a tiny 1×1 pixel, and either HTTPS URL or a base64 data URL. * 413 request body too large: send images as HTTPS URLs or resize them. Request bodies on `https://api.nano-gpt.com` are limited to 32 MiB (compressed and decompressed). `https://nano-gpt.com` has an edge limit of about 4.5 MB per request, compressed or not; use `https://api.nano-gpt.com/api/v1` for larger requests. * 503 after fallbacks: try a different model, verify API key/session, and prefer base64 data URL for local or protected assets. * Missing usage events: confirm `include_usage` is `true` in the payload or that prompt caching is enabled. ## Context Memory Enable unlimited-length conversations with lossless, hierarchical memory. * Append `:memory` to any model name * Or send header `memory: true` * Can be combined with web search: `:online:memory` * Retention: default 30 days; configure via `:memory-` (1..365) or header `memory_expiration_days: `; header takes precedence ```python Python theme={null} import requests BASE_URL = "https://api.nano-gpt.com/api/v1" API_KEY = "YOUR_API_KEY" headers = { "Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json" } # Suffix-based payload = { "model": "openai/gpt-6.1-sol:memory", "messages": [{"role": "user", "content": "Keep our previous discussion in mind and continue."}] } requests.post(f"{BASE_URL}/chat/completions", headers=headers, json=payload) ``` ```javascript JavaScript theme={null} const BASE_URL = "https://api.nano-gpt.com/api/v1"; const API_KEY = "YOUR_API_KEY"; // Header-based (with optional retention override) await fetch(`${BASE_URL}/chat/completions`, { method: 'POST', headers: { 'Authorization': `Bearer ${API_KEY}`, 'Content-Type': 'application/json', 'memory': 'true', 'memory_expiration_days': '45' }, body: JSON.stringify({ model: 'openai/gpt-6.1-sol', messages: [{ role: 'user', content: 'Continue with full history awareness.' }] }) }); ``` ```bash cURL theme={null} # Combine with web search (and set retention to 90 days via suffix) curl -X POST https://api.nano-gpt.com/api/v1/chat/completions \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "openai/gpt-6.1-sol:online:memory-90", "messages": [ {"role": "user", "content": "Research and continue our plan without losing context."} ] }' # Header-based retention override (header takes precedence) curl -X POST https://api.nano-gpt.com/api/v1/chat/completions \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -H "memory: true" \ -H "memory_expiration_days: 45" \ -d '{ "model": "openai/gpt-6.1-sol", "messages": [ {"role": "user", "content": "Use memory with 45-day retention."} ] }' ``` ### Custom Context Size Override When Context Memory is enabled, you can override the model-derived context size used for the memory compression step with `model_context_limit`. * Parameter: `model_context_limit` (number or numeric string) * Default: Derived from the selected model’s context size * Minimum: Values below 10,000 are clamped internally * Scope: Only affects memory compression; does not change the target model’s own window Examples: ```bash theme={null} # Enable memory via header; use model default context size curl -s -X POST \ -H "Authorization: Bearer $NANOGPT_API_KEY" \ -H "Content-Type: application/json" \ -H "memory: true" \ https://api.nano-gpt.com/api/v1/chat/completions \ -d '{ "model": "google/gemini-3-flash-preview", "messages": [{"role":"user","content":"Briefly say hello."}], "stream": false }' # Explicit numeric override curl -s -X POST \ -H "Authorization: Bearer $NANOGPT_API_KEY" \ -H "Content-Type: application/json" \ -H "memory: true" \ https://api.nano-gpt.com/api/v1/chat/completions \ -d '{ "model": "google/gemini-3-flash-preview", "messages": [{"role":"user","content":"Briefly say hello."}], "model_context_limit": 20000, "stream": false }' # String override (server coerces to number) curl -s -X POST \ -H "Authorization: Bearer $NANOGPT_API_KEY" \ -H "Content-Type: application/json" \ -H "memory: true" \ https://api.nano-gpt.com/api/v1/chat/completions \ -d '{ "model": "google/gemini-3-flash-preview", "messages": [{"role":"user","content":"Briefly say hello."}], "model_context_limit": "30000", "stream": false }' ``` ## Reasoning Streams The Chat Completions endpoint separates the model’s visible answer from its internal reasoning. By default, reasoning is included and delivered alongside normal content so that clients can decide whether to display it. `:thinking` is model-specific and only works when that exact ID (or a documented alias) exists. `-thinking` is a legacy alias pattern for some model families only, not universal. Do not assume `-thinking` works for arbitrary model IDs. Always check `GET /api/v1/models` for exact valid IDs. See also: [Extended Thinking (Reasoning)](/api-reference/miscellaneous/extended-thinking). ### Endpoint variants Choose the base path that matches how your client consumes reasoning streams. These paths only change where reasoning appears; none of them turns it on. See [Extended Thinking](/api-reference/miscellaneous/extended-thinking#turn-reasoning-on) for that. * `https://api.nano-gpt.com/api/v1/chat/completions` — default endpoint that streams internal thoughts through `choices[0].delta.reasoning`, or returns them in `choices[0].message.reasoning` on non-streaming requests. Recommended for apps like SillyTavern that understand the modern response shape. * `https://api.nano-gpt.com/api/v1legacy/chat/completions` — legacy contract that swaps the field name to `choices[0].delta.reasoning_content` / `message.reasoning_content` for older OpenAI-compatible clients. Use this for LiteLLM’s OpenAI adapter to avoid downstream parsing errors. * `https://api.nano-gpt.com/api/v1thinking/chat/completions` — reasoning-aware models write everything into the normal `choices[0].delta.content` stream so clients that ignore reasoning fields still see the full conversation transcript. This is the preferred endpoint for JanitorAI, which needs the website host: `https://nano-gpt.com/api/v1thinking/chat/completions`. ### Streaming payload format Server-Sent Event (SSE) streams emit the answer in `choices[0].delta.content` and the thought process in `choices[0].delta.reasoning` (plus optional `delta.reasoning_details`). Reasoning deltas are dispatched before or alongside regular content, letting you render both panes in real-time. ```text theme={null} data: { "choices": [{ "delta": { "reasoning": "Assessing possible tool options…" } }] } data: { "choices": [{ "delta": { "content": "Let me walk you through the solution." } }] } ``` Streaming responses don't repeat these values at the end, so collect `delta.content` and `delta.reasoning` as they arrive. Non-streaming requests return the assistant reply in `choices[0].message.content` and the reasoning in `choices[0].message.reasoning` (plus `reasoning_details` when available). ### Showing or hiding reasoning Send `reasoning: { "exclude": true }` to strip the reasoning payload from both streaming deltas and the final message. With this flag set, `delta.reasoning` and `message.reasoning` are omitted entirely. ```bash theme={null} curl -X POST https://api.nano-gpt.com/api/v1/chat/completions \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "anthropic/claude-opus-4.6", "messages": [{"role": "user", "content": "What is 2+2?"}], "reasoning": {"exclude": true} }' ``` **Without reasoning.exclude**: ```json theme={null} { "choices": [{ "message": { "content": "The answer is 4.", "reasoning": "The user is asking for a simple addition. 2+2 equals 4." } }] } ``` **With reasoning.exclude**: ```json theme={null} { "choices": [{ "message": { "content": "The answer is 4." } }] } ``` ### Reasoning Effort `reasoning_effort` (or `reasoning.effort`) controls reasoning depth and also acts as an explicit reasoning-mode signal. An accepted value other than `"none"` requests reasoning/thinking behavior. Available levels and defaults depend on the model. Use `"none"` to request disabled reasoning only on models that support turning it off. Always-thinking models keep their reasoning requirements; Claude Opus 5.5 rejects attempts to disable thinking. #### Parameter: `reasoning_effort` | Value | Description | | - | - | | `none` | Requests disabled reasoning where the model supports it | | `minimal` | Lowest reasoning depth | | `low` | Low reasoning depth | | `medium` | Medium reasoning depth | | `high` | High reasoning depth | | `xhigh` | Extra-high reasoning depth where supported | | `max` | Maximum effort where supported; distinct from `xhigh` on models that accept both | Claude Opus 5.5 uses adaptive thinking automatically, supports `low`, `medium`, `high`, `xhigh`, and `max`, and defaults to `high` when no effort or thinking budget is supplied. See [Opus 5.5 reasoning controls](/api-reference/miscellaneous/extended-thinking#claude-opus-5-5). `reasoning.exclude` only hides returned reasoning; it never disables thinking generation. #### Usage The `reasoning_effort` parameter can be passed at the top level: ```bash theme={null} curl -X POST https://api.nano-gpt.com/api/v1/chat/completions \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "anthropic/claude-opus-4.6", "messages": [ {"role": "user", "content": "Explain quantum entanglement step by step"} ], "reasoning_effort": "high", "max_tokens": 4096 }' ``` Alternatively, pass it as part of the `reasoning` object: ```json theme={null} { "model": "anthropic/claude-opus-4.6", "messages": [{"role": "user", "content": "Solve this complex math problem..."}], "reasoning": { "effort": "high" } } ``` Both formats are accepted. If both are present, top-level `reasoning_effort` is authoritative for Chat Completions request shaping. #### Change Effort Within a Conversation GPT-6 Astra and Claude Fable 5.1 accept `configuration_update` on empty `system` or `developer` messages. An update at the end of the request applies to the generated answer. Keep the request-level effort constant, preserve each update in later history, and do not place updates next to each other. See [inline reasoning effort updates](/api-reference/miscellaneous/inline-reasoning-effort) for examples and supported combinations. #### Combining effort with exclude `reasoning.exclude` controls output visibility only. It hides reasoning fields/blocks, but does not inherently disable reasoning compute. If an effort level is set to a non-`none` value, reasoning can still run while hidden. ```json theme={null} { "model": "anthropic/claude-opus-4.6", "messages": [{"role": "user", "content": "..."}], "reasoning": { "effort": "high", "exclude": true } } ``` ### Model suffix: reasoning effort Clients that do not expose reasoning controls for custom-provider models can set an effort in the model ID, for example `openai/gpt-latest:reasoning-effort/high`. Supported suffix values are `none`, `low`, `medium`, `high`, `xhigh`, and `max`. NanoGPT strips the suffix before model lookup and uses it as the default `reasoning_effort`. Explicit body generation settings take precedence. These IDs are not additional model-list entries; enter them manually in your client. Effort support remains model/provider-specific. ```json theme={null} { "model": "openai/gpt-latest:reasoning-effort/high", "messages": [{ "role": "user", "content": "Analyze this design." }], "reasoning": { "exclude": true } } ``` The `:reasoning-effort/high` example requests high effort while hiding reasoning output. Use `openai/gpt-latest:reasoning-effort/none` to request disabled reasoning, equivalent to the base model with `reasoning_effort: "none"`. This is different from `:reasoning-exclude`, which only hides reasoning output. Models that require reasoning keep their existing restrictions. Explicit body generation settings, including enabled thinking, take precedence over the `none` suffix. See [Reasoning Effort Suffixes](/api-reference/miscellaneous/model-suffixes#reasoning-effort-suffixes) for precedence, suffix composition, and Responses/Messages equivalents. ### Model suffix: `:reasoning-exclude` You can toggle the filter without altering your JSON body by appending `:reasoning-exclude` to the `model` name. * Equivalent to sending `{ "reasoning": { "exclude": true } }` * Only the `:reasoning-exclude` suffix is stripped before the request is routed; other suffixes remain active * Works for streaming and non-streaming responses on both Chat Completions and Text Completions ```json theme={null} { "model": "anthropic/claude-opus-4.6:reasoning-exclude", "messages": [{ "role": "user", "content": "What is 2+2?" }] } ``` #### Combine with other suffixes `:reasoning-exclude` composes safely with the other routing suffixes you already use: * `:thinking` (when that exact model ID exists). `-thinking` variants are legacy aliases for some families only. * `:online` and `:online/linkup-deep` * `:memory` and `:memory-` Examples: * `anthropic/claude-sonnet-4.6:thinking:8192:reasoning-exclude` * `openai/gpt-6.1-sol:online:reasoning-exclude` * `anthropic/claude-opus-4.6:memory-30:online/linkup-deep:reasoning-exclude` * `z-ai/glm-5.3-flash:fast:reasoning-exclude` * `z-ai/glm-5.3-flash:cheap:reasoning-exclude` ### Legacy delta field compatibility Older clients that expect the legacy `reasoning_content` field can opt in per request. Set `reasoning.delta_field` to `"reasoning_content"`, or use the top-level shorthands `reasoning_delta_field` / `reasoning_content_compat` if updating nested objects is difficult. When the toggle is active, every streaming and non-streaming response exposes `reasoning_content` instead of `reasoning`, and the modern key is omitted. The compatibility pass is skipped if `reasoning.exclude` is `true`, because no reasoning payload is emitted. If you cannot change the request payload, target `https://api.nano-gpt.com/api/v1legacy/chat/completions` instead—the legacy endpoint keeps `reasoning_content` without extra flags. LiteLLM’s OpenAI adapter should point here to maintain compatibility. For clients that ignore reasoning-specific fields entirely, use `https://api.nano-gpt.com/api/v1thinking/chat/completions` so the full text appears in the standard content stream; this is the correct choice for JanitorAI, at `https://nano-gpt.com/api/v1thinking/chat/completions` because JanitorAI's app can't reach the direct API host. ```json theme={null} { "model": "openai/gpt-6.1-sol", "messages": [...], "reasoning": { "delta_field": "reasoning_content" } } ``` #### Notes and limitations * GPU-TEE models (`phala/*`) require byte-for-byte SSE passthrough for signature verification. For those models, streaming cannot be filtered; the suffix has no effect on the streaming bytes. * When assistant content is an array (e.g., vision/text parts), only text parts are filtered; images and tool/metadata content are untouched. ## Service tiers (Flex and Fast/Priority) Set `service_tier` to request a non-default capacity tier on providers that support service tiers: * `auto` or omitted: use NanoGPT's normal routing and the provider default. * `default`: request the provider's standard tier where the provider accepts an explicit default value. * `flex`: request lower-cost, variable-capacity processing where supported. * `fast`: request lower-latency, higher-priority processing where supported. * `priority`: legacy alias for `fast` on OpenAI models; compatible non-OpenAI providers may continue to use the Priority name. Before sending a tiered request, call [`GET /api/v1/models?detailed=true`](/api-reference/endpoint/models) and inspect the selected model's `supported_service_tiers` array. The basic model list intentionally omits this field for OpenAI compatibility. An empty array means the model supports only the default tier. Behavior notes: * When `service_tier` is `"flex"`, `"fast"`, or `"priority"`, NanoGPT prefers routing to providers that support the requested tier. * Service tier availability is model- and provider-specific. The detailed model API is the programmatic source of truth; [model pages](https://nano-gpt.com/models) show the same support as badges. * Not all providers support service tiers, so tiered requests may be routed differently than default requests. * Header provider overrides (like `X-Provider`) and explicit provider selection are honored for pricing and x402 estimates. * Provider-native web search can force routing; tier pricing follows that routing. * If you explicitly force a provider that does not support service tiers, the requested tier may be ignored by the upstream provider, or routing and pricing may differ from the default route. Billing note: * Flex requests are billed at flex rates where applicable. * Fast/Priority requests are billed at the applicable higher-priority rate. * High-context pricing may also apply for models and providers with separate high-context SKUs, such as `es2k` pricing for GPT-5.5/GPT-5.4 where available. Response note: * Responses now include a top-level `service_tier` field when it is provided on the request. ### Example: flex tier ```json theme={null} { "model": "openai/gpt-5.5", "messages": [ { "role": "user", "content": "Give me a concise release note." } ], "service_tier": "flex" } ``` ### Example: fast tier ```json theme={null} { "model": "openai/gpt-5.5", "messages": [ { "role": "user", "content": "Give me a concise release note." } ], "service_tier": "fast" } ``` Use `"priority"` instead only when maintaining compatibility with an older integration or a provider route that still uses that name. ## YouTube Transcripts Automatically fetch and prepend YouTube video transcripts when the latest user message contains YouTube links. ### Defaults * Parameter: `youtube_transcripts` (boolean) * Default: `false` (opt-in) * Opt-in: set `youtube_transcripts` to `true` (string `"true"` is also accepted) to fetch transcripts * Limit: Up to 3 YouTube URLs processed per request * Higher volume: Use the standalone [`POST /api/youtube-transcribe`](/api-reference/endpoint/youtube-transcribe) endpoint for up to 10 URLs per request * Injection: Transcripts are added as a system message before your messages * Billing: \$0.01 per transcript fetched ### Enable automatic transcripts By default, YouTube links are ignored. Set `youtube_transcripts` to `true` when you want the system to retrieve and bill for transcripts. ```bash theme={null} curl -X POST https://api.nano-gpt.com/api/v1/chat/completions \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "google/gemini-3-flash-preview", "messages": [ {"role": "user", "content": "Summarize this: https://youtu.be/dQw4w9WgXcQ"} ], "youtube_transcripts": true }' ``` ### Notes * Web scraping is separate. To scrape non‑YouTube URLs, set `scraping: true`. YouTube transcripts do not require `scraping: true`. * When not requested, YouTube links are ignored for transcript fetching and are not billed. * If your balance is insufficient when enabled, the request may be blocked with a 402. ## Performance Benchmarks LinkUp achieves state-of-the-art performance on OpenAI's SimpleQA benchmark: | Provider | Score | | - | - | | LinkUp Deep Search | 90.10% | | Exa | 90.04% | | Perplexity Sonar Pro | 86% | | LinkUp Standard Search | 85% | | Perplexity Sonar | 77% | | Tavily | 73% | ## Compressed Request Bodies Request bodies may be sent gzip, deflate, or Brotli compressed by adding a `Content-Encoding` header (e.g. `Content-Encoding: gzip`). Conversation-history payloads compress roughly 5:1, which cuts upload time — and therefore time-to-first-token — on long conversations. Requires a JSON `Content-Type` and authentication; the 32 MiB body limit on `https://api.nano-gpt.com` applies to both the compressed and decompressed body. `https://nano-gpt.com` has an edge limit of about 4.5 MB per request, compressed or not; use `https://api.nano-gpt.com` for large requests. See [Compressed Request Bodies](/api-reference/miscellaneous/request-compression) for SDK-ready snippets. ## Important Notes * Web search increases input token count, which affects total cost * Models gain access to real-time information published less than a minute ago * Internet connectivity can provide up to 10x improvement in factuality * Almost all models support web search (the NanoGPT help model does not) - append a suffix or send a `web_search` object (`webSearch` and `linkup` are supported as aliases) # Check Balance Source: https://docs.nano-gpt.com/api-reference/endpoint/check-balance POST /check-balance Check the account balance # Completions Source: https://docs.nano-gpt.com/api-reference/endpoint/completion POST /v1/completions Creates a completion for the provided prompt. This endpoint is available on a best-effort basis for legacy compatibility, and performance may be less consistent than /v1/chat/completions because not all upstream providers support the legacy completions API. > [!NOTE] > > `POST /api/v1/completions` is available on a best-effort basis for legacy OpenAI compatibility. Performance and behavior may be less consistent than `POST /api/v1/chat/completions` because not all upstream providers support the legacy completions API. > [!NOTE] > > `POST /api/v1/completions` supports the same model suffix parser for provider routing (`:fast`, `:cheap`, etc.) and `:reasoning-exclude`, but this endpoint remains best-effort legacy compatibility. Prefer Chat Completions for new integrations. See [Model Suffixes](/api-reference/miscellaneous/model-suffixes). > [!NOTE] > > The body `provider` field accepts either the existing provider ID string or a structured routing object with fields such as `order`, `only`, `ignore`, `sort`, `max_price`, `allow_fallbacks`, and `require_parameters`. See [Provider Selection > Provider Routing Object](/api-reference/miscellaneous/provider-selection#provider-routing-object). # Deposits (Crypto + Fiat) Source: https://docs.nano-gpt.com/api-reference/endpoint/crypto-deposits POST https://nano-gpt.com/api/transaction/create/{ticker} Create deposit payment intents and track status programmatically ## Overview NanoGPT supports multiple deposit methods (crypto, stablecoins, and cards). This page documents the public endpoints you can use to: * Create a deposit payment intent * Check deposit limits * Track deposit status (polling or SSE) Deposits are credited automatically after payment confirmation. ## Automating deposits 1. Choose a payment method and create its invoice or payment window using your account API key. Check the endpoint's amount units and current limits. 2. Save the complete response, including the transaction ID, destination, amount and expiry, before sending funds. Use the specified asset and network. 3. Send the payment once. A reused address does not necessarily mean continuous monitoring; methods with payment windows require a new window for each top-up. 4. Poll the method's status endpoint until balance credit is confirmed. Payment detection or blockchain confirmation alone is not proof of credited balance. 5. On a timeout or expired window, reconcile the original request and wallet transaction before trying again. Do not resend funds merely because polling failed. Keep the transaction ID and blockchain hash for support. Retry protection, amount matching, expiry and fees differ by method. Only send an `Idempotency-Key` where the endpoint explicitly supports it. Follow `Retry-After` and polling headers, and use bounded backoff for temporary failures. ## Monitored deposits `POST /api/deposit/create` creates a network-specific payment window, separate from the invoice endpoints below. Authenticate with the same account API key. Two flows are documented: native POL on Polygon PoS, and [USDT on BNB Smart Chain](#usdt-on-bnb-smart-chain). The native POL contract: | Request or response | Native POL | | - | - | | Request | `network: "polygon"`, `token: "POL"` (`POLYGON` is also accepted), `amount` in gross USD | | Network | Polygon PoS, chain ID `137`; native POL only | | Limits | Currently $0.10-$25,000 USD per request; check `minimumDepositUsd` in the response | | Amount to send | `quotedTokenAmount` (decimal string) or `quotedTokenAmountAtomic` (integer string, 18 decimals) | | Destination and expiry | Use the returned `address` and `expiresAt` (Unix seconds); the default window is 30 minutes | | Optional expiry | `expires_at`, a future Unix timestamp in seconds, at most 30 minutes from creation | | Status | Poll the returned `statusUrl`, or `/api/transaction/status/polygon/{txId}` with the complete ID URL-encoded | | Confirmed credit | `status: "COMPLETED"` and `balanceCredited: true`; actual USD credit is `settlement.creditedUsdExact` | Save atomic amounts as integers or strings, never floating-point numbers. For this flow, the legacy `amountCrypto` creation field contains the USD estimate, not the token quantity. The quote is not price-locked: one slightly smaller or larger transfer is valued from the amount actually received. Do not split a payment across multiple transfers. Native POL (and [USDT on BNB Smart Chain](#usdt-on-bnb-smart-chain)) supports an optional `Idempotency-Key` of 8-128 visible ASCII characters without spaces, retained for 24 hours. Use a unique key per top-up and keep the key and request unchanged on retries. A replay neither extends expiry nor authorizes another wallet transfer. If creation returns an existing pending payment or an uncertain outcome (`409`/`503`), reconcile that request before sending. Other methods do not inherit this support. Send early enough for inclusion on-chain within the window. Confirmation can continue afterward, but late arrivals are not guaranteed automatic credit. An expired status does not mean that a transfer was reversed or that no funds were sent. Contact support with the original transaction ID and hash if needed. ### USDT on BNB Smart Chain The same endpoint opens a window for USDT (BEP-20) on BNB Smart Chain. It suits server wallets and contract wallets such as a Safe: the window matches the USDT transfer to your address, whoever sends it. | Request or response | USDT on BNB Smart Chain | | - | - | | Request | `network: "bnb"`, `token: "USDT"` (uppercase), `amount` in USD | | Network | BNB Smart Chain, chain ID `56`; USDT contract `0x55d398326f99059fF775485246999027B3197955`, 18 decimals | | Limits | Up to $25,000 per window. After the quoted consolidation fee the credit must be at least $0.10; a smaller `amount` returns `400` with `requiredGrossUsd` | | Amount to send | `quotedTokenAmount` USDT (decimal string), or `quotedTokenAmountAtomic` as the `uint256` of `transfer(address,uint256)`. 1 USDT is credited as \$1 | | Destination and expiry | The returned `address` and `expiresAt` (Unix seconds); the default window is 30 minutes | | Optional expiry | `expires_at`, a future Unix timestamp in seconds, at most 30 minutes from creation | | Status | Poll the returned `statusUrl`, or `/api/transaction/status/bnb/{txId}` with the complete ID URL-encoded | | Confirmed credit | `status: "COMPLETED"` and `balanceCredited: true`; the USD credited is `settlement.creditedUsdExact` | Your address is the same every time, but it is only watched while a window is open. **Open the window first, wait for the `200` response, then broadcast the transfer.** A transfer mined before the window opened, or after it expired, is not credited automatically; contact support with the transaction hash. For a Safe, open the window just before you execute the transaction, not when you propose it. * Send one USDT transfer per window. Any amount is credited; it does not have to equal `quotedTokenAmount`. A second transfer in the same window is not credited automatically, so open a new window for the next payment. * Send USDT only. Other tokens (USDC, BNB, BUSD) are not credited by a USDT window. * One USDT window can be open per account. Creating another while one is open returns `409` with `code: "deposit_already_pending"` and the open window in `transaction`; pay into that one or wait for it to finish. Match windows by `jobId`: the address inside `txId` can differ in letter case between responses, and either form works on the status endpoint. * `Idempotency-Key` works the same way as for native POL. Keyed calls, including replays, are limited to 30 per 10 minutes per account, and every create call counts toward 30 per 10 minutes per account. Follow `Retry-After` on `429` and `503`. * `PROCESSING` means the transfer was seen and the ledger credit is on its way; keep polling. `EXPIRED` means the window closed without a credited transfer. ```bash theme={null} # 1. Open a window (amount is USD = USDT to send) curl -X POST https://nano-gpt.com/api/deposit/create \ -H "x-api-key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: topup-2026-11-17-0001" \ -d '{"network":"bnb","token":"USDT","amount":150}' # Response (abridged) # { # "txId": "0xYourAddress:6f1c...:1795392000", # "address": "0xYourAddress", # "network": "bnb", "token": "USDT", "chainId": 56, # "tokenContract": "0x55d398326f99059fF775485246999027B3197955", # "tokenDecimals": 18, # "quotedTokenAmount": "150", # "quotedTokenAmountAtomic": "150000000000000000000", # "expiresAt": 1795392000, # "statusUrl": "/api/transaction/status/bnb/0xYourAddress%3A6f1c...%3A1795392000", # "status": "PENDING" # } # 2. Send 150 USDT to "address" on BNB Smart Chain before expiresAt # 3. Poll until COMPLETED with balanceCredited: true curl "https://nano-gpt.com/api/transaction/status/bnb/0xYourAddress%3A6f1c...%3A1795392000" \ -H "x-api-key: YOUR_API_KEY" ``` For USDT, settlement credits the USDT received at \$1, minus the consolidation fee quoted for the window (`consolidationFeeUsdExact`), plus the 3% bonus for eligible deposits. `creditEstimate` itemizes this for the requested amount. ## Deposit fees and credit Review the payment quote for conversion spreads, consolidation fees and bonus eligibility. Your wallet pays any sending network fee separately. Do not treat an estimated credit as a guaranteed final amount. For native POL, settlement applies a 1% conversion spread, the current \$0.00 consolidation fee, then the 3% bonus for eligible deposits. The bonus is included with the credit for API-created deposits too. `creditEstimate` itemizes the quote; `settlement.creditedUsdExact` reports the completed ledger credit. Other methods can have different fees and settlement rules. ## Supported Payment Methods Limits vary by method and can change. Use `GET /api/transaction/limits/{ticker}` for the authoritative min/max. ### Crypto (invoice / address) | Ticker | Name | Provider | | - | - | - | | `BTC` | Bitcoin | BTCPay | | `BTC-LN` | Bitcoin Lightning | BTCPay | | `LTC` | Litecoin | BTCPay | | `LTC-MWEB` | Litecoin MWEB | BTCPay | | `XMR` | Monero | BTCPay | | `DOGE` | Dogecoin | BTCPay | | `DASH` | Dash | BTCPay | | `ZEC` | Zcash | BTCPay | | `BCH` | Bitcoin Cash | Prompt.Cash | | `BAN` | Banano | Nanswap (legacy) | | `KAS` | Kaspa | Nanswap | | `TON` | Toncoin | Nanswap | | `NEAR` | NEAR Protocol | Nanswap | | `EGLD` | MultiversX | Nanswap | | `VVV` | VVV | Nanswap | | `ZANO` | Zano | Zano proxy | | `FUSD` | Freedom Dollar | Zano proxy | ### Stablecoins and multi-chain (Daimo Pay) These methods settle as USDC and can be paid from multiple chains/wallets. | Ticker | Name | | - | - | | `USDC` | USD Coin | | `USDT` | Tether | | `ETH` | Ethereum | | `SOL` | Solana | ### Fiat (card) | Ticker | Name | Provider | | - | - | - | | `USD` | US Dollar | Stripe | | `EUR` | Euro | Stripe | | `GBP` | British Pound | Stripe | ### Nano (direct deposit) Nano deposits use a direct-send flow to your assigned Nano deposit address (no invoice creation). See: [Check Balance](/api-reference/endpoint/check-balance) and [Receive Nano](/api-reference/endpoint/receive-nano). ## Authentication The deposit creation and status endpoints require API key authentication using one of these methods: ```bash theme={null} # Method 1: Authorization header curl -H "Authorization: Bearer YOUR_API_KEY" # Method 2: x-api-key header curl -H "x-api-key: YOUR_API_KEY" ``` ## Endpoint Summary Pick the endpoint based on the payment method: * Monitored deposits (native POL on Polygon, USDT on BNB Smart Chain): `POST /api/deposit/create` (see [Monitored deposits](#monitored-deposits)) * Crypto invoice / swap deposits: `POST /api/transaction/create/{ticker}` * Daimo Pay (multi-chain): `POST /api/transaction/create/daimo/{ticker}` * Card (Stripe): `POST /api/transaction/create/usd` * Limits: `GET /api/transaction/limits/{ticker}` * Status polling: `GET /api/transaction/status/{ticker}/{txId}` * Status SSE: `GET /api/transaction/status/events?ticker={ticker}&txId={txId}` * Nano (XNO): send to `nanoDepositAddress` (from [Check Balance](/api-reference/endpoint/check-balance)); optionally call [Receive Nano](/api-reference/endpoint/receive-nano) > [card] Create Crypto Deposit > > Create an invoice / pay-in address for supported crypto tickers **ticker** `string` *required* Ticker symbol. Examples: `btc`, `btc-ln`, `ltc`, `zec`, `bch`, `kas`, `vvv`, `zano`, `fusd` **amount** `number` *required* Amount of cryptocurrency to deposit. Must be between minimum and maximum limits. ```bash cURL theme={null} curl -X POST https://nano-gpt.com/api/transaction/create/btc \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"amount": 0.001}' ``` ```javascript JavaScript theme={null} const response = await fetch('https://nano-gpt.com/api/transaction/create/btc', { method: 'POST', headers: { 'Authorization': 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json' }, body: JSON.stringify({ amount: 0.001 }) }); const deposit = await response.json(); console.log('Send BTC to:', deposit.address); ``` ```javascript BTC Lightning Example theme={null} // BTC-LN has lower minimum ($0.10) const lnResponse = await fetch('https://nano-gpt.com/api/transaction/create/btc-ln', { method: 'POST', headers: { 'Authorization': 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json' }, body: JSON.stringify({ amount: 0.00001 }) }); const lnDeposit = await lnResponse.json(); console.log('Lightning invoice:', lnDeposit.paymentLink); ``` ```json Success Response theme={null} { "txId": "abc123", "address": "bc1q...", "amount": 0.001, "status": "New", "paymentLink": "bitcoin:bc1q...?amount=0.001", "createdAt": "2026-01-19T12:00:00.000Z", "expiresAt": "2026-01-19T13:00:00.000Z" } ``` ### Response Fields **txId** `string` Unique transaction identifier for tracking **address** `string` Deposit address for sending crypto **amount** `number` Requested deposit amount **status** `string` Payment status. Common values include: `New`, `Pending`, `Processing`, `Paid`, `Completed`, `Expired`, `Failed` **paymentLink** `string` URI for wallet apps (e.g., `bitcoin:address`) **createdAt** `string` ISO timestamp of creation **expiresAt** `string` ISO timestamp when address expires > [card] Check Payment Limits > > Get minimum and maximum deposit amounts for a payment method **ticker** `string` *required* Payment method ticker symbol (for example: `btc`, `btc-ln`, `zec`, `usdc`, `sol`, `usd`) ```bash cURL theme={null} curl https://nano-gpt.com/api/transaction/limits/kas \ -H "Authorization: Bearer YOUR_API_KEY" ``` ```javascript JavaScript theme={null} const limitsResponse = await fetch('https://nano-gpt.com/api/transaction/limits/btc', { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }); const limits = await limitsResponse.json(); // Validate amount before creating deposit if (amount < limits.minimum) { throw new Error(`Minimum deposit is ${limits.minimum} BTC`); } ``` ```json Limits Response theme={null} { "minimum": 10.5, "maximum": 5250, "fiatEquivalentMinimum": 1, "fiatEquivalentMaximum": 500, "timestamp": 1705669200 } ``` > [card] Create Daimo Payment > > Create a multi-chain payment (USDC/USDT/ETH/SOL) via Daimo Pay **ticker** `string` *required* Daimo payment ticker. Common values: `usdc`, `usdt`, `eth`, `sol` **amount** `number` *required* Amount to pay. This is typically treated as a USD/USDC amount (for example, `10` for about \$10). ```bash cURL theme={null} curl -X POST https://nano-gpt.com/api/transaction/create/daimo/usdc \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"amount": 10}' ``` ```json Success Response theme={null} { "paymentId": "encrypted_payment_id" } ``` > [card] Create Card Deposit (Stripe) > > Create a Stripe Checkout session for card deposits **amount** `number` *required* Amount in the selected fiat currency (for example, `10`). ```bash cURL theme={null} curl -X POST https://nano-gpt.com/api/transaction/create/usd \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"amount": 10}' ``` ```json Success Response theme={null} { "paymentLink": "https://checkout.stripe.com/c/pay/cs_test_..." } ``` ## Status Tracking Most deposit methods can be tracked by polling a status endpoint: ```http theme={null} GET /api/transaction/status/{ticker}/{txId} ``` Some methods use provider-specific IDs (for example Stripe session IDs). The create response usually returns the correct `txId` value to use. Example: ```bash theme={null} curl "https://nano-gpt.com/api/transaction/status/btc/abc123" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ### Real-time status (SSE) Instead of polling, you can subscribe to Server-Sent Events: ```http theme={null} GET /api/transaction/status/events?ticker={ticker}&txId={txId} ``` Example: ```bash theme={null} curl -N "https://nano-gpt.com/api/transaction/status/events?ticker=btc&txId=abc123" \ -H "Authorization: Bearer YOUR_API_KEY" ``` The server may also return an `x-poll-after` header on status responses to indicate a recommended retry interval (seconds). ## Transaction Lifecycle Status values can vary slightly by payment method, but a typical lifecycle looks like: | Status | Meaning | | - | - | | `New` / `Pending` | Deposit created, awaiting payment | | `Processing` | Payment detected and being confirmed/processed | | `Paid` | Payment confirmed, crediting pending | | `Completed` | Balance credited | | `Expired` | Payment window expired (some providers can still credit late payments) | | `Failed` | Provider error or processing failure | Notes: * `BTC` deposits can take longer to reach `Completed` due to on-chain settlement/confirmations. * Some providers may accept payment after an invoice expires; in those cases the deposit can still complete. ## Payment Providers NanoGPT uses different providers per ticker: * **BTCPay**: BTC, BTC-LN, LTC, LTC-MWEB, XMR, DOGE, DASH, ZEC * **Prompt.Cash**: BCH * **Nanswap**: BAN, KAS, TON, NEAR, EGLD, VVV * **Zano proxy**: ZANO, FUSD * **Daimo Pay**: USDC, USDT, ETH, SOL (multi-chain payments settling as USDC) * **Stripe**: card deposits (USD/EUR/GBP) * **Native Nano**: XNO direct deposits to your `nanoDepositAddress` ## Pricing Endpoints These endpoints are commonly used by deposit flows and checkout UIs: * `GET /api/get-nano-price` (NANO/USD pricing) * `GET /api/get-fiat-prices` (fiat FX rates) Example: ```bash theme={null} curl "https://nano-gpt.com/api/get-nano-price" curl "https://nano-gpt.com/api/get-fiat-prices" ``` Example responses: ```json theme={null} // GET /api/get-nano-price { "pair": "NANOUSD", "latestPrice": 1.23 } ``` ```json theme={null} // GET /api/get-fiat-prices { "usdTo": { "USD": 1, "EUR": 0.92, "GBP": 0.79 }, "currencies": { "USD": "United States Dollar", "EUR": "Euro", "GBP": "British Pound" } } ``` ## Bonuses and Discounts * `BTC-LN`: Lightning deposits may include a bonus on the credited amount (if enabled). * `XNO`: Paying with Nano balance may include a usage discount (if enabled). * `USDC` via Daimo: USDC stablecoin deposits typically credit close to \$1 per 1 USDC. ## Error Handling ### HTTP Status Codes | Code | Description | | - | - | | 200 | Success | | 400 | Invalid amount, unsupported ticker, or below/above limits | | 401 | Authentication failure | | 429 | Rate limited | | 500 | Provider unavailable or internal error | ### Common Error Messages > [accordion] Amount Validation Errors > > * `"No amount specified"` - Missing amount in request body > * `"Invalid amount. Must be a positive number."` - Amount validation failed > * `"Minimum amount is X"` - Below minimum threshold > * `"Maximum amount is X"` - Above maximum threshold > [accordion] Provider Errors > > * `"Unsupported ticker"` - Ticker not supported > * `"This payment method is currently not available"` - Provider temporarily unavailable ## Rate Limits Limits vary by endpoint. Native POL creation with `Idempotency-Key`, including replays, is limited to **30 requests per 10 minutes** per account and tenant. Use status polling for known payments and follow `Retry-After` on rate-limit responses; follow `X-Poll-After` where provided for polling. ## Payment Flow **1. Create Invoice** Call `/api/transaction/create/{ticker}` with desired amount **2. Get Address** Extract `address` from response **3. Send Payment** User sends crypto to the provided address **4. Auto-Credit** Account balance automatically updated when payment confirms # Data API Source: https://docs.nano-gpt.com/api-reference/endpoint/data-api GET https://api.nano-gpt.com/api/v1/data Discover and call NanoGPT data tools through one stable endpoint family ## Overview NanoGPT exposes a unified Data API under `/api/v1/data`. It gives customers one discoverable entry point for web search, URL scraping, maps data, social data, and business enrichment. The Data API is a wrapper around the existing direct endpoints. It does not change the underlying response bodies, validation rules, billing, rate limits, async behavior, provider options, authentication, or x402 behavior unless noted here. Direct endpoints remain available for compatibility. ## Base URL ```text theme={null} https://api.nano-gpt.com/api/v1/data ``` Local development: ```text theme={null} http://localhost:3000/api/v1/data ``` ## Authentication Use the same NanoGPT API key authentication as existing API routes: ```http theme={null} Authorization: Bearer YOUR_API_KEY ``` The public accountless x402 contract is available on selected Data API paths. To request an accountless x402 quote, send the API request without `Authorization` or `x-api-key`, and include `x-x402: true`. NanoGPT will return `402 Payment Required` with available payment options. An unauthenticated request without `x-x402: true` is treated as a normal unauthenticated request and returns `401 missing_api_key`. Currently documented accountless Data API paths: * `POST /api/v1/data/web/search` * `POST /api/v1/data/url/scrape` Use `GET /api/v1/x402/endpoints` as the deployment source of truth, including Lightning L402 availability when advertised. See [Accountless x402 API Payments](/api-reference/miscellaneous/x402) for completion, replay, and polling behavior. Direct legacy routes remain available, but accountless docs prefer the public v1 data paths. Some underlying endpoints may also support browser-session flows. The Data API forwards authentication and payment-related headers to the underlying route. ## Discovery List available Data API endpoints: ```http theme={null} GET /api/v1/data ``` Alias: ```http theme={null} GET /api/v1/data/endpoints ``` The catalog response is cacheable: ```http theme={null} Cache-Control: public, max-age=300, stale-while-revalidate=3600 ``` ### Example catalog response ```json theme={null} { "object": "list", "data": [ { "id": "web.search", "object": "data.endpoint", "name": "Web Search", "description": "Search the web through NanoGPT search providers.", "category": "search", "provider": "NanoGPT", "methods": ["POST"], "endpoint": "/api/v1/data/web/search", "url": "https://api.nano-gpt.com/api/v1/data/web/search", "direct_endpoint": "/api/web", "pricing": "Usage-based; estimated from provider, depth, and partner markup.", "status": "available" } ], "meta": { "count": 20, "providers": ["Apify", "Firecrawl", "Hunter", "NanoGPT"], "categories": ["business", "maps", "scraping", "search", "social"], "dispatch": { "endpoint": "/api/v1/data", "body": { "endpoint": "web.search", "input": { "query": "latest AI news" } } } } } ``` ## Endpoint Metadata For endpoints that do not support `GET`, calling their Data API path with `GET` returns the public metadata object instead of dispatching the tool. ```http theme={null} GET /api/v1/data/web/search ``` For endpoints that do support `GET`, the request is forwarded to the underlying endpoint. ## Calling Endpoints The Data API supports path-style dispatch and body-style dispatch. ### Path-style dispatch Use a stable Data API path and send the underlying endpoint's normal input body. ```bash theme={null} curl https://api.nano-gpt.com/api/v1/data/web/search \ -H "Authorization: Bearer $NANOGPT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "query": "latest AI model releases", "depth": "standard" }' ``` Path-style dispatch is the simplest format for fixed integrations because each tool has a URL. ### Body-style dispatch Use `POST /api/v1/data` and specify the target endpoint in the request body. ```bash theme={null} curl https://api.nano-gpt.com/api/v1/data \ -H "Authorization: Bearer $NANOGPT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "endpoint": "web.search", "input": { "query": "latest AI model releases", "depth": "standard" } }' ``` The dispatch key can be `endpoint`, `id`, or `type`. Endpoint input can be provided in an `input` object: ```json theme={null} { "endpoint": "web.search", "input": { "query": "latest AI model releases" } } ``` It can also be provided directly in the dispatch body: ```json theme={null} { "endpoint": "web.search", "query": "latest AI model releases" } ``` If `input` is present, it is forwarded. If `data` is present and `input` is absent, `data` is forwarded. Otherwise, all fields except `endpoint`, `id`, `type`, `input`, and `data` are forwarded as the endpoint input. ## Request Forwarding Behavior The Data API: * Preserves request query parameters. * Preserves request headers except hop-by-hop headers such as `connection`, `content-length`, `host`, `keep-alive`, `transfer-encoding`, and `upgrade`. * Forces `Content-Type: application/json` when it forwards a JSON body. * Forwards JSON request bodies to `POST` routes. * Allows empty-body path-style `POST` requests and forwards `{}`. * Requires a valid JSON body for body-style `POST /api/v1/data`. * Adds tracking headers to dispatched responses. ## Response Headers Dispatched responses include: ```http theme={null} x-nanogpt-data-endpoint: web.search x-nanogpt-direct-endpoint: /api/web ``` These headers are exposed to browser clients through: ```http theme={null} Access-Control-Expose-Headers: x-nanogpt-data-endpoint, x-nanogpt-direct-endpoint ``` Use these headers for client-side observability, debugging, analytics, and support traces. ## Error Format Errors generated by the Data API wrapper use this shape: ```json theme={null} { "error": { "message": "Unknown data endpoint: not.real", "type": "invalid_request_error", "code": "unknown_endpoint" } } ``` Common wrapper-level errors: | Status | Code | Meaning | | - | - | - | | `400` | `invalid_json` | Request body is missing or invalid JSON where JSON is required. | | `400` | `invalid_body` | Body-style dispatch body is not an object. | | `400` | `missing_endpoint` | Body-style dispatch did not include `endpoint`, `id`, or `type`. | | `404` | `unknown_endpoint` | Endpoint id or path is not recognized. | | `405` | `method_not_allowed` | Endpoint exists but does not support the requested method. | | `500` | `unsupported_data_endpoint` | Catalog entry exists but no dispatcher implementation matched it. | Once a request is forwarded, the underlying endpoint may return its own existing error format. ## Endpoint Catalog | Endpoint ID | Data API Path | Direct Endpoint | Methods | Category | Provider | Pricing Note | | - | - | - | - | - | - | - | | `web.search` | `/api/v1/data/web/search` | `/api/web` | `POST` | search | NanoGPT | Usage-based; estimated from provider, depth, and partner markup. | | `url.scrape` | `/api/v1/data/url/scrape` | `/api/scrape-urls` | `POST` | scraping | NanoGPT | Per URL, with higher pricing for stealth mode. | | `firecrawl` | `/api/v1/data/firecrawl` | `/api/v1/firecrawl` | `POST` | scraping | Firecrawl | Credit-based Firecrawl pricing with NanoGPT markup. | | `google_maps.search` | `/api/v1/data/google-maps/search` | `/api/v1/googlemaps` | `GET`, `POST` | maps | Apify | Apify charged-event pricing with NanoGPT markup. | | `google_maps.reviews` | `/api/v1/data/google-maps/reviews` | `/api/v1/googlemaps/reviews` | `POST` | maps | Apify | Apify charged-event pricing with NanoGPT markup. | | `reddit.scrape` | `/api/v1/data/reddit` | `/api/v1/reddit` | `POST` | social | Apify | Apify charged-event pricing with NanoGPT markup. | | `linkedin.profile` | `/api/v1/data/linkedin/profile` | `/api/v1/linkedin/profile` | `POST` | business | Apify | Apify charged-event pricing with NanoGPT markup. | | `instagram.profile` | `/api/v1/data/instagram/profile` | `/api/v1/instagram/profile` | `POST` | social | Apify | Apify charged-event pricing with NanoGPT markup. | | `instagram.posts` | `/api/v1/data/instagram/posts` | `/api/v1/instagram/posts` | `POST` | social | Apify | Apify charged-event pricing with NanoGPT markup. | | `instagram.reels` | `/api/v1/data/instagram/reels` | `/api/v1/instagram/reels` | `POST` | social | Apify | Apify charged-event pricing with NanoGPT markup. | | `tiktok.scrape` | `/api/v1/data/tiktok` | `/api/v1/tiktok` | `POST` | social | Apify | Apify charged-event pricing with NanoGPT markup. | | `x.read` | `/api/v1/data/x` | `/api/v1/x` | `GET`, `POST` | social | NanoGPT | Endpoint-specific usage pricing. | | `hunter.discover` | `/api/v1/data/hunter/discover` | `/api/v1/hunter/discover` | `POST` | business | Hunter | Free. | | `hunter.domain_search` | `/api/v1/data/hunter/domain-search` | `/api/v1/hunter/domain-search` | `GET`, `POST` | business | Hunter | Hunter search-credit pricing with NanoGPT markup. | | `hunter.email_finder` | `/api/v1/data/hunter/email-finder` | `/api/v1/hunter/email-finder` | `GET`, `POST` | business | Hunter | Hunter search-credit pricing with NanoGPT markup. | | `hunter.email_verifier` | `/api/v1/data/hunter/email-verifier` | `/api/v1/hunter/email-verifier` | `GET`, `POST` | business | Hunter | Hunter verification-credit pricing with NanoGPT markup. | | `hunter.person_enrichment` | `/api/v1/data/hunter/people/find` | `/api/v1/hunter/people/find` | `GET`, `POST` | business | Hunter | Hunter enrichment-credit pricing with NanoGPT markup. | | `hunter.company_enrichment` | `/api/v1/data/hunter/companies/find` | `/api/v1/hunter/companies/find` | `GET`, `POST` | business | Hunter | Hunter enrichment-credit pricing with NanoGPT markup. | | `hunter.combined_enrichment` | `/api/v1/data/hunter/combined/find` | `/api/v1/hunter/combined/find` | `GET`, `POST` | business | Hunter | Hunter enrichment-credit pricing with NanoGPT markup. | | `hunter.email_count` | `/api/v1/data/hunter/email-count` | `/api/v1/hunter/email-count` | `GET`, `POST` | business | Hunter | Free. | ## Endpoint Aliases Body-style dispatch accepts canonical endpoint IDs and these aliases: | Alias | Resolves To | | - | - | | `googlemaps` | `google_maps.search` | | `googlemaps.search` | `google_maps.search` | | `google-maps.search` | `google_maps.search` | | `maps.search` | `google_maps.search` | | `maps.reviews` | `google_maps.reviews` | | `linkedin` | `linkedin.profile` | | `linked-in.profile` | `linkedin.profile` | | `ig.profile` | `instagram.profile` | | `ig.posts` | `instagram.posts` | | `ig.reels` | `instagram.reels` | | `twitter.read` | `x.read` | | `twitter` | `x.read` | | `x` | `x.read` | | `search` | `web.search` | | `web` | `web.search` | | `scrape` | `url.scrape` | | `urls.scrape` | `url.scrape` | | `url_scrape` | `url.scrape` | | `hunter.domain-search` | `hunter.domain_search` | | `hunter.email-finder` | `hunter.email_finder` | | `hunter.email-verifier` | `hunter.email_verifier` | | `hunter.people.find` | `hunter.person_enrichment` | | `hunter.person` | `hunter.person_enrichment` | | `hunter.company` | `hunter.company_enrichment` | | `hunter.companies.find` | `hunter.company_enrichment` | | `hunter.combined.find` | `hunter.combined_enrichment` | | `hunter.email-count` | `hunter.email_count` | The resolver also normalizes endpoint IDs by trimming slashes, accepting `api/v1/data/...`-style strings, converting path slashes to dots, and converting hyphens to underscores. ## X/Twitter Subpaths `x.read` is special. The catalog lists the base X endpoint: ```text theme={null} /api/v1/data/x ``` The dispatcher also supports dynamic X subpaths and forwards them to `/api/v1/x/...`. Examples: ```http theme={null} GET /api/v1/data/x/search?query=nanogpt POST /api/v1/data/x/search?query=nanogpt GET /api/v1/data/x/user?username=nanogpt GET /api/v1/data/x/tweet?id=1234567890 ``` For path-style `POST` requests with no body, the wrapper forwards `{}` and preserves the query string. This supports query-only X calls. ## Examples ### Web Search ```bash theme={null} curl https://api.nano-gpt.com/api/v1/data/web/search \ -H "Authorization: Bearer $NANOGPT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "query": "NanoGPT API data endpoints", "provider": "linkup", "depth": "standard", "outputType": "searchResults" }' ``` Body-style dispatch: ```bash theme={null} curl https://api.nano-gpt.com/api/v1/data \ -H "Authorization: Bearer $NANOGPT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "endpoint": "web.search", "input": { "query": "NanoGPT API data endpoints", "provider": "linkup", "depth": "standard", "outputType": "searchResults" } }' ``` ### Scrape URLs ```bash theme={null} curl https://api.nano-gpt.com/api/v1/data/url/scrape \ -H "Authorization: Bearer $NANOGPT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "urls": ["https://nano-gpt.com"], "stealthMode": false }' ``` ### Accountless x402 Data Request ```bash theme={null} curl -i https://api.nano-gpt.com/api/v1/data/web/search \ -H "Content-Type: application/json" \ -H "x-x402: true" \ -d '{ "query": "NanoGPT API data endpoints", "provider": "linkup", "depth": "standard", "outputType": "searchResults" }' ``` ```bash theme={null} curl -i https://api.nano-gpt.com/api/v1/data/url/scrape \ -H "Content-Type: application/json" \ -H "x-x402: true" \ -d '{ "urls": ["https://nano-gpt.com"], "stealthMode": false }' ``` Both examples return `402 Payment Required` with a `payment` object when accountless x402 is enabled and the request can be quoted. If you receive `401 missing_api_key` immediately, check that the initial quote request includes `x-x402: true`. Without that header, NanoGPT does not enter the x402 quote flow. ### Google Maps Search ```bash theme={null} curl https://api.nano-gpt.com/api/v1/data/google-maps/search \ -H "Authorization: Bearer $NANOGPT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "searchStringsArray": ["coffee shops in Amsterdam"], "maxCrawledPlacesPerSearch": 10 }' ``` Google Maps search also supports `GET` for the same behavior exposed by the direct `/api/v1/googlemaps` endpoint, including polling async runs when applicable. ### Hunter Domain Search ```bash theme={null} curl "https://api.nano-gpt.com/api/v1/data/hunter/domain-search?domain=example.com" \ -H "Authorization: Bearer $NANOGPT_API_KEY" ``` ```bash theme={null} curl https://api.nano-gpt.com/api/v1/data/hunter/domain-search \ -H "Authorization: Bearer $NANOGPT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "domain": "example.com" }' ``` Body-style dispatch: ```bash theme={null} curl https://api.nano-gpt.com/api/v1/data \ -H "Authorization: Bearer $NANOGPT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "endpoint": "hunter.domain_search", "input": { "domain": "example.com" } }' ``` ### X Search With Query Parameters ```bash theme={null} curl "https://api.nano-gpt.com/api/v1/data/x/search?query=nanogpt" \ -H "Authorization: Bearer $NANOGPT_API_KEY" ``` Path-style `POST` also works for query-only X calls: ```bash theme={null} curl -X POST "https://api.nano-gpt.com/api/v1/data/x/search?query=nanogpt" \ -H "Authorization: Bearer $NANOGPT_API_KEY" ``` ## Related Docs * [Direct Web Search API](/api-reference/endpoint/web-search) * [Web Scraping](/api-reference/endpoint/scrape-urls) * [Data Extraction APIs](/api-reference/endpoint/data-extraction) * [x402 Payments](/api-reference/miscellaneous/x402) # Data Extraction APIs Source: https://docs.nano-gpt.com/api-reference/endpoint/data-extraction POST https://api.nano-gpt.com/api/v1/firecrawl Public data extraction endpoints for web, maps, social, and email/domain intelligence workflows ## Overview NanoGPT exposes data extraction APIs for web, maps, social, and email/domain intelligence workflows. For new integrations that need a stable, discoverable entry point across these tools, use the unified [Data API](/api-reference/endpoint/data-api) under `/api/v1/data`. It wraps the direct endpoints documented here without changing their response bodies, billing, validation rules, async behavior, or provider-specific options. These endpoints require API key authentication. Each request estimates a maximum charge before running. Some endpoints require `maxTotalChargeUsd` when the result count is unbounded. ## Authentication Use either header: * `Authorization: Bearer YOUR_API_KEY` * `x-api-key: YOUR_API_KEY` ## Shared Billing and Runtime Behavior * Responses include returned data plus NanoGPT billing metadata. * Partial results may still be billed if the extraction job produced usable data before failing. * Result limits exist, commonly up to 5,000 returned items for social and data scrapers. * Long-running calls can take up to several minutes. * For unbounded searches, set `maxTotalChargeUsd` to cap spend. * Use `resultLimit`, `resultsLimit`, or endpoint-specific max-count fields to keep runs bounded. Typical responses include a data payload and billing metadata: ```json theme={null} { "data": [], "meta": { "nanogpt": { "costUsd": 0.05, "itemsReturned": 25 } } } ``` ## Endpoints | Data API Path | Direct Endpoint | Method | Purpose | | - | - | - | - | | `/api/v1/data/firecrawl` | `/api/v1/firecrawl` | POST | Web page scraping, site maps, and crawls. | | `/api/v1/data/google-maps/search` | `/api/v1/googlemaps` | GET, POST | Google Maps place search and detail extraction. | | `/api/v1/data/google-maps/reviews` | `/api/v1/googlemaps/reviews` | POST | Google Maps review extraction. | | `/api/v1/data/instagram/profile` | `/api/v1/instagram/profile` | POST | Instagram profile extraction. | | `/api/v1/data/instagram/posts` | `/api/v1/instagram/posts` | POST | Instagram post extraction. | | `/api/v1/data/instagram/reels` | `/api/v1/instagram/reels` | POST | Instagram Reels extraction. | | `/api/v1/data/reddit` | `/api/v1/reddit` | POST | Reddit post, comment, community, and user extraction. | | `/api/v1/data/tiktok` | `/api/v1/tiktok` | POST | TikTok hashtag, profile, search, and post extraction. | | `/api/v1/data/linkedin/profile` | `/api/v1/linkedin/profile` | POST | LinkedIn profile enrichment. | | `/api/v1/data/hunter/{path}` | `/api/v1/hunter/{path}` | GET, POST | Email/domain intelligence pass-through with path selection. | | Not in Data API catalog | `/api/v1/facebook/ads` | POST | Facebook/Meta ad library extraction. | > [!NOTE] > > The direct endpoints remain available. Use the Data API paths when you want endpoint discovery, stable public tool IDs, body-style dispatch for dynamic clients, or response headers identifying both the Data API endpoint and direct endpoint. ## Web Crawling ```text theme={null} POST https://api.nano-gpt.com/api/v1/firecrawl ``` ### Body ```json theme={null} { "operation": "scrape", "url": "https://example.com", "formats": ["markdown"], "waitForFinishSecs": 120 } ``` ### Operations * `scrape` * `map` * `crawl` ### Important Parameters | Parameter | Description | | - | - | | `url` | Required target URL. | | `operation` | Operation to run. Must be one of `scrape`, `map`, or `crawl` when provided. | | `limit` | Page or item limit for `map` and `crawl`. | | `search` | Optional search string for `map`. | | `maxReturnedPages` | Maximum pages returned for `crawl`. | | `waitForFinishSecs` | Wait time, capped at 240 seconds. | PDF parsing has max page controls when PDF parsing is enabled. ## Google Maps ```text theme={null} POST https://api.nano-gpt.com/api/v1/googlemaps ``` ### Required Input Provide at least one of: * `searchStringsArray` * `startUrls` * `placeIds` * scrape-all-places option, when supported ### Important Parameters * `maxTotalChargeUsd` * `resultLimit` * `maxCrawledPlacesPerSearch` * `scrapePlaceDetailPage` * `scrapeContacts` * `scrapeSocialMediaProfiles` * `maxReviews` * `maxImages` * filters such as category, rating, website availability, and closed-place handling when supported ## Google Maps Reviews ```text theme={null} POST https://api.nano-gpt.com/api/v1/googlemaps/reviews ``` ### Required Input Provide at least one of: * `startUrls` * `placeIds` ### Important Parameters * `maxReviews` * `reviewsSort` * `reviewsStartDate` * `maxTotalChargeUsd` * `resultLimit` > [!NOTE] > > If you use `reviewsStartDate`, sort reviews by newest first. ## Facebook Ads ```text theme={null} POST https://api.nano-gpt.com/api/v1/facebook/ads ``` ### Required Input * `startUrls`: at least one Facebook Page URL or Meta Ad Library URL. ### Important Parameters * `resultsLimit` * `activeStatus`: `active` or `inactive` * `maxTotalChargeUsd` * `resultLimit` ## Instagram Profile ```text theme={null} POST https://api.nano-gpt.com/api/v1/instagram/profile ``` ### Required Input * `username` or `usernames`: Instagram username, profile URL, or profile ID. ### Important Parameters * `includeAboutSection` * `maxTotalChargeUsd` * `resultLimit` ## Instagram Posts ```text theme={null} POST https://api.nano-gpt.com/api/v1/instagram/posts ``` ### Required Input * `username`: one or more Instagram usernames, profile URLs, or post URLs. ### Important Parameters * `resultsLimit` * `dataDetailLevel`: `basicData` or `detailedData` * `skipPinnedPosts` * `maxTotalChargeUsd` * `resultLimit` ## Reddit ```text theme={null} POST https://api.nano-gpt.com/api/v1/reddit ``` ### Required Input Provide at least one of: * `startUrls`: Reddit URLs from `reddit.com` or `redd.it` * `searches`: search terms ### Important Parameters * `maxItems` * `maxPostCount` * `maxComments` * `maxCommunities` * `maxUsers` * `searchPosts` * `searchComments` * `searchCommunities` * `searchUsers` * `maxTotalChargeUsd` * `resultLimit` ## TikTok ```text theme={null} POST https://api.nano-gpt.com/api/v1/tiktok ``` ### Required Input Provide at least one of: * `hashtags` * `profiles` * `searchQueries` * `postURLs` ### Important Parameters * `resultsPerPage` * `maxProfilesPerQuery` * `searchSection` * transcription options, if exposed * `maxTotalChargeUsd` * `resultLimit` ## Hunter Hunter endpoints provide pass-through style email/domain intelligence with NanoGPT billing. Users authenticate with NanoGPT; do not pass a separate Hunter API key. Supported examples include: * `domain-search` * `email-finder` * `email-verifier` * `discover` ### Endpoints ```text theme={null} GET https://api.nano-gpt.com/api/v1/hunter/{path} POST https://api.nano-gpt.com/api/v1/hunter/{path} GET https://api.nano-gpt.com/api/v1/hunter?endpoint=domain-search POST https://api.nano-gpt.com/api/v1/hunter ``` For `GET`, query params are forwarded except: * `api_key` * `apiKey` * `endpoint` * `path` For `POST`, JSON body params are forwarded. Use `endpoint` or `path` to select the target path. A nested `params` object is also supported. ### Response Shape ```json theme={null} { "data": {}, "meta": { "nanogpt": { "endpoint": "domain-search", "hunterSearchesBilled": 1, "hunterVerificationsBilled": 0, "hunterEnrichmentsBilled": 0, "costUsd": 0.01 } } } ``` ## Example ```bash theme={null} curl -X POST https://api.nano-gpt.com/api/v1/googlemaps \ -H "Authorization: Bearer $NANOGPT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "searchStringsArray": ["coffee shops in Amsterdam"], "resultLimit": 25, "maxTotalChargeUsd": 1.00, "scrapePlaceDetailPage": true }' ``` # Decisions Source: https://docs.nano-gpt.com/api-reference/endpoint/decisions POST /v1/decisions Typed choices, scores, and yes/no probabilities from decision models. ## Overview Decision models answer named, typed questions about the state you provide instead of generating prose: * `choice` selects one named option and returns a probability for every option. * `score` returns an expected score over an ordered rubric. * `noul` returns the probability that a yes/no statement is true. PPLX Decider v1.2, Clef and Clef Flash can also evaluate images: send up to four photos with your questions and get the same typed answers. See [Image input](#image-input). For new HTTP integrations, use the native `POST /api/v1/decisions` endpoint. If you already use the official TypeSafe SDK, point it at NanoGPT's `POST /api/v1/systemone` compatibility endpoint. Decision models are also available through NanoGPT's OpenAI-compatible Chat Completions and Responses APIs and the Anthropic-compatible Messages API. Only input tokens are billed. Browse every decision model, with current pricing, on [nano-gpt.com/models/decisions](https://nano-gpt.com/models/decisions), or list them with `GET /api/v1/decision-models`. > [!NOTE] > > Decision models work on both API hosts. The examples use the direct API host, `https://api.nano-gpt.com`; `https://nano-gpt.com` accepts the same requests. See [API Hosts](/api-reference/miscellaneous/api-hosts). > > Before using a model on either host, check that host’s `GET /api/v1/models?detailed=true&output_modalities=decisions` catalog for the model, its `supported_endpoints`, and its `decision_input` capabilities and limits. Catalogs can differ during rollouts. > [!NOTE] > > Decision models return calibrated probabilities, not generated text. Use a chat model when you need an explanation or other free-form response. ## Models | Model | Context | Images | Use | | - | - | - | - | | `typesafe/jev-1.13` | 32K | No | TypeSafe Jev 1.13, pinned for integrations that should not follow alias upgrades. | | `typesafe/jev-latest` | 32K | No | Moving alias for the latest TypeSafe Jev release. | | `liquid/d1` | 64K | No | Liquid AI's D1. | | `perplexity/pplx-decider-v1.2` | 262K | Yes | Perplexity's PPLX Decider v1.2. Supports zero data retention. | | `cloudflare/clef` | 1,800 text tokens | Yes | Cloudflare's open decision model. | | `cloudflare/clef-flash` | 1,800 text tokens | Yes | Lower-cost Clef variant. | Use `perplexity/pplx-decider-v1.2` for PPLX integrations. Requests for the retired `perplexity/pplx-decider-v1.1-27b` ID return HTTP 410 with code `model_retired`; update the model ID explicitly to use v1.2. The v1.2 price is \$0.02 per million input tokens, with free output. Clef also accepts `clef`. The System One compatibility endpoint also accepts the official SDK model names `jev-1.13` and `jev-latest`. `GET /api/v1/models` leaves decision models out, because they reject plain chat requests. List them with `GET /api/v1/decision-models`, which returns detailed entries by default (`detailed=false` for IDs only), or add `output_modalities=decisions` to `/api/v1/models` and its subscription, paid and personalized variants. Each entry has `architecture.output_modalities: ["decisions"]`, a `supported_endpoints` list, and a `decision_input` object. `decision_input.image_input` is `true` for the image-capable models, and `decision_input.image_limits` lists their limits. For Clef and Clef Flash, the 1,800-token limit covers all text in the request, including `state` text, `questions` and request overhead. Images are counted separately; see [Image input](#image-input). ## Native Decisions API ### Endpoint ```text theme={null} POST https://api.nano-gpt.com/api/v1/decisions ``` Authenticate with either `Authorization: Bearer YOUR_API_KEY` or `x-api-key: YOUR_API_KEY`. ### Example request ```bash cURL theme={null} curl https://api.nano-gpt.com/api/v1/decisions \ -H "Authorization: Bearer $NANOGPT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "typesafe/jev-1.13", "state": { "ticket": "I was charged twice and need this fixed before Friday.", "customer_tier": "business" }, "questions": { "route": { "type": "choice", "instructions": "Which team should handle this ticket?", "criteria": { "billing": "Payments, invoices, refunds, or duplicate charges", "technical": "Product behavior, bugs, or integrations", "sales": "Plans, pricing, or purchasing" } }, "urgency": { "type": "score", "instructions": "How urgent is the ticket?", "criteria": [ "No time pressure", "Can wait several days", "Needs attention within one business day", "Immediate action is required" ] }, "needs_human_review": { "type": "noul", "instructions": "Does this ticket need human review?", "criteria": { "true": "A person should review the case", "false": "Automation can safely handle the case" } } }, "user": "customer_123" }' ``` ```javascript JavaScript theme={null} const response = await fetch("https://api.nano-gpt.com/api/v1/decisions", { method: "POST", headers: { Authorization: `Bearer ${process.env.NANOGPT_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ model: "typesafe/jev-1.13", state: { ticket: "I was charged twice and need this fixed before Friday.", customer_tier: "business", }, questions: { route: { type: "choice", instructions: "Which team should handle this ticket?", criteria: { billing: "Payments, invoices, refunds, or duplicate charges", technical: "Product behavior, bugs, or integrations", sales: "Plans, pricing, or purchasing", }, }, urgency: { type: "score", instructions: "How urgent is the ticket?", criteria: [ "No time pressure", "Can wait several days", "Needs attention within one business day", "Immediate action is required", ], }, needs_human_review: { type: "noul", instructions: "Does this ticket need human review?", criteria: { true: "A person should review the case", false: "Automation can safely handle the case", }, }, }, user: "customer_123", }), }); if (!response.ok) throw new Error(await response.text()); const decision = await response.json(); console.log(decision.answers); ``` ```python Python theme={null} import os import requests response = requests.post( "https://api.nano-gpt.com/api/v1/decisions", headers={ "Authorization": f"Bearer {os.environ['NANOGPT_API_KEY']}", "Content-Type": "application/json", }, json={ "model": "typesafe/jev-1.13", "state": { "ticket": "I was charged twice and need this fixed before Friday.", "customer_tier": "business", }, "questions": { "route": { "type": "choice", "instructions": "Which team should handle this ticket?", "criteria": { "billing": "Payments, invoices, refunds, or duplicate charges", "technical": "Product behavior, bugs, or integrations", "sales": "Plans, pricing, or purchasing", }, }, "urgency": { "type": "score", "instructions": "How urgent is the ticket?", "criteria": [ "No time pressure", "Can wait several days", "Needs attention within one business day", "Immediate action is required", ], }, "needs_human_review": { "type": "noul", "instructions": "Does this ticket need human review?", "criteria": { "true": "A person should review the case", "false": "Automation can safely handle the case", }, }, }, "user": "customer_123", }, timeout=30, ) response.raise_for_status() print(response.json()["answers"]) ``` ### Example response ```json theme={null} { "id": "decision_...", "model": "typesafe/jev-1.13", "answers": { "route": { "type": "choice", "choice": "billing", "confidence": 0.97, "probabilities": { "billing": 0.97, "technical": 0.02, "sales": 0.01 } }, "urgency": { "type": "score", "score": 2.63, "confidence": 0.81, "legend": { "0": "No time pressure", "1": "Can wait several days", "2": "Needs attention within one business day", "3": "Immediate action is required" }, "probabilities": { "0": 0.01, "1": 0.05, "2": 0.24, "3": 0.70 } }, "needs_human_review": { "type": "noul", "noul": 0.84 } }, "usage": { "input_tokens": 126, "output_tokens": 8, "estimated_cost": 0.000005292 } } ``` `noul` is the probability of the `true` outcome. A `score` can be fractional because it is the expected value across the returned score distribution. ### Usage and cost Every response reports `usage.input_tokens` and `usage.output_tokens`. Only input tokens are billed; output tokens are free. By default, the response is returned as soon as the answers are ready, and billing settles immediately afterwards. The charge itself is unaffected. These responses report `usage.estimated_cost`: the model's published input price for the reported input tokens, in USD. It does not include account discounts or payment-currency conversion, so your actual charge can differ. To get the exact amount charged instead, send `"include_usage": true`. The response then waits for billing to settle and reports the exact charge, in USD, as `usage.cost` instead of `usage.estimated_cost`. This adds a little latency. Your usage history always shows the exact charge. ```json theme={null} "usage": { "input_tokens": 126, "output_tokens": 8, "cost": 0.000005027 } ``` ### Declined questions A decision model can decline individual questions. On models that do this, such as GPT-6 Luna Decisions, a declined question comes back with only a `type`, and the other questions keep their answers: ```json theme={null} "answers": { "needs_human_review": { "type": "refusal" }, "route": { "type": "choice", "choice": "billing", "confidence": 0.97, "probabilities": { "billing": 0.97, "technical": 0.03 } } } ``` Check each answer's `type` before reading its value. A response with a declined question returns `200` and is charged normally. If every question is declined, the request returns `400` with the code `content_policy_violation` and isn't charged. The compatibility endpoints return a declined question the same way, inside the JSON text. The official TypeSafe JavaScript SDK returns it as is. The Python SDK drops answer types it doesn't recognize and logs a warning, so a declined question is simply missing from `answers`. ### Image input `perplexity/pplx-decider-v1.2`, `cloudflare/clef` and `cloudflare/clef-flash` accept images on the native `POST /api/v1/decisions` endpoint and the `POST /api/v1/systemone` compatibility endpoint. Use them to classify photos, score visual content, or answer yes/no questions about an image. Make `state` an array, and put each image directly in it as an `image_url` part with a base64 data URL. Plain strings in the same array add text context. The optional `image_url.detail` field accepts `auto`, `low` or `high`. ```bash cURL theme={null} IMAGE=$(base64 < return-photo.jpg | tr -d '\n') curl https://api.nano-gpt.com/api/v1/decisions \ -H "Authorization: Bearer $NANOGPT_API_KEY" \ -H "Content-Type: application/json" \ -d @- < [!WARNING] > > The SDK's System One call is supported. The SDK's model-list method is not, because NanoGPT's `/api/v1/models` response uses the NanoGPT/OpenAI-compatible model-list shape rather than TypeSafe's model-list shape. ## OpenAI and Anthropic compatibility Use these shapes when a decision model must fit into an existing OpenAI- or Anthropic-compatible client. The answer object is returned as JSON text, so parse the returned string once. Chat Completions and Responses report `usage.estimated_cost` by default. To get the exact charge as `usage.cost`, send `"include_usage": true` or `"stream_options": {"include_usage": true}`. Messages responses always report the exact charge. ### Chat Completions ```bash theme={null} curl https://api.nano-gpt.com/api/v1/chat/completions \ -H "Authorization: Bearer $NANOGPT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "typesafe/jev-latest", "messages": [ {"role": "user", "content": "I was charged twice. Please fix this."} ], "stream": false, "response_format": { "type": "questions", "questions": { "billing": { "type": "noul", "instructions": "Is this request about billing?" } } } }' ``` Parse `choices[0].message.content` as JSON. ### Responses API ```bash theme={null} curl https://api.nano-gpt.com/api/v1/responses \ -H "Authorization: Bearer $NANOGPT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "typesafe/jev-latest", "input": "I was charged twice. Please fix this.", "stream": false, "store": false, "text": { "format": { "type": "questions", "questions": { "billing": { "type": "noul", "instructions": "Is this request about billing?" } } } } }' ``` Parse `output_text` as JSON. The same JSON text is also available in the assistant output item. ### Anthropic Messages ```bash theme={null} curl https://api.nano-gpt.com/api/v1/messages \ -H "x-api-key: $NANOGPT_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "Content-Type: application/json" \ -d '{ "model": "typesafe/jev-latest", "max_tokens": 128, "messages": [ {"role": "user", "content": "I was charged twice. Please fix this."} ], "stream": false, "output_config": { "format": { "type": "questions", "questions": { "billing": { "type": "noul", "instructions": "Is this request about billing?" } } } } }' ``` Parse `content[0].text` as JSON. `max_tokens` is accepted for Anthropic SDK compatibility but does not change the fixed typed output. ## Limitations Decision-model requests are deliberately narrower than chat generation requests: * Only non-streaming text input in `user` messages is supported on compatibility endpoints. Image input is available only on the native Decisions and System One endpoints, for PPLX Decider v1.2, Clef and Clef Flash. * System, developer, assistant, tool, audio, video, and file input is not supported. Compatibility endpoints also reject images. * Tools, sampling controls, log probabilities, and reasoning generation controls are not supported. * Output-token-limit fields are accepted where an SDK requires them, but they do not change the fixed typed output. * BYOK and accountless x402 payments are not supported. * Standard NanoGPT or `X-Provider` provider pins are not supported. Use the native Decisions `provider` object only when you need endpoint-level routing controls. Unsupported combinations return a `400` error instead of being silently ignored. # Embedding Models Source: https://docs.nano-gpt.com/api-reference/endpoint/embedding-models GET /v1/embedding-models List all available embedding models with detailed information ## Overview The `/api/v1/embedding-models` endpoint provides a comprehensive list of available embedding models with detailed information including dimensions, max dimensions, token limits, pricing, and feature support. Use this endpoint instead of hardcoding embedding model capabilities. This endpoint is cacheable. Refresh it periodically because model availability can change. ## Authentication Authentication is optional but may enable user-specific features: | Header | Format | Required | Description | | - | - | - | - | | `Authorization` | `Bearer {api_key}` | Optional | API key for authenticated access | | `x-api-key` | `{api_key}` | Optional | Alternative API key header | ## Response Format Returns a list of all available embedding models with comprehensive details: ```json theme={null} { "object": "list", "data": [ { "id": "text-embedding-3-small", "object": "model", "created": 1754480583, "owned_by": "openai", "name": "Text Embedding 3 Small", "description": "Most cost-effective OpenAI embedding model with dimension reduction support", "dimensions": 1536, "max_dimensions": 1536, "supports_dimensions": true, "max_tokens": 8191, "zero_data_retention": false, "pricing": { "per_million_tokens": 0.02, "currency": "USD" } }, { "id": "text-embedding-3-large", "object": "model", "created": 1754480583, "owned_by": "openai", "name": "Text Embedding 3 Large", "description": "Highest performance OpenAI embedding model with dimension reduction support", "dimensions": 3072, "max_dimensions": 3072, "supports_dimensions": true, "max_tokens": 8191, "zero_data_retention": false, "pricing": { "per_million_tokens": 0.13, "currency": "USD" } }, { "id": "BAAI/bge-m3", "object": "model", "created": 1754480583, "owned_by": "nanogpt", "name": "BGE M3", "description": "Multilingual embedding model with excellent performance across languages", "dimensions": 1024, "max_dimensions": 1024, "supports_dimensions": false, "max_tokens": 8192, "zero_data_retention": true, "pricing": { "per_million_tokens": 0.01, "currency": "USD" } } // ... more models ] } ``` ## Field Descriptions | Field | Type | Description | | - | - | - | | `id` | string | Unique model identifier to use in embedding requests | | `object` | string | Always "model" for OpenAI compatibility | | `created` | number | Unix timestamp of response creation | | `owned_by` | string | `openai` for OpenAI models, otherwise `nanogpt` | | `name` | string | Human-readable model name | | `description` | string | Detailed model description and use cases | | `dimensions` | number | Default embedding vector dimensions | | `max_dimensions` | number | Maximum embedding vector dimensions supported | | `supports_dimensions` | boolean | Whether custom dimensions are supported | | `max_tokens` | number | Maximum input tokens supported | | `zero_data_retention` | boolean | Whether the model accepts requests while ZDR-only routing is on. Those requests use only providers that declare zero data retention. | | `pricing` | object | Pricing information object | ### Pricing Object Structure | Field | Type | Description | | - | - | - | | `per_million_tokens` | number | Cost per million tokens in USD | | `currency` | string | Always "USD" | ## Model Categories ### OpenAI Models High-quality embeddings with dimension reduction support: * `text-embedding-3-small` - Balance of cost and performance * `text-embedding-3-large` - Maximum accuracy * `text-embedding-ada-002` - Legacy model ### Multilingual Models Support for multiple languages: * `BAAI/bge-m3` - Excellent multilingual support ### Language-Specific Models Optimized for specific languages: * English: `BAAI/bge-base-en-v1.5`, `BAAI/bge-large-en-v1.5` ### Specialized Models Domain-specific embeddings: * `Qwen/Qwen3-Embedding-0.6B` - Efficient with dimension reduction * `Qwen/Qwen3-Embedding-4B` - Higher quality Qwen embeddings * `Qwen/Qwen3-Embedding-8B` - Long-context Qwen embeddings * `gemini-embedding-001` - Gemini embeddings ## Usage Examples ### Basic Request ```bash theme={null} curl "https://api.nano-gpt.com/api/v1/embedding-models" ``` ### With Authentication ```bash theme={null} curl "https://api.nano-gpt.com/api/v1/embedding-models" \ -H "Authorization: Bearer your_api_key_here" ``` ### Python Example ```python theme={null} import requests # Discover available embedding models response = requests.get("https://api.nano-gpt.com/api/v1/embedding-models") models = response.json() # Display models sorted by price for model in sorted(models["data"], key=lambda x: x["pricing"]["per_million_tokens"]): print(f"{model['id']}: ${model['pricing']['per_million_tokens']}/1M tokens - {model['dimensions']} dims") ``` ### JavaScript Example ```javascript theme={null} // Discover available embedding models const response = await fetch("https://api.nano-gpt.com/api/v1/embedding-models"); const models = await response.json(); // Find models that support dimension reduction const flexibleModels = models.data.filter(m => m.supports_dimensions); console.log("Models with dimension reduction:", flexibleModels.map(m => m.id)); ``` ## Model Selection Guide | Use Case | Recommended Models | Rationale | | - | - | - | | General English text | `text-embedding-3-small` | Best price/performance ratio | | Maximum accuracy | `text-embedding-3-large` | Highest quality embeddings | | Multilingual content | `BAAI/bge-m3` | Excellent cross-language performance | | Code embeddings | `qwen/qwen3-embedding-8b` | Strong code retrieval with a 32K-token context | | Budget-conscious | `BAAI/bge-large-en-v1.5` | \$0.01/1M tokens | | Chinese content | `BAAI/bge-m3` | Strong Chinese and multilingual retrieval | | Fast similarity search | Models with `supports_dimensions: true` | Can reduce dimensions for speed | # Embeddings Source: https://docs.nano-gpt.com/api-reference/endpoint/embeddings POST /v1/embeddings Create embeddings for text using OpenAI-compatible and alternative embedding models ## Overview Create embeddings for text using OpenAI-compatible and alternative embedding models. NanoGPT supports 20+ embedding models (and this list changes over time); use `GET /api/v1/embedding-models` for the source-of-truth list. ## Available Models ### OpenAI Models * `text-embedding-3-small` - 1536 dimensions, \$0.02/1M tokens - Most cost-effective with dimension reduction support * `text-embedding-3-large` - 3072 dimensions, \$0.13/1M tokens - Highest performance with dimension reduction support * `text-embedding-ada-002` - 1536 dimensions, \$0.10/1M tokens - Legacy model ### Alternative Models **Multilingual:** * `BAAI/bge-m3` - 1024 dimensions, \$0.01/1M tokens - Multilingual support **Language-Specific:** * `BAAI/bge-base-en-v1.5` - 768 dimensions, \$0.005/1M tokens - English (base) * `BAAI/bge-large-en-v1.5` - 1024 dimensions, \$0.01/1M tokens - English optimized **Specialized:** * `Qwen/Qwen3-Embedding-0.6B` - 1024 dimensions, \$0.01/1M tokens - Supports dimension reduction * `Qwen/Qwen3-Embedding-4B` - 2560 dimensions, \$0.02/1M tokens - Supports dimension reduction * `Qwen/Qwen3-Embedding-8B` - 4096 dimensions, \$0.01/1M tokens - Supports dimension reduction * `gemini-embedding-001` - 3072 dimensions, \$0.15/1M tokens ## Request Parameters | Parameter | Type | Required | Description | | - | - | - | - | | `input` | string or array | Yes | Single text string or array of up to 2048 strings to embed | | `model` | string | Yes | ID of the embedding model to use | | `encoding_format` | string | No | Format for embeddings: `"float"` (default) or `"base64"` | | `dimensions` | integer | No | Reduce embedding dimensions (only for supported models) | | `user` | string | No | Optional identifier for tracking usage | ## Response Format ```json theme={null} { "object": "list", "data": [ { "object": "embedding", "index": 0, "embedding": [0.023, -0.012, 0.045, ...] } ], "model": "text-embedding-3-small", "usage": { "prompt_tokens": 8, "total_tokens": 8 } } ``` ## Code Examples ### Python with OpenAI SDK ```python theme={null} from openai import OpenAI # Initialize client pointing to NanoGPT client = OpenAI( api_key="YOUR_NANOGPT_API_KEY", base_url="https://api.nano-gpt.com/api/v1" ) # Create embedding response = client.embeddings.create( input="Your text to embed", model="text-embedding-3-small" ) # Access the embedding embedding = response.data[0].embedding print(f"Embedding dimensions: {len(embedding)}") ``` ### JavaScript/TypeScript ```javascript theme={null} import OpenAI from 'openai'; // Initialize client pointing to NanoGPT const openai = new OpenAI({ apiKey: 'YOUR_NANOGPT_API_KEY', baseURL: 'https://api.nano-gpt.com/api/v1' }); // Create embedding const response = await openai.embeddings.create({ input: "Your text to embed", model: "text-embedding-3-small" }); // Access the embedding const embedding = response.data[0].embedding; console.log(`Embedding dimensions: ${embedding.length}`); ``` ### cURL ```bash theme={null} curl https://api.nano-gpt.com/api/v1/embeddings \ -H "Authorization: Bearer YOUR_NANOGPT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "input": "Your text to embed", "model": "text-embedding-3-small" }' ``` ### Batch Processing ```python theme={null} # Process multiple texts in a single request texts = [ "First text to embed", "Second text to embed", "Third text to embed" ] response = client.embeddings.create( input=texts, # Pass array of strings model="text-embedding-3-small" ) # Access embeddings by index for i, data in enumerate(response.data): print(f"Text {i}: {len(data.embedding)} dimensions") ``` ### Dimension Reduction For models that support it (`text-embedding-3-small`, `text-embedding-3-large`, `Qwen/Qwen3-Embedding-0.6B`, `Qwen/Qwen3-Embedding-4B`, `Qwen/Qwen3-Embedding-8B`): ```python theme={null} # Reduce dimensions to 256 for faster similarity comparisons response = client.embeddings.create( input="Your text to embed", model="text-embedding-3-small", dimensions=256 # Reduce from 1536 to 256 ) ``` ## Use Cases ### Semantic Search ```python theme={null} import numpy as np from sklearn.metrics.pairwise import cosine_similarity # Create embeddings for your documents documents = ["Document 1 text", "Document 2 text", "Document 3 text"] doc_embeddings = [] for doc in documents: response = client.embeddings.create(input=doc, model="text-embedding-3-small") doc_embeddings.append(response.data[0].embedding) # Create embedding for search query query = "Search query text" query_response = client.embeddings.create(input=query, model="text-embedding-3-small") query_embedding = query_response.data[0].embedding # Calculate similarities similarities = cosine_similarity([query_embedding], doc_embeddings)[0] # Find most similar documents top_matches = np.argsort(similarities)[::-1][:3] for idx in top_matches: print(f"Document {idx}: {similarities[idx]:.3f} similarity") ``` ### RAG (Retrieval Augmented Generation) ```python theme={null} # 1. Embed and store your knowledge base knowledge_base = [ {"text": "Fact 1...", "embedding": None}, {"text": "Fact 2...", "embedding": None}, ] for item in knowledge_base: response = client.embeddings.create( input=item["text"], model="text-embedding-3-small" ) item["embedding"] = response.data[0].embedding # 2. For a user query, find relevant context user_query = "What is...?" query_response = client.embeddings.create( input=user_query, model="text-embedding-3-small" ) query_embedding = query_response.data[0].embedding # 3. Find most relevant facts # relevant_facts = find_similar_texts(query_embedding, knowledge_base, top_k=3) # 4. Use retrieved context with chat completion chat_response = client.chat.completions.create( model="gpt-4", messages=[ {"role": "system", "content": f"Context: {relevant_facts}"}, {"role": "user", "content": user_query} ] ) ``` ## Best Practices ### Model Selection * **General English text**: Use `text-embedding-3-small` for best price/performance * **Maximum accuracy**: Use `text-embedding-3-large` * **Multilingual**: Use `BAAI/bge-m3` or `qwen/qwen3-embedding-8b` * **Code**: Use `qwen/qwen3-embedding-8b` * **Budget-conscious**: Use BAAI models at \$0.01/1M tokens ### Performance Optimization * **Batch requests**: Send up to 2048 texts in a single request * **Use dimension reduction**: Reduce dimensions for faster similarity calculations when exact precision isn't critical * **Cache embeddings**: Store computed embeddings to avoid re-processing identical texts * **Choose appropriate models**: Don't use 3072-dimension models if 768 dimensions suffice ### Cost Optimization * **Monitor token usage**: Track the `usage` field in responses * **Use smaller models**: Start with `text-embedding-3-small` before upgrading * **Implement caching**: Avoid re-embedding identical content * **Batch processing**: Reduce API call overhead ## Rate Limits Rate limits vary by endpoint and account. See [Rate Limits](/api-reference/miscellaneous/rate-limits). ## Error Handling The API returns standard HTTP status codes and OpenAI-compatible error responses: See also: [Error Handling](/api-reference/miscellaneous/error-handling). ```json theme={null} { "error": { "message": "Invalid model specified", "type": "invalid_request_error", "param": "model", "code": null } } ``` Common error codes: * `401`: Invalid or missing API key * `400`: Invalid request parameters * `429`: Rate limit exceeded * `500`: Server error # Feedback API Source: https://docs.nano-gpt.com/api-reference/endpoint/feedback GET /v1/feedback/{id} Submit private API feedback and retrieve its status, with exact error codes and retry guidance. Use the Feedback API to report a reproducible bug, documentation issue, missing feature, or model-quality problem. Reports remain private. Submit a report when the user asks, or when a NanoGPT problem is reproducible and blocks the task. Don't report transient errors, timeouts, rate limits or insufficient balance. MCP clients get the same operations as `nanogpt_send_feedback` and `nanogpt_get_feedback` in [`@nanogpt/mcp`](https://github.com/Nano-GPT-com/nanogpt-mcp) 1.6.0 or later. | Operation | Endpoint | | - | - | | Submit a report | `POST https://api.nano-gpt.com/api/v1/feedback` | | Read its status and latest team reply | `GET https://api.nano-gpt.com/api/v1/feedback/{id}` | The `/v1/feedback` and `/v1/feedback/{id}` paths are aliases. The full request and response schemas are also available in the [OpenAPI contract](https://nano-gpt.com/openapi.json). ## Authentication and access Send a valid inference API key in `Authorization: Bearer ...` or `x-api-key`. Use the **same key that submitted the report** for retrieval. A different key, even on the same account, receives `404 feedback_not_found`. Key rotation does not transfer API access; the account owner can still use [website support](https://nano-gpt.com/support). Key expiry, revocation, account restrictions and allowed Origin rules apply. Browser cookies, management tokens, partner tokens and accountless x402 do not grant access. If both credential headers are sent, they must identify the same key. Feedback requests do not incur usage charges. To submit a report, the key's account, or the team that pays for it, must have a balance or an active subscription. Other accounts receive `403 feedback_requires_funded_account` and can use [website support](https://nano-gpt.com/support) or [website feedback](https://nano-gpt.com/feedback) instead. Reading an existing report's status works at any balance. ## Submit feedback Send uncompressed JSON, at most **16 KiB**, with an `Idempotency-Key` header. Choose a new idempotency key for each new report. Keep the key and body when retrying the same report after a network failure or temporary error. ```sh theme={null} curl -i 'https://api.nano-gpt.com/api/v1/feedback' \ -H "Authorization: Bearer $NANOGPT_API_KEY" \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: feedback-example-001' \ --data '{ "type": "documentation", "title": "Clarify a retrieval example", "description": "The example does not explain which ID to use for the status lookup." }' ``` | Field | Requirements | | - | - | | `type` | Required: `bug`, `feature_request`, `documentation`, or `model_quality`. | | `title` | Required: 4-200 characters. | | `description` | Required: 10-8,000 characters. | | `request_id` | Optional diagnostic reference, up to 200 characters. Use a captured `X-Request-ID` when available. | | `endpoint` | Optional API path such as `/api/v1/chat/completions`, up to 200 characters. | | `model` | Optional model ID, up to 200 characters. | | `expected`, `actual`, `steps` | Optional text, up to 2,000 characters each. | Unknown fields are rejected. `Idempotency-Key` must contain 8-128 ASCII letters, digits, dots, underscores, colons or hyphens, starting with a letter or digit. The OpenAPI contract specifies the full field patterns. HTTP `201` returns a receipt and a `Location` header for retrieval: ```json theme={null} { "id": "10000000-0000-4000-8000-000000000001", "object": "feedback", "status": "pending", "visibility": "private", "created_at": "2026-09-29T12:00:00.000Z" } ``` An identical retry with the same API key and idempotency key returns the original receipt, including its original `pending` status. Use GET for the current status. Changed normalized fields return `409 idempotency_conflict`. Replaying a deleted or archived report returns `410` and does not recreate it. Receipt acceptance does not promise a fix or a response deadline. ## Retrieve status Use the UUID from the submission receipt or its `Location` header. The website support ticket ID is a different identifier and cannot be used for this lookup. Send no query parameters. A GET request needs neither a body nor an `Idempotency-Key` header. ```sh theme={null} curl -i 'https://api.nano-gpt.com/api/v1/feedback/10000000-0000-4000-8000-000000000001' \ -H "Authorization: Bearer $NANOGPT_API_KEY" ``` HTTP `200` includes `type`, `title`, current `status`, `created_at`, `updated_at`, `delete_after`, and `latest_response`, alongside the receipt ID, object and visibility. `latest_response` is the latest visible team reply with `id`, `content` and `created_at`, or `null` when no reply is available. Internal notes and attachment data are excluded. Statuses are `pending`, `accepted`, `in-progress`, `done`, and `rejected`. Wait at least **five minutes** between successful polls (`Retry-After: 300`). Stop polling on `done`, `rejected`, `404`, or `410`. Closed support tickets normally expire after three days unless retention is extended through the website; `delete_after` exposes the scheduled deletion time, or is `null` when none is set. ## Retrieval error codes Use the **HTTP status and `error.code` together**. In particular, `feedback_unavailable` means permanent deletion or archiving with `410`, and a temporary failure with `503`. Do not decide whether to retry by code alone. ```json theme={null} { "error": { "type": "invalid_request_error", "code": "feedback_not_found", "message": "Feedback not found." } } ``` | HTTP status | `error.code` | Meaning and action | | - | - | - | | `400` | `invalid_request` | The ID is not a UUID v4, or query parameters were supplied. Correct the request. | | `400` | `conflicting_credentials` | `Authorization` and `x-api-key` disagree. Send one credential. | | `401` | `missing_api_key` | Supply an inference API key. | | `401` | `malformed_api_key` | Correct the API key format. | | `401` | `invalid_api_key` | The key is invalid, expired, revoked, or unsupported for feedback. Correct authentication before retrying. | | `403` | `api_key_origin_not_allowed` | The request violates the key's Origin restriction. Correct the request Origin or key policy. | | `403` | `payment_review_required` | Account API access is restricted pending review. Use website support. | | `404` | `feedback_not_found` | No report is accessible with this API key. Check the receipt ID and submitting key, then stop automatic retries. This response does not reveal whether another key owns a report. | | `410` | `feedback_unavailable` | The report was deleted or archived. Stop polling; this response does not include retry advice. | | `429` | `rate_limit_exceeded` | A feedback request quota was reached. Honor `Retry-After`. | | `429` | `authentication_rate_limited` | This credential was rejected repeatedly and is temporarily refused (per credential, not per IP). Correct the credentials and honor `Retry-After`. | | `500` or `503` | `internal_error` | Authentication encountered a server failure. Retry with bounded backoff; `Retry-After` may be absent. | | `503` | `feedback_unavailable` | A temporary feedback failure. Honor `Retry-After: 30` and retain `X-Request-ID` for support. | | `503` | `rate_limit_unavailable` | The rate-limit service could not check the request. Honor `Retry-After`. | Treat `error.message` as explanatory text that may change. Clients should tolerate new fields and codes and use the HTTP status as a fallback. ## Submission-only errors POST also uses the authentication, rate-limit, server, `404`, and `410` errors above, and can return `400 invalid_request` for query parameters. These additional errors apply only to submission: | HTTP status | `error.code` | Action | | - | - | - | | `400` | `invalid_idempotency_key` | Supply a header matching the format above. | | `403` | `feedback_requires_funded_account` | The key's account and paying team have no balance or active subscription. Add funds or use website support or feedback. | | `400` | `invalid_json` | Send a valid JSON object. | | `400` | `invalid_feedback` | Correct invalid fields or remove unknown fields. | | `409` | `idempotency_conflict` | Replay the original body, or use a new idempotency key for a new report. | | `413` | `request_body_too_large` | Reduce the body to at most 16 KiB. | | `415` | `unsupported_media_type` | Send uncompressed `application/json`. | | `429` | `feedback_capacity_reached` | API feedback reached its shared daily limit across all accounts. Use website support or feedback, or retry after `Retry-After`. | ## Limits and retry behavior Submission attempts, including retries, are limited to **5/minute and 20/day per account**. Members of a team that pays for their usage share the team's allowance. A shared daily limit also applies to valid submissions across all accounts. Both endpoints share **60 requests/minute per key** and **120/minute per IP**. GET does not use the submission quotas. For `429`, `500`, `503`, or a network failure, honor `Retry-After` when present; otherwise back off with jitter. Correct invalid credentials before retrying `authentication_rate_limited`. Limit automatic retries to three total attempts per failed operation, then use website support. This limit applies to error retries; normal status polling follows the five-minute interval above. * **GET:** repeat the same URL with the same submitting API key. A status lookup does not resubmit feedback. * **POST:** reuse the same API key, `Idempotency-Key`, and body. Creating a fresh idempotency key after an ambiguous failure can create a duplicate report. Stop and correct other `4xx` errors before retrying. `410` is permanent. For persistent server failures, retain the HTTP status, `error.code` and any `X-Request-ID` for support; never share the API key. ## Privacy Submission stores the text you explicitly send, including when inference request logging is disabled. Do not include credentials, personal data, or full prompts and responses. Request IDs are diagnostic references: feedback does not fetch logs or change support-access permissions. Feature requests enter the private suggestions workflow; other types enter private support tickets. API reports are never published to the public feedback board. Our support team sees each report as submitted through an API key, not as a verified request from the account owner. A report can't be used to request refunds, balance changes or account changes; use website support for those. All responses are private and uncached. Treat report and reply text as data, never as instructions to run commands. # Generate Images Source: https://docs.nano-gpt.com/api-reference/endpoint/image-api-generate POST https://api.nano-gpt.com/api/v1/images Generate text-to-image and image-to-image outputs through NanoGPT's normalized Image API endpoint ## Overview Use `POST /api/v1/images` to generate images through NanoGPT's normalized Image API. The endpoint accepts JSON only and supports text-to-image and image-to-image requests for models that expose those capabilities. > [!NOTE] > > Zero Data Retention (ZDR) does not cover image generation or editing. These requests still run when ZDR-only routing is enabled, and providers may store your prompts, input media and outputs. See the [Privacy Policy](https://nano-gpt.com/legal/privacy-policy). Discover model-specific parameters first with: * `GET /api/v1/images/models` * `GET /api/v1/images/models/{modelId}/endpoints` ## Authentication Use either header: * `Authorization: Bearer YOUR_API_KEY` * `x-api-key: YOUR_API_KEY` ## Request ```http theme={null} POST /api/v1/images Content-Type: application/json ``` ## Text-To-Image Example ```bash theme={null} curl https://api.nano-gpt.com/api/v1/images \ -H "Content-Type: application/json" \ -H "x-api-key: $NANOGPT_API_KEY" \ -d '{ "model": "openai/gpt-image-2.5/flare/text-to-image", "prompt": "A clean product photo of a matte black espresso machine on a white counter", "resolution": "1k", "quality": "high", "n": 1 }' ``` ## Image-To-Image Example ```json theme={null} { "model": "openai/gpt-image-2.5/flare/text-to-image", "prompt": "Make this look like a polished studio product photo", "input_references": [ { "type": "image_url", "image_url": { "url": "https://example.com/reference.png" } } ], "resolution": "1k", "quality": "high", "n": 1 } ``` ## Request Fields | Field | Type | Required | Description | | - | - | - | - | | `model` | string | Yes | Image model ID from `GET /api/v1/images/models`. | | `prompt` | string | Usually | Text prompt or edit instruction. Model requirements can vary. | | `n` | integer | No | Number of output images. Internally normalized to `nImages`; if both are supplied, `nImages` takes precedence. | | `resolution` | string | No | Output resolution when supported by the model. | | `aspect_ratio` | string | No | Output aspect ratio when supported by the model. | | `quality` | string | No | Quality tier when supported by the model. | | `output_format` | string | No | Output format when supported by the model. | | `seed` | integer | No | 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. | | `input_references` | array | No | Image references for image-to-image models. | NanoGPT exposes many model-specific parameters. Treat parameter support as discoverable through `supported_parameters`, not globally available. ## Input 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. ## Unsupported Features `stream: true` is not supported yet. Provider selection and provider passthrough are not supported yet. Non-empty `provider` objects return `unsupported_provider_options`. ## Common Errors | Code | Description | | - | - | | `missing_model` | `model` is required. | | `invalid_content_type` | `POST /api/v1/images` accepts `application/json` requests only. | | `invalid_input_references` | `input_references` must be an array of image URL strings, data URLs, or `image_url` objects. | | `conflicting_image_inputs` | Use `input_references` or legacy image input aliases, not both. | | `unsupported_stream` | `stream: true` is not supported yet. | | `unsupported_provider_options` | Provider selection and passthrough options are not supported yet. | ## Notes * Use `n` for output count. If your request also sends `nImages`, `nImages` takes precedence. * Use [Image API](/api-reference/image-generation) for the full guide and error response examples. # Get Image Model Endpoints Source: https://docs.nano-gpt.com/api-reference/endpoint/image-api-model-endpoints GET https://api.nano-gpt.com/api/v1/images/models/{modelId}/endpoints Inspect endpoint metadata, pricing, and image-input constraints for an image model ## Overview Use `GET /api/v1/images/models/{modelId}/endpoints` to inspect public endpoint metadata for a specific image model. The response includes supported parameters, public NanoGPT pricing, streaming support, and image reference constraints when the model supports image inputs. For model IDs that contain slashes, use the `endpoints` URL returned by `GET /api/v1/images/models`. ## Authentication Authentication is optional. * `Authorization: Bearer YOUR_API_KEY` * `x-api-key: YOUR_API_KEY` ## Request ```http theme={null} GET /api/v1/images/models/openai/gpt-image-2.5/flare/text-to-image/endpoints ``` ## Response ```json theme={null} { "id": "openai/gpt-image-2.5/flare/text-to-image", "endpoints": [ { "provider_name": "OpenAI", "provider_slug": "openai", "provider_tag": null, "supported_parameters": { "resolution": { "type": "enum", "values": ["1k", "2k", "4k"], "default": "1k" }, "n": { "type": "range", "min": 1, "max": 4, "default": 1 } }, "allowed_passthrough_parameters": [], "supports_streaming": false, "pricing": [ { "billable": "output_image", "unit": "image", "cost_usd": 0.153, "resolution": "1k" } ], "input_reference_constraints": { "max_items": 16, "route": { "min_width": 8, "min_height": 8, "max_bytes": 31457280, "formats": ["png", "jpeg", "webp"], "source": "route-preflight" } } } ] } ``` ## Fields | Field | Type | Description | | - | - | - | | `id` | string | Image model ID. | | `endpoints` | array | Public endpoint metadata for the model. Currently one public endpoint is returned per model. | | `provider_name` | string | Public provider display name. | | `provider_slug` | string | Public provider slug. | | `provider_tag` | string or null | Currently `null`; provider selection is not exposed on this API surface. | | `supported_parameters` | object | Machine-readable parameter metadata for this model endpoint. | | `allowed_passthrough_parameters` | array | Empty for now; provider passthrough is not supported. | | `supports_streaming` | boolean | Currently `false`. | | `pricing` | array | Public NanoGPT pricing metadata. This is not provider at-cost pricing. | | `input_reference_constraints` | object | Included when the model supports image inputs. | ## Example ```bash theme={null} curl https://api.nano-gpt.com/api/v1/images/models/openai/gpt-image-2.5/flare/text-to-image/endpoints ``` ## Notes * Provider selection, provider passthrough options, and provider-specific endpoint choice are not supported yet. * `pricing` uses public NanoGPT pricing. * Check `supported_parameters` before deciding which request controls to show. # List Image Models Source: https://docs.nano-gpt.com/api-reference/endpoint/image-api-models GET https://api.nano-gpt.com/api/v1/images/models List image models for NanoGPT's dedicated Image API ## Overview Use `GET /api/v1/images/models` to discover image models for the dedicated Image API. The response includes model IDs, capabilities, supported parameters, streaming support, and a model-specific endpoint metadata URL. Model availability and supported parameters can change. Build clients from the returned metadata instead of hardcoding model capability tables. ## Authentication Authentication is optional. * `Authorization: Bearer YOUR_API_KEY` * `x-api-key: YOUR_API_KEY` ## Response ```json theme={null} { "object": "list", "data": [ { "id": "openai/gpt-image-2.5/flare/text-to-image", "name": "GPT Image 2.5 Flare", "description": "Model description...", "created": 1760000000, "owned_by": "openai", "architecture": { "input_modalities": ["text", "image"], "output_modalities": ["image"] }, "supported_parameters": { "resolution": { "type": "enum", "values": ["1k", "2k", "4k"], "default": "1k" }, "n": { "type": "range", "min": 1, "max": 4, "default": 1 } }, "supports_streaming": false, "endpoints": "/api/v1/images/models/openai/gpt-image-2.5/flare/text-to-image/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" } } ``` ## Fields | Field | Type | Description | | - | - | - | | `id` | string | Model ID to use in `POST /api/v1/images`. | | `name` | string | Human-readable model name. | | `description` | string | Model description. | | `created` | integer | Unix timestamp for when the model was added. | | `owned_by` | string | Public owner or provider label. | | `architecture.input_modalities` | string\[] | Supported input modalities, such as `text` or `image`. | | `architecture.output_modalities` | string\[] | Supported output modalities. | | `supported_parameters` | object | Machine-readable model-specific parameter metadata. | | `supports_streaming` | boolean | Currently always `false`. | | `endpoints` | string | URL for endpoint metadata and pricing for this model. | | `capabilities` | object | Feature flags such as `image_generation`, `image_to_image`, `inpainting`, and `nsfw`. | | `category` | string | Usually `image`. | ## Example ```bash theme={null} curl https://api.nano-gpt.com/api/v1/images/models ``` ## Notes * `supported_parameters` varies by model. * Model IDs may contain slashes. Prefer the returned `endpoints` URL when fetching endpoint metadata. * Use this endpoint with [Get Image Model Endpoints](/api-reference/endpoint/image-api-model-endpoints) before sending generation requests. # Image Edits Source: https://docs.nano-gpt.com/api-reference/endpoint/image-edits POST https://api.nano-gpt.com/api/v1/images/edits OpenAI-compatible image editing endpoint with multipart and JSON inputs ## Overview Use the image edits endpoint to modify one or more input images with a text prompt. This is an OpenAI-compatible image editing endpoint. > [!NOTE] > > Zero Data Retention (ZDR) does not cover image generation or editing. These requests still run when ZDR-only routing is enabled, and providers may store your prompts, input media and outputs. See the [Privacy Policy](https://nano-gpt.com/legal/privacy-policy). GPT Image 2 remains the compatibility choice for requests that include a mask. For natural-language edits without a mask, use `openai/gpt-image-2.5/flare/edit` for the current everyday recommendation. For new JSON-only image-to-image generation flows, also consider the dedicated [Image API](/api-reference/image-generation), which uses `input_references` and `POST /api/v1/images`. Both paths are supported aliases: * `POST /api/v1/images/edit` * `POST /api/v1/images/edits` ## Authentication Use either header: * `Authorization: Bearer YOUR_API_KEY` * `x-api-key: YOUR_API_KEY` ## Accountless x402 Payment JSON image edit requests can be quoted without an account or API key on supported deployments when you explicitly opt in to the quote flow: ```bash theme={null} curl -i https://api.nano-gpt.com/api/v1/images/edits \ -H "Content-Type: application/json" \ -H "x-x402: true" \ -d '{ "model": "gpt-image-2", "prompt": "Remove the background", "imageDataUrl": "data:image/png;base64,..." }' ``` To request an accountless x402 quote, send the API request without `Authorization` or `x-api-key`, and include `x-x402: true`. NanoGPT will return `402 Payment Required` with available payment options. This endpoint supports accountless x402 payments where listed by `GET /api/v1/x402/endpoints`, including Lightning L402 when advertised. Multipart uploads require normal authentication before conversion. See [Accountless x402 API Payments](/api-reference/miscellaneous/x402) for the full flow. If you receive `401 missing_api_key` immediately, check that the initial quote request includes `x-x402: true`. Without that header, NanoGPT does not enter the x402 quote flow. ## Multipart Request Send `multipart/form-data` when uploading files. | Field | Type | Required | Description | | - | - | - | - | | `prompt` | string | Yes | Edit instruction. | | `image` | file or string | Yes\* | Input image file, image URL, or data URL. | | `image[]` | repeated file or string | Yes\* | Repeated image inputs for multi-image editing. | | `mask` | file | No | Optional mask image for inpainting-capable models. | | `model` | string | No | Image-edit-capable model. Defaults to an image-edit-capable default when omitted. | | `size` | string | No | Requested output size, when supported by the model. | | `n` | integer | No | Number of outputs, when supported by the model. | \*Provide `image` or one or more `image[]` fields. Other image-generation parameters may pass through when supported by the selected model. ```bash theme={null} curl -X POST https://api.nano-gpt.com/api/v1/images/edits \ -H "Authorization: Bearer $NANOGPT_API_KEY" \ -F model=gpt-image-2 \ -F prompt="Remove the background" \ -F image=@product.png \ -F size=1024x1024 ``` ### Multi-image Multipart ```bash theme={null} curl -X POST https://api.nano-gpt.com/api/v1/images/edit \ -H "x-api-key: $NANOGPT_API_KEY" \ -F model=gpt-image-2 \ -F prompt="Combine these references into one product image" \ -F "image[]=@reference-1.png" \ -F "image[]=@reference-2.jpg" ``` ## JSON Request Send JSON when you already have images as data URLs. ```json theme={null} { "model": "gpt-image-2", "prompt": "Remove the background", "imageDataUrl": "data:image/png;base64,...", "maskDataUrl": "data:image/png;base64,..." } ``` ### Multi-image JSON ```json theme={null} { "model": "gpt-image-2", "prompt": "Combine these references into one product image", "imageDataUrls": [ "data:image/png;base64,...", "data:image/jpeg;base64,..." ] } ``` ## Response Responses follow the same image response conventions as image generation. Depending on request parameters and model support, returned items may contain `url` or `b64_json`. ```json theme={null} { "created": 1778155200, "data": [ { "url": "https://..." } ] } ``` ## Common Errors | Code | Description | | - | - | | `missing_image_input` | `image` is required. | | `image_input_too_large` | Upload or input image is too large. | | `invalid_multipart_body` | Multipart body could not be parsed. | | `rate_limit_exceeded` | Too many image edit uploads. | ## Notes * Multipart uploads have strict size limits. * Generated URLs are temporary unless another page explicitly guarantees longer retention. * Use `GET /api/v1/image-models` to discover image-edit-capable models and supported parameters. # Image Generation (OpenAI-Compatible) Source: https://docs.nano-gpt.com/api-reference/endpoint/image-generation-openai POST /v1/images/generations Creates an image generation for the provided prompt (OpenAI-compatible). For unauthenticated accountless x402 quote requests, include x-x402: true. ## 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"`. > [!NOTE] > > Zero Data Retention (ZDR) does not cover image generation or editing. These requests still run when ZDR-only routing is enabled, and providers may store your prompts, input media and outputs. See the [Privacy Policy](https://nano-gpt.com/legal/privacy-policy). For new integrations that do not need OpenAI-compatible request shapes, use the dedicated [Image API](/api-reference/image-generation). 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 ` * 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. Set it explicitly to select the intended model; use `GET /api/v1/image-models` to discover available IDs. * `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 and 2.6 Flare and Sunburst models): * `quality` (string, optional): Model-specific quality level, for example `low`, `medium`, or `high`. GPT Image 2.5 and 2.6 also accept `xhigh` and `max`. * `output_format` (string, optional): `png`, `jpeg`, or `webp`. GPT Image 2.6 also supports animated `gif` for generation without reference images. * `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. For `gpt-image-2.6-flare` and `gpt-image-2.6-sunburst`, see [GPT Image 2.6 controls and pricing](/api-reference/image-generation#gpt-image-2-6). These models add a separate `complexity` control and bill from actual token usage; their catalog per-image estimates cover image output only. See [Supported Parameter Discovery](/api-reference/image-generation#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](/api-reference/endpoint/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 24 hours, and the stored image is deleted after about a day. Download promptly for long-term storage. ## Examples ```bash cURL (basic) theme={null} 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" }' ``` ```bash cURL (response_format: "url") theme={null} 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" }' ``` ```bash cURL (transparent background) theme={null} 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" }' ``` ```python Python (img2img) theme={null} 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](/api-reference/image-generation#supported-parameter-discovery). # Image Models Source: https://docs.nano-gpt.com/api-reference/endpoint/image-models GET https://api.nano-gpt.com/api/v1/image-models List available image generation and image editing models with capabilities and supported parameters ## Overview Use `GET /api/v1/image-models` to discover the currently available image models and their capabilities. Do not hardcode image model capability tables in your client; model availability and supported parameters can change. For new integrations using the normalized Image API, prefer [`GET /api/v1/images/models`](/api-reference/endpoint/image-api-models). That newer route returns model-specific `supported_parameters`, endpoint metadata links, and input-reference capabilities for use with [`POST /api/v1/images`](/api-reference/endpoint/image-api-generate). This endpoint is cacheable. Refresh it periodically and handle new fields as additive. ## Endpoint ```text theme={null} GET https://api.nano-gpt.com/api/v1/image-models ``` ## Authentication Authentication is optional. * `Authorization: Bearer YOUR_API_KEY` * `x-api-key: YOUR_API_KEY` ## Query Parameters | Parameter | Type | Default | Description | | - | - | - | - | | `detailed` | boolean | `true` | Include names, descriptions, pricing, capabilities, and supported parameters. | ## Response ```json theme={null} { "object": "list", "data": [ { "id": "pruna-ai/p-image/text-to-image", "object": "model", "created": 1778544000, "owned_by": "prunaai", "name": "P-Image", "description": "Fast text-to-image generation for low-cost drafts, social visuals, and rapid creative iteration.", "architecture": { "modality": "text->image", "input_modalities": ["text"], "output_modalities": ["image"] }, "pricing": { "per_image": { "1024*1024": 0.005, "1376*768": 0.005 }, "currency": "USD" }, "capabilities": { "image_generation": true, "image_to_image": false, "inpainting": false, "nsfw": false }, "supported_parameters": { "resolutions": ["1024x1024", "1376x768", "1184x896"], "max_images": 4 }, "icon_url": "/icons/PrunaAI.svg", "tags": ["text-to-image", "prunaai", "wavespeed"], "category": "image" } ], "meta": { "count": 169, "generated_at": "2026-05-14T00:00:00.000Z" } } ``` ## Supported Parameters Supported parameters vary by model. Common fields include: * `resolutions`: array of supported resolution values for this model. * `max_images`: maximum number of images that can be requested at once. * `rendering_speed`: available rendering speed values, when the model exposes speed tiers. * `fixed_image_count`: fixed output count for models that do not allow custom `n`. Use `supported_parameters.resolutions` to populate resolution or size controls. Treat the values as model-specific strings. Most image generation models use pixel dimensions such as `1024x1024`, but some models use values such as `auto`, aspect ratios, quality tiers, or scale factors. Use the model's `supported_parameters` and `capabilities` objects to decide which controls to show and which request fields to send. ## Fields | Field | Type | Description | | - | - | - | | `id` | string | Model ID to pass to image generation or image editing endpoints. | | `object` | string | Always `model`. | | `created` | integer | Unix timestamp derived from the model's added date. | | `owned_by` | string | Provider or owner identifier. | | `name` | string | Human-readable model name. | | `description` | string | Short model description. | | `architecture` | object | Modality metadata, including input and output modalities. | | `pricing` | object | USD pricing metadata. Shape can vary by model. | | `capabilities` | object | Feature flags such as `image_generation`, `image_to_image`, and `inpainting`. | | `capabilities.nsfw` | boolean | Whether the model is uncensored / NSFW-capable. | | `supported_parameters` | object | Model-specific parameters such as sizes, counts, quality settings, seeds, or image input controls. | | `supported_parameters.resolutions` | string\[] | Model-specific supported output resolution values. Usually pixel dimensions like `1024x1024`; may also be symbolic values such as `auto` or model-specific scale factors. | | `supported_parameters.max_images` | integer | Maximum number of images the model supports per request. | | `supported_parameters.rendering_speed` | string\[] | Optional list of rendering speed tiers. Present only for models that expose speed choices. | | `supported_parameters.fixed_image_count` | integer | Optional fixed output image count. Present when the model always returns a fixed number of images. | | `icon_url` | string | Optional provider icon path. | | `tags` | string\[] | Optional model tags. | | `category` | string | Model category. Usually `image`. | `supported_parameters`, including `supported_parameters.resolutions`, is included only in detailed responses. `detailed=true` is the default. If you pass `detailed=false`, each item may include only basic identifiers such as `id`, `object`, `created`, and `owned_by`. ## Example ```bash theme={null} curl "https://api.nano-gpt.com/api/v1/image-models?detailed=true" \ -H "Authorization: Bearer $NANOGPT_API_KEY" ``` ## Notes * Supported parameters vary by model. * Use this endpoint instead of hardcoding media model capabilities. * The response is cacheable, but model availability can change. * Pricing values are in USD unless otherwise documented in the response. # List Inline Batches Source: https://docs.nano-gpt.com/api-reference/endpoint/inline-batches-list GET /api/beta/batches List authenticated inline batches with filters and bidirectional cursor pagination Inline list responses contain metadata only. The `results` field is always `null`, including for completed batches. Retrieve `GET /api/beta/batches/{batch_id}` to obtain completed inline results. See the [Batch API guide](/api-reference/endpoint/batches#list-batches) for pagination examples, filter rules, and error behavior. # Create Invitation Source: https://docs.nano-gpt.com/api-reference/endpoint/invitations-create POST /invitations/create Create an invitation or referral link with an optional credit amount. ## Overview Create an invitation or referral link with an optional credit amount. Invitation links can include a fixed credit amount, while referral links always have a zero amount. ## Authentication This endpoint supports two authentication methods: * Session-based authentication (browser session cookie) * API key authentication via request headers ### API Key Headers * `x-api-key: YOUR_API_KEY` or * `Authorization: Bearer YOUR_API_KEY` ## Request ### Headers * `Content-Type: application/json` * `x-api-key: YOUR_API_KEY` (required for API key auth) ### Body | Field | Type | Required | Description | | - | - | - | - | | `type` | string | No | Either `"invitation"` or `"referralLink"`. Defaults to `"invitation"`. | | `amount` | number | No | Credit amount to include with the invitation. Must be non-negative. Ignored for referral links (always 0). | | `currency` | string | No | Currency for the amount. Required if `amount > 0`. Use `"USD"` for US dollars. | | `recipientName` | string | No | Name of the invitation recipient. | | `issuerName` | string | No | Name of the person sending the invitation. | | `issuerNote` | string | No | Personal note to include with the invitation. | ## Response ### Success (200 OK) ```json theme={null} { "insertId": "12345", "redeemCode": "ABC123XY", "url": "https://example.com/invite/ABC123XY", "type": "invitation", "amount": 10, "currency": "USD" } ``` | Field | Type | Description | | - | - | - | | `insertId` | string | Database ID of the created invitation. | | `redeemCode` | string | Unique code the recipient uses to redeem the invitation. | | `url` | string | Full URL to share with the recipient. | | `type` | string | The invitation type (`"invitation"` or `"referralLink"`). | | `amount` | number | Credit amount attached to this invitation. | | `currency` | string \| null | Currency of the amount, or `null` if amount is 0 (recipient chooses currency). | ## Errors | Status | Body | Description | | - | - | - | | 400 | `"Invalid request body"` | Request body is not valid JSON. | | 400 | `"InvalidAmount"` | The provided amount is negative. | | 400 | `"InsufficientBalance"` | Your account balance is insufficient for the specified amount. | | 401 | `"Invalid session"` | Session is missing required data. | | 401 | `"Unable to get session"` | Authentication failed. | | 500 | `"Failed to create invitation"` | Server error during invitation creation. | ## Notes * When `amount` is 0 or not provided, the `currency` in the response is `null`, allowing the recipient to choose their preferred currency upon redemption. * Referral links always have an amount of 0, regardless of what value is passed. * The `redeemCode` uses a URL-safe alphabet that avoids ambiguous characters (no 0, O, 1, l). * Ensure your account has sufficient balance before creating invitations with credit amounts. ## Examples ```bash cURL theme={null} curl -X POST https://nano-gpt.com/api/invitations/create \ -H "Content-Type: application/json" \ -H "x-api-key: YOUR_API_KEY" \ -d '{ "amount": 10, "currency": "USD", "recipientName": "Jane Doe", "issuerName": "John Smith", "issuerNote": "Welcome to the platform!" }' ``` ```bash cURL theme={null} curl -X POST https://nano-gpt.com/api/invitations/create \ -H "Content-Type: application/json" \ -H "x-api-key: YOUR_API_KEY" \ -d '{ "type": "referralLink", "issuerName": "John Smith" }' ``` ```bash cURL theme={null} curl -X POST https://nano-gpt.com/api/invitations/create \ -H "Content-Type: application/json" \ -H "x-api-key: YOUR_API_KEY" \ -d '{ "recipientName": "Jane Doe" }' ``` # Context Memory (Standalone) Source: https://docs.nano-gpt.com/api-reference/endpoint/memory POST /v1/memory Compress a conversation with Context Memory and return compressed messages and usage (no model inference) ## Overview The standalone Context Memory endpoint compresses an entire conversation into a single memory message. This endpoint does not run a model. It returns the compressed memory message and usage so you can pipe it into your own chat completion request or store it. * No model inference is performed * Pass your `messages` array and optional settings ## Authentication * `Authorization: Bearer YOUR_API_KEY` or * `x-api-key: YOUR_API_KEY` ## Request ### Headers * `Content-Type: application/json` * `Authorization: Bearer YOUR_API_KEY` or `x-api-key: YOUR_API_KEY` * `memory_expiration_days: <1..365>` (optional) — overrides body; defaults to 30 ### Body ```json theme={null} { "messages": [ { "role": "system", "content": "You are a helpful assistant." }, { "role": "user", "content": "Summarize our previous discussion and continue." } ], "expiration_days": 45, "model_context_limit": 128000 } ``` * `messages` (required): OpenAI-style messages. `user`, `assistant`, `system`, `tool`, and `function` roles are accepted. Assistant `tool_calls` are ignored during compression. * `expiration_days` (optional): 1..365; default 30. If both header and body are provided, the header takes precedence. * `model_context_limit` (optional): Context target for compression. Default 128k; values below 10k are clamped internally. ## Response ### Success (200) ```json theme={null} { "messages": [ { "role": "system", "content": "..." } ], "usage": { "prompt_tokens": 51234, "completion_tokens": 1234, "total_tokens": 52468, "prompt_tokens_details": { "cached_tokens": 4096 } } } ``` * `messages`: The single memory-compressed message array to use as your full context in a chat completion request * `usage`: Token usage. When available, `prompt_tokens_details.cached_tokens` indicates discounted cached input tokens ### Error Examples ```json 400 Bad Request theme={null} { "error": "messages must be a non-empty array" } ``` ```json 401 Unauthorized theme={null} { "error": "Invalid session" } ``` ```json 402 Payment Required theme={null} { "error": "Insufficient balance" } ``` ```json 429 Too Many Requests theme={null} { "error": "Rate limit exceeded. Please wait before sending another request." } ``` ## Pricing & Billing * Non-cached input tokens: \$5.00 / 1M * Cached input tokens: \$2.50 / 1M (when applicable) * Output tokens: \$10.00 / 1M Note: This endpoint only charges for memory compression. If you later call `/v1/chat/completions`, model costs are billed separately. ## Retention * Default retention: 30 days * Configure via body `expiration_days` or header `memory_expiration_days` * Header value takes precedence over body when both are supplied ## Examples ```javascript JavaScript theme={null} const res = await fetch('https://api.nano-gpt.com/api/v1/memory', { method: 'POST', headers: { 'Authorization': 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json', 'memory_expiration_days': '45' }, body: JSON.stringify({ messages: [ { role: 'system', content: 'You are a helpful assistant.' }, { role: 'user', content: 'Optimize our previous plan and continue.' } ] }) }); const { messages, usage } = await res.json(); // Use `messages` as the full context for a subsequent /v1/chat/completions call ``` ```python Python theme={null} import requests url = 'https://api.nano-gpt.com/api/v1/memory' headers = { 'Authorization': 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json' } data = { 'messages': [ { 'role': 'system', 'content': 'You are a helpful assistant.' }, { 'role': 'user', 'content': 'Summarize and continue.' } ], 'expiration_days': 30, 'model_context_limit': 128000 } r = requests.post(url, headers=headers, json=data) result = r.json() print(result['messages'][0]['content'][:200]) print(result['usage']) ``` ```bash cURL theme={null} curl -X POST https://api.nano-gpt.com/api/v1/memory \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -H "memory_expiration_days: 90" \ -d '{ "messages": [ {"role": "system", "content": "You are a helpful assistant."}, {"role": "user", "content": "Compress our conversation and continue."} ] }' ``` # Messages Source: https://docs.nano-gpt.com/api-reference/endpoint/messages POST /v1/messages Accepts Anthropic Messages requests, including video blocks for models that advertise video input. Authenticate with an API key using the Authorization: Bearer header or the x-api-key header. > [!NOTE] > > These examples use the direct API host, `https://api.nano-gpt.com`. It has no IPv6 address, so clients with only IPv6 should use `https://nano-gpt.com` with the same paths. See [API Hosts](/api-reference/miscellaneous/api-hosts). > [!NOTE] > > To set reasoning effort through a custom model ID, append `:reasoning-effort/high` (also `none`, `low`, `medium`, `xhigh`, or `max`). NanoGPT strips the suffix before routing and uses it as the default `output_config.effort` for enabled reasoning levels. `:reasoning-effort/none` instead supplies `thinking: { type: "disabled" }`; `output_config.effort: "none"` is not accepted. Explicit body generation settings, including enabled thinking, take precedence over `none`. The suffix does not bypass model/provider restrictions. See [Reasoning Effort Suffixes](/api-reference/miscellaneous/model-suffixes#reasoning-effort-suffixes). > [!NOTE] > > **API host:** Use `https://api.nano-gpt.com/api` as the base URL for the Anthropic SDK, which appends `/v1/messages`. For raw HTTP requests, use `https://api.nano-gpt.com/api/v1/messages`. See [API Hosts](/api-reference/miscellaneous/api-hosts). > [!NOTE] > > `/v1/messages` accepts **compressed request bodies** (`Content-Encoding: gzip`, `deflate`, or `br`) on authenticated JSON requests — useful for long conversations, where compressed uploads cut time-to-first-token. See [Compressed Request Bodies](/api-reference/miscellaneous/request-compression). ## Overview The `/v1/messages` endpoint provides full Anthropic API compatibility. Clients using the Anthropic SDK can use NanoGPT by simply changing the base URL -- no code changes required. NanoGPT accepts requests in the **Anthropic Messages** format, routes them to the requested NanoGPT model, and returns responses back in the Anthropic Messages shape. For non‑Anthropic models, NanoGPT transparently translates the request to an OpenAI-style chat format internally and then converts the response back to Anthropic Messages format. > [!NOTE] > > Decision models (Jev, Liquid D1, PPLX Decider v1.2, Clef and Clef Flash) use `output_config.format: {"type":"questions","questions":{...}}`, accept only non-streaming user text, and return the answer object as JSON text in `content[0].text`. See [Decisions](/api-reference/endpoint/decisions) for complete examples and limitations. This endpoint supports: * Text generation (streaming and non-streaming) * Multi-turn conversations * Tool use (function calling) * Vision (images), video understanding, and document/PDF processing * Extended thinking (reasoning models) * Prompt caching * Token estimates via [`POST /api/v1/messages/count_tokens`](/api-reference/endpoint/messages-count-tokens) For asynchronous Claude requests at batch token rates, use [Anthropic Message Batches](/api-reference/endpoint/batches#anthropic-message-batches). The native batch API supports create, list, retrieve, cancel, results, and delete through the official Anthropic SDK. It accepts supported Claude models, with one model per batch and a required `max_tokens` for each request; synchronous Messages model support does not imply batch support. ## Endpoint ``` POST https://api.nano-gpt.com/api/v1/messages ``` ## Authentication Use either header: * `Authorization: Bearer YOUR_API_KEY` * `x-api-key: YOUR_API_KEY` ## Request Format ### Required Fields | Field | Type | Description | | - | - | - | | `model` | string | Model identifier (any NanoGPT model, including non‑Anthropic models). Can be left out when `models` is sent. | | `max_tokens` | number | Maximum tokens to generate (must be a finite number) | | `messages` | array | Array of conversation messages | ### Optional Fields | Field | Type | Default | Description | | - | - | - | - | | `system` | string or array | -- | System prompt (string or array of text blocks) | | `stream` | boolean | `false` | Enable streaming responses | | `models` | string\[] | -- | Models to try in order if one fails before any output is sent. `model` goes first. At most 4 in total. The model that answered is billed, and so is a failed attempt its provider charged for. With two or more different models it needs an API key. See [Model fallbacks](/api-reference/miscellaneous/provider-selection#model-fallbacks). | | `provider` | string or object | -- | Provider selection controls for this request, applied as on Chat Completions. See [Provider Routing Object](/api-reference/miscellaneous/provider-selection#provider-routing-object). | | `temperature` | number | -- | Sampling temperature | | `top_p` | number | -- | Nucleus sampling parameter | | `top_k` | number | -- | Top-k sampling parameter | | `stop_sequences` | string\[] | -- | Custom stop sequences | | `tools` | array | -- | Tool definitions for function calling | | `tool_choice` | string or object | -- | Control tool selection behavior | | `disable_parallel_tool_use` | boolean | -- | Disable parallel tool calls | | `thinking` | object | -- | Enable extended thinking for supported models | | `metadata` | object | -- | Request metadata (`user` or `user_id`) | | `service_tier` | string | -- | Service tier: `"auto"`, `"default"`, `"standard"`, `"flex"`, `"fast"`, the legacy `"priority"` alias, or `"batch"` | ### Message Format Messages must have a `role` (`user` or `assistant`) and `content`: ```json theme={null} { "role": "user", "content": "Hello!" } ``` Or with structured content blocks: ```json theme={null} { "role": "user", "content": [ { "type": "text", "text": "What's in this image?" }, { "type": "image", "source": { "type": "base64", "media_type": "image/jpeg", "data": "" } } ] } ``` ### Content Block Types #### Text Block ```json theme={null} { "type": "text", "text": "Your message here" } ``` #### Image Block (for vision-capable models) ```json theme={null} { "type": "image", "source": { "type": "base64", "media_type": "image/jpeg", "data": "" } } ``` Or with URL: ```json theme={null} { "type": "image", "source": { "type": "url", "url": "https://example.com/image.jpg" } } ``` For many or large images, prefer `url` sources over `base64`. See [Image Input](/api-reference/endpoint/chat-completion#image-input) for the 32 MiB request limit on `https://api.nano-gpt.com` (compressed and decompressed) and when to send images inline. `https://nano-gpt.com` has an edge limit of about 4.5 MB per request, compressed or not; use `https://api.nano-gpt.com` for large requests. Supported media types: `image/jpeg`, `image/png`, `image/gif`, `image/webp` #### Document Block (for PDF-capable models) ```json theme={null} { "type": "document", "source": { "type": "base64", "media_type": "application/pdf", "data": "" } } ``` #### Video Block (for video-capable models) Use `type: "video"` for new integrations. Inline video bytes use an Anthropic base64 source: ```json theme={null} { "type": "video", "source": { "type": "base64", "media_type": "video/mp4", "data": "AAAA..." } } ``` For URL transport, use an HTTPS URL and declare the video MIME type: ```json theme={null} { "type": "video", "source": { "type": "url", "url": "https://cdn.example.com/clip.mp4", "media_type": "video/mp4" } } ``` A `document` compatibility block with a `video/*` source is normalized as video. A document with `application/pdf` remains a document. Public remote sources must use HTTPS; inline base64 must be valid. See the [Video Input guide](/api-reference/miscellaneous/video-input) for model discovery, limits, errors, segment behavior, and the equivalent Chat Completions and Responses shapes. #### Tool Use Block (in assistant messages) ```json theme={null} { "type": "tool_use", "id": "tool_abc123", "name": "get_weather", "input": { "city": "Paris" } } ``` #### Tool Result Block (in user messages) ```json theme={null} { "type": "tool_result", "tool_use_id": "tool_abc123", "content": "The weather in Paris is sunny, 22 C" } ``` ### Tool Definitions ```json theme={null} { "tools": [ { "name": "get_weather", "description": "Get current weather for a city", "input_schema": { "type": "object", "properties": { "city": { "type": "string", "description": "City name" } }, "required": ["city"] } } ] } ``` ### Tool Choice Options | Value | Description | | - | - | | `"auto"` | Model may use tools if appropriate | | `"none"` | Disable tool use for this request | | `"any"` | Model must use at least one tool | | `"required"` | Model must use at least one tool | | `{"type": "tool", "name": "tool_name"}` | Force use of a specific tool | ### Extended Thinking For models that support extended thinking (reasoning): ```json theme={null} { "thinking": { "type": "enabled", "budget_tokens": 8192 } } ``` Requirements: * `budget_tokens` must be >= 1024 * `budget_tokens` must be \< `max_tokens` * Model must support thinking for the exact model ID you send (check `GET /api/v1/models`) `:thinking` is model-specific and only works when that exact ID (or a documented alias) exists. `-thinking` is a legacy alias pattern for some model families only, not universal. Do not assume `-thinking` works for arbitrary model IDs. Always check `GET /api/v1/models` for exact valid IDs. If the requested model does not support thinking, NanoGPT automatically ignores/strips the `thinking` parameter and routes the request to the base model. For Chat Completions compatibility controls, `:reasoning-exclude` (or `reasoning.exclude`) only hides reasoning output; it does not force reasoning compute off. Use `reasoning_effort` / `reasoning.effort` to control reasoning depth, and set `none` to disable reasoning behavior. ## Change Effort Within a Conversation GPT-6 Astra and Claude Fable 5.1 support [inline reasoning effort updates](/api-reference/miscellaneous/inline-reasoning-effort) using an empty system message: `{"role":"system","content":[],"output_config":{"effort":"high"}}`. Set the baseline with request-level `output_config.effort` and leave it unchanged. A trailing update applies to the generated answer; preserve it before assistant output when replaying history. This Messages form requires the `system` role. ## Response Format ### Non-Streaming Response ```json theme={null} { "id": "msg_abc123", "type": "message", "role": "assistant", "model": "claude-opus-4-5-20251101", "content": [ { "type": "text", "text": "Hello! How can I help you today?" } ], "stop_reason": "end_turn", "stop_sequence": null, "usage": { "input_tokens": 10, "output_tokens": 12, "cache_creation_input_tokens": 0, "cache_read_input_tokens": 0, "cache_creation": { "ephemeral_5m_input_tokens": 0, "ephemeral_1h_input_tokens": 0 }, "service_tier": "standard" } } ``` ### Stop Reasons | Stop Reason | Description | | - | - | | `end_turn` | Natural end of response | | `max_tokens` | Hit token limit | | `stop_sequence` | Hit a custom stop sequence | | `tool_use` | Model wants to use a tool | | `content_filter` | Content was filtered | | `refusal` | The model declined for safety reasons | If an answer stops with `content_filter` or `refusal` after output has started, the request is charged for its input and the output generated so far. See [Content Policy and Empty Responses](/api-reference/miscellaneous/error-handling#content-policy-and-empty-responses). ### Streaming Response (SSE) See also: [Streaming Protocol (SSE)](/api-reference/miscellaneous/streaming-protocol). When `stream: true`, the response is Server-Sent Events with named event types: #### Event: message_start ```text theme={null} event: message_start data: {"type": "message_start", "message": {"id": "msg_abc", "type": "message", "role": "assistant", "model": "claude-opus-4-5-20251101", "content": [], "stop_reason": null, "usage": {"input_tokens": 10, "output_tokens": 0}}} ``` #### Event: content_block_start ```text theme={null} event: content_block_start data: {"type": "content_block_start", "index": 0, "content_block": {"type": "text", "text": ""}} ``` #### Event: content_block_delta ```text theme={null} event: content_block_delta data: {"type": "content_block_delta", "index": 0, "delta": {"type": "text_delta", "text": "Hello"}} ``` #### Event: content_block_stop ```text theme={null} event: content_block_stop data: {"type": "content_block_stop", "index": 0} ``` #### Event: message_delta ```text theme={null} event: message_delta data: {"type": "message_delta", "delta": {"stop_reason": "end_turn"}, "usage": {"output_tokens": 12}} ``` #### Event: message_stop ```text theme={null} event: message_stop data: {"type": "message_stop"} ``` ### Streaming Tool Use When the model uses tools during streaming: ```text theme={null} event: content_block_start data: {"type": "content_block_start", "index": 0, "content_block": {"type": "tool_use", "id": "tool_abc", "name": "get_weather", "input": {}}} event: content_block_delta data: {"type": "content_block_delta", "index": 0, "delta": {"type": "input_json_delta", "partial_json": "{\"city\":"}} event: content_block_delta data: {"type": "content_block_delta", "index": 0, "delta": {"type": "input_json_delta", "partial_json": " \"Paris\"}"}} event: content_block_stop data: {"type": "content_block_stop", "index": 0} ``` ## Supported Models ### Claude Models (Full Support) | Model | Streaming | Tools | Vision | Thinking | | - | - | - | - | - | | claude-opus-4-6 | Yes | Yes | Yes | Yes\* | | claude-opus-4-5-20251101 | Yes | Yes | Yes | Yes\* | | claude-opus-4-1-20250805 | Yes | Yes | Yes | Yes\* | | claude-sonnet-4-5-20250929 | Yes | Yes | Yes | Yes\* | \*Use only exact thinking-capable model IDs from `GET /api/v1/models`. ### Other Models (Via Compatibility Layer) The v1/messages endpoint also works with non-Anthropic models: | Model | Streaming | Tools | Vision | | - | - | - | - | | openai/gpt-6.1-sol | Yes | Yes | Yes | | google/gemini-3-flash-preview | Yes | Yes | Yes | | google/gemini-3.1-pro-preview | Yes | Yes | Yes | | zai-org/glm-4.7 | Yes | Yes | -- | See the [Models documentation](/api-reference/endpoint/models) for the full list. ## Prompt Caching For the full guide (supported models, thresholds, pricing, and usage fields), see [Prompt Caching](/api-reference/miscellaneous/prompt-caching). NanoGPT automatically applies implicit caching on providers/models that support it (including OpenAI, Gemini, and many open-source provider/model routes), with no extra request flags. Use explicit prompt-caching controls on Claude when you need deterministic cache boundaries, TTL selection, or `stickyProvider` consistency control. ### Enable via Header ``` anthropic-beta: prompt-caching-2024-07-31 ``` ### TTL Options * Default: 5-minute cache TTL * Extended: Add `extended-cache-ttl-2025-04-11` to request 1-hour TTL on Anthropic-native Claude flows ### Cache Control in Content (Explicit Claude Controls) Add `cache_control` to content blocks for explicit Claude caching: ```json theme={null} { "type": "text", "text": "This is a long system prompt...", "cache_control": { "type": "ephemeral" } } ``` ### Cache Usage in Response ```json theme={null} { "usage": { "input_tokens": 100, "output_tokens": 50, "cache_creation_input_tokens": 80, "cache_read_input_tokens": 0 } } ``` ## Error Handling For a general guide across NanoGPT APIs, see [Error Handling](/api-reference/miscellaneous/error-handling). ### Error Response Format ```json theme={null} { "type": "error", "error": { "type": "invalid_request_error", "message": "max_tokens is required", "param": "max_tokens" } } ``` ### Error Types | HTTP Status | Error Type | Description | | - | - | - | | 400 | `invalid_request_error` | Invalid request (missing fields, bad format) | | 401 | `authentication_error` | Invalid or missing API key | | 403 | `permission_error` | Insufficient permissions | | 404 | `not_found_error` | Unknown model | | 429 | `rate_limit_error` | Rate limit exceeded | | 500+ | `api_error` | Server error | All error responses include an `X-Request-ID` header for support requests. ## Headers ### Request Headers | Header | Required | Description | | - | - | - | | `Authorization` | Yes\* | Bearer token authentication | | `x-api-key` | Yes\* | Alternative API key header | | `Content-Type` | Yes | Must be `application/json` | | `anthropic-beta` | No | Enable beta features (e.g., prompt caching) | | `anthropic-version` | No | API version (accepted but not required) | \*One of `Authorization` or `x-api-key` is required. ### BYOK Headers For Bring Your Own Key: | Header | Description | | - | - | | `x-use-byok` | Set to `true` to use your own API key | | `x-byok-provider` | Provider name for your key | ## Examples ### Basic Request (cURL) ```bash theme={null} curl -X POST https://api.nano-gpt.com/api/v1/messages \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_API_KEY" \ -d '{ "model": "claude-opus-4-5-20251101", "max_tokens": 256, "messages": [ { "role": "user", "content": "Hello!" } ] }' ``` ### Streaming Request (cURL) ```bash theme={null} curl -N -X POST https://api.nano-gpt.com/api/v1/messages \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_API_KEY" \ -d '{ "model": "claude-opus-4-5-20251101", "stream": true, "max_tokens": 256, "messages": [{ "role": "user", "content": "Hello!" }] }' ``` ### With Tools (cURL) ```bash theme={null} curl -X POST https://api.nano-gpt.com/api/v1/messages \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_API_KEY" \ -d '{ "model": "claude-opus-4-5-20251101", "max_tokens": 1024, "tools": [ { "name": "get_weather", "description": "Get current weather", "input_schema": { "type": "object", "properties": { "city": { "type": "string" } }, "required": ["city"] } } ], "messages": [ { "role": "user", "content": "What is the weather in Tokyo?" } ] }' ``` ### Anthropic SDK (Node.js) ```typescript theme={null} import Anthropic from "@anthropic-ai/sdk"; const anthropic = new Anthropic({ apiKey: process.env.NANOGPT_API_KEY, baseURL: "https://api.nano-gpt.com/api" }); const message = await anthropic.messages.create({ model: "claude-opus-4-5-20251101", max_tokens: 256, messages: [ { role: "user", content: "Hello!" } ] }); console.log(message.content[0].text); ``` ### Anthropic SDK with Streaming (Node.js) ```typescript theme={null} import Anthropic from "@anthropic-ai/sdk"; const anthropic = new Anthropic({ apiKey: process.env.NANOGPT_API_KEY, baseURL: "https://api.nano-gpt.com/api" }); const stream = await anthropic.messages.stream({ model: "claude-opus-4-5-20251101", max_tokens: 256, messages: [ { role: "user", content: "Tell me a story" } ] }); for await (const event of stream) { if (event.type === "content_block_delta" && event.delta.type === "text_delta") { process.stdout.write(event.delta.text); } } ``` ### Anthropic SDK with Prompt Caching (Node.js) ```typescript theme={null} import Anthropic from "@anthropic-ai/sdk"; const anthropic = new Anthropic({ apiKey: process.env.NANOGPT_API_KEY, baseURL: "https://api.nano-gpt.com/api" }); const message = await anthropic.messages.create({ model: "claude-opus-4-5-20251101", max_tokens: 256, system: [ { type: "text", text: "You are a helpful assistant with expertise in...", cache_control: { type: "ephemeral" } } ], messages: [ { role: "user", content: "Hello!" } ] }, { headers: { "anthropic-beta": "prompt-caching-2024-07-31" } }); ``` ### Vision Example (Node.js) ```typescript theme={null} import Anthropic from "@anthropic-ai/sdk"; import fs from "fs"; const anthropic = new Anthropic({ apiKey: process.env.NANOGPT_API_KEY, baseURL: "https://api.nano-gpt.com/api" }); const imageData = fs.readFileSync("image.jpg").toString("base64"); const message = await anthropic.messages.create({ model: "claude-opus-4-5-20251101", max_tokens: 1024, messages: [ { role: "user", content: [ { type: "text", text: "What's in this image?" }, { type: "image", source: { type: "base64", media_type: "image/jpeg", data: imageData } } ] } ] }); ``` ### Python SDK ```python theme={null} import anthropic client = anthropic.Anthropic( api_key="YOUR_NANOGPT_API_KEY", base_url="https://api.nano-gpt.com/api" ) message = client.messages.create( model="claude-opus-4-5-20251101", max_tokens=256, messages=[ {"role": "user", "content": "Hello!"} ] ) print(message.content[0].text) ``` ## Limits | Limit | Value | | - | - | | Request timeout | 800 seconds | | Tool argument size | \~100 KB per tool call | | Tool definitions | Up to 1,024 tools and 1 MiB of tool JSON per request | | Image types | JPEG, PNG, GIF, WebP | ## Limitations * GPU-TEE models do not support streaming through `POST /api/v1/messages`. Use `POST /api/v1/chat/completions` if you need streaming with GPU-TEE models. ## Migration from Anthropic To migrate from Anthropic's API to NanoGPT: 1. Change the base URL: * From: `https://api.anthropic.com` * To: `https://api.nano-gpt.com/api` The full endpoint will be: `https://api.nano-gpt.com/api/v1/messages` 2. Use your NanoGPT API key instead of your Anthropic key 3. No other code changes required -- the API is fully compatible ## Service tier compatibility Anthropic-style service tiers are normalized when routing to providers that support service tiers: * `standard` → `default` * `default` → `default` * `flex` → `flex` * `fast` → higher-priority processing where supported * `priority` → legacy alias for `fast` on OpenAI models; compatible non-OpenAI providers may continue to use the Priority name * `batch` → ignored for service-tier routing Before sending a tiered request, call [`GET /api/v1/models?detailed=true`](/api-reference/endpoint/models) and inspect the selected model's `supported_service_tiers` array. The basic model list intentionally omits this field for OpenAI compatibility. An empty array means the model supports only the default tier. Flex and Fast/Priority availability is model- and provider-specific. If you explicitly force a provider that does not support service tiers, the requested tier may be ignored by the upstream provider, or routing and pricing may differ from the default route. ## Notes * The `anthropic-version` header is accepted but not required * Token usage numbers use NanoGPT's token accounting (may differ slightly from Anthropic's exact counts) * All Anthropic SDK features are supported, including streaming, tools, and caching # Messages Count Tokens Source: https://docs.nano-gpt.com/api-reference/endpoint/messages-count-tokens POST https://api.nano-gpt.com/api/v1/messages/count_tokens Anthropic-compatible token estimate endpoint for planning and cost control ## Overview Use `POST /api/v1/messages/count_tokens` to estimate the number of input tokens for an Anthropic Messages-format request. This endpoint is useful for request planning, context budgeting, and cost control. The result is an estimate and may not exactly match a provider tokenizer. ## Endpoint ```text theme={null} POST https://api.nano-gpt.com/api/v1/messages/count_tokens ``` ## Authentication Use either header: * `Authorization: Bearer YOUR_API_KEY` * `x-api-key: YOUR_API_KEY` ## Request Body ```json theme={null} { "model": "claude-3-5-sonnet", "system": "You are concise.", "messages": [ { "role": "user", "content": "Hello" } ], "tools": [], "tool_choice": null } ``` ## Supported Content The request uses Anthropic message format and supports: * text blocks * image and document-like blocks * tool use blocks * tool result blocks * `system` * `tools` * `tool_choice` ## Limits * `tools` can hold up to 1,024 tools and 1 MiB (1,048,576 bytes) of JSON. Requests over a limit return a 400 `invalid_request_error`. * A request body over 1.5 MiB returns `413`. ## Response ```json theme={null} { "input_tokens": 123 } ``` ## Example ```bash theme={null} curl -X POST https://api.nano-gpt.com/api/v1/messages/count_tokens \ -H "Authorization: Bearer $NANOGPT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "claude-3-5-sonnet", "system": "You are concise.", "messages": [ { "role": "user", "content": "Hello" } ] }' ``` ## Notes * This is an estimate for planning and cost control. * It may not exactly match a provider tokenizer. * For generation, use `POST /api/v1/messages`. # Models Source: https://docs.nano-gpt.com/api-reference/endpoint/models GET /v1/models List available models. The default response is intentionally minimal for OpenAI compatibility; use `detailed=true` for capabilities, supported service tiers, and pricing. > [!NOTE] > > These examples use the direct API host, `https://api.nano-gpt.com`. It has no IPv6 address, so clients with only IPv6 should use `https://nano-gpt.com` with the same paths. See [API Hosts](/api-reference/miscellaneous/api-hosts). ## Overview The `/api/v1/models` endpoint provides a list of available text generation models. It supports optional detailed information including capabilities, supported service tiers, and pricing data. The endpoint maintains full backwards compatibility while adding powerful new features. The default response deliberately stays close to OpenAI's minimal Models API shape. Enhanced fields such as `supported_service_tiers` are returned only when you add `?detailed=true`. For non-text model catalogs, use the dedicated catalog endpoints: * [Image models](/api-reference/endpoint/image-models) * [Video models](/api-reference/endpoint/video-models) * [Audio models](/api-reference/endpoint/audio-models) * [Embedding models](/api-reference/endpoint/embedding-models) * [Decision models](/api-reference/endpoint/decisions#models): `GET /api/v1/decision-models` Decision models answer typed questions through the [Decisions API](/api-reference/endpoint/decisions) and reject plain chat requests, so the text model lists leave them out unless you ask for them with `output_modalities`. For API-only distillation metadata and filtering, see [Distillation Policy](/api-reference/miscellaneous/distillation-policy). ## Notable Model IDs (Examples) Model availability changes frequently. Use `GET /api/v1/models` as the authoritative source of callable IDs. Examples below include canonical IDs and public moving aliases; legacy compatibility aliases are intentionally omitted. * **OpenAI**: `openai/gpt-6.1-sol`, `openai/gpt-6-astra`, `openai/gpt-latest` * **Anthropic**: `anthropic/claude-opus-5.5`, `anthropic/claude-sonnet-5.5`, `anthropic/claude-fable-5.2` * **Google Gemini**: `google/gemini-flash-latest`, `google/gemini-3.8-flash`, `google/gemini-3.1-pro-preview` * **SpaceXAI Grok**: `x-ai/grok-4.7`, `x-ai/grok-latest` * **Moonshot Kimi**: `moonshotai/kimi-k3.1-pro`, `moonshotai/kimi-k3`, `moonshotai/kimi-latest` * **Z.AI GLM**: `z-ai/glm-5.3`, `z-ai/glm-5.3:thinking`, `z-ai/glm-5.3-flash` * **Xiaomi MiMo**: `xiaomi/mimo-v2.6-pro` * **DeepSeek**: `deepseek/deepseek-v4.1-flash-1017`, `deepseek/deepseek-v4-flash-latest`, `deepseek/deepseek-latest` * **MiniMax**: `minimax/minimax-m3.1-flash`, `minimax/minimax-m3`, `minimax/minimax-latest` * **Qwen**: `qwen/qwen4-max`, `qwen/qwen3.8-max`, `qwen/qwen3-coder-next` ### Qwen 4 Max Qwen 4 Max is available as `qwen/qwen4-max` or `qwen/qwen4-max:thinking`. Both are pay-as-you-go only and are not included in subscriptions. Check the [live model catalog](https://api.nano-gpt.com/api/v1/models?detailed=true) for current pricing, capabilities and limits. ### Claude Fable Latest `anthropic/claude-fable-latest` currently resolves to `anthropic/claude-fable-5.2`. Choose a version-specific ID, such as `anthropic/claude-fable-5.1` or `anthropic/claude-fable-5.2`, to keep your model selection fixed when the alias moves. ### GPT Terra Latest `openai/gpt-terra-latest` follows GPT-6.1 Terra. It supports text and image input, tools, structured output, a 1,050,000-token context window, and up to 128,000 output tokens. Reasoning levels are `none`, `low`, `medium`, `high`, `xhigh`, and `max`; NanoGPT defaults to `medium`. Batch requests with tools must use `/v1/responses`; Chat Completions batches do not support tools for this model. Standard pricing is $1/M input, $5/M output, $0.05/M cached input, and $1.25/M cache writes. Requests above 272,000 input tokens use higher long-context rates. It is a paid model; use the [live model pricing and privacy metadata](https://api.nano-gpt.com/api/models/openai%2Fgpt-6.1-terra/providers) for the current route details. For Pro reasoning mode, choose `openai/gpt-6.1-terra-pro` explicitly. It uses the same base model and per-token rates, but performs more model work, increasing token usage, cost, and latency. The Latest alias continues to select standard Terra by default. Choose `openai/gpt-5.6-terra` or `openai/gpt-5.6-terra-pro` explicitly to retain those models and their behavior. The general chat default and the examples on this site remain GPT-6.1 Sol. ### DeepSeek Flash Latest `deepseek/deepseek-v4-flash-latest` follows the current recommended Flash snapshot, DeepSeek V4.1 Flash 1017. Append `:thinking` to enable reasoning by default; the base alias defaults to non-thinking. Both remain included in subscriptions. The current snapshot accepts text and images, with a shared 1,048,576-token context window and up to 393,216 output tokens within the remaining context. JSON object output is supported, and JSON Schema output is available on eligible routes. Zero data retention is also available on eligible routes. Output limits and supported reasoning levels depend on the selected route, so the model-wide maximum is not available on every provider. Auto prices follow the current eligible routes and can differ from the snapshot's peak/off-peak schedule. Read `pricing` and `effective_pricing` in `/api/v1/models?detailed=true` for the current Auto tariff, or the model's [provider pricing](https://api.nano-gpt.com/api/models/deepseek%2Fdeepseek-v4-flash-latest/providers) for Auto prices by privacy mode and provider-specific prices. Selecting a provider can change the price, including any applicable schedule and provider-selection markup. For a fixed checkpoint and the older price/capability contract, select `deepseek/deepseek-v4-flash-0731` explicitly instead of the moving alias. ### Kimi Latest and K3.1 Pro `moonshotai/kimi-latest` follows the newest recommended Kimi model, currently `moonshotai/kimi-k3.1-pro`. The faster, more expensive `moonshotai/kimi-k3.1-pro-highspeed` remains a separate selection. Choose `moonshotai/kimi-k3` explicitly to retain the K3 checkpoint and its pricing. K3.1 Pro supports text, image and video input, tool calling, structured output, and a shared 1,048,576-token context window. Output limits depend on the route and remaining context. Thinking is always enabled with `low`, `high`, or `max` effort; NanoGPT defaults to `max`. Hiding reasoning does not disable thinking or its token usage. Start a new conversation when switching from K3 to K3.1 Pro. K3.1 Pro currently costs $2 per million input tokens, $10 per million output tokens, and \$0.20 per million cached-input tokens. K3 Auto prices vary by route; check current pricing before switching. K3.1 Pro does not support the Batch API and is excluded from subscriber discounts. It does not inherit K3-specific discounts, and neither model is included in subscriptions. Keep explicit K3 for integrations that need its batch support. Availability, privacy options and route limits can differ; check `/api/v1/models?detailed=true` and the [provider endpoint](https://api.nano-gpt.com/api/models/moonshotai%2Fkimi-latest/providers) on your chosen API host for current information. ### MiniMax Latest and M3.1 Flash `minimax/minimax-latest` currently resolves to MiniMax M3 Thinking. This compatibility alias retains M3's request format and structured-output support; it does not automatically select MiniMax M3.1 Flash. Plain `minimax/minimax-m3` only thinks when a request [asks for it](/api-reference/miscellaneous/extended-thinking#turn-reasoning-on). Reasoning isn't guaranteed on MiniMax M3 Thinking. When MiniMax is the provider, such as with `provider: { "only": ["minimax"] }`, M3's thinking is adaptive, so the model can answer without any, and MiniMax has no setting to force it. For the newer model, select `minimax/minimax-m3.1-flash` explicitly. It is included in subscriptions and supports text, image, and video input, tool calling, a shared 1,000,000-token context window, and up to 524,288 output tokens within the remaining context. Thinking is always enabled; `reasoning_effort` accepts `low`, `medium`, `high`, `xhigh`, and `max`, with `max` as the default. Reasoning tokens count toward the output limit. Hiding reasoning with `reasoning.exclude` does not disable thinking or its token usage. M3.1 Flash uses a fixed `temperature` of `1` and `top_p` of `0.95`. Custom values have no effect; omit these parameters from requests. M3.1 Flash currently does not support `response_format` JSON modes, forced `tool_choice`, or disabling thinking. Keep an explicit M3 model for integrations that need these controls. Use the detailed model catalog for current prices and the [provider endpoint](https://api.nano-gpt.com/api/models/minimax%2Fminimax-m3.1-flash/providers) for route-specific limits and privacy information. ## Compatibility Responses mirror OpenAI's Models API shape. All models endpoints return: ```json theme={null} { "object": "list", "data": [ { /* model */ }, ... ] } ``` Each model minimally includes: ```json theme={null} { "id": "openai/gpt-6.1-sol", "object": "model", "created": 1736966400, "owned_by": "openai" } ``` ## Features * **Basic Mode**: Standard OpenAI-compatible model listing. Capability and service-tier metadata is omitted. * **Detailed Mode**: Enhanced information with capabilities, supported service tiers, pricing, and model descriptions. ## Provider Selection Discovery Provider selection support, public provider IDs, and provider-specific prices are discovered via `GET /api/models/:canonicalId/providers`. Its `Per1kTokens` fields are USD per 1,000 tokens and include selection markup; `provider.max_price` uses USD per 1 million tokens. See [Provider Selection](/api-reference/miscellaneous/provider-selection#discover-providers-and-pricing) for details. ## Query Parameters | Parameter | Type | Default | Description | | - | - | - | - | | `detailed` | boolean | `false` | Returns detailed model information including capabilities, supported service tiers, and pricing | | `sort` | string | none | Values: `favorites`, `mostused`. Reorders the returned model list. Sorting only affects models that would already be visible to the caller. It does not add or hide models. | | `output_modalities` | string | none | `decisions` lists only decision models; `text,decisions` lists chat models and decision models together. Without it, decision models are left out. Also accepted by the subscription, paid and personalized lists. | When `detailed=true`, additional fields may be included per model: * `name` — display name * `description` — short model description * `context_length` — total context window shared by input and generated output (if known) * `max_output_tokens` — max output tokens (if known) * `capabilities` — feature flags (see below) * `supported_service_tiers` — alternate `service_tier` values accepted by the model (`flex`, `fast`, and/or the legacy `priority` alias); an empty array means only the default tier is available * `pricing.prompt` and `pricing.completion` — current per-million-token prices in USD * `pricing.cacheReadInputPer1kTokens`, `pricing.cacheWriteInputPer1kTokens` and `pricing.cacheWriteInputPer1kTokens1h` — cache read, 5-minute cache write and 1-hour cache write prices in USD per 1,000 tokens, when the model has them (see [Pricing Object Structure](#pricing-object-structure)) * `pricing.firstContextThresholdTokens`, `pricing.highContextThresholdTokens` and the prices above them — for models whose prices rise with prompt length (see [Long-Context Pricing](#long-context-pricing)) * `pricing.unit` — `per_million_tokens`, the unit of `prompt` and `completion` * `icon_url` — small icon representing the provider * `cost_estimate` — internal rollup used in UI for cost hints (for example `"$"`, `"$$"`, or an object) * `category` — optional category tag (for example `"flagship"`, `"mini"`, `"reasoning"`) * `distillationPolicy` — optional policy metadata indicating whether model outputs may be used for distillation or output-based training under NanoGPT's recorded model-license rules ### Discovering service-tier support Service-tier availability is model-specific. To discover it programmatically, request the detailed model list and inspect each model's `supported_service_tiers` array: ```bash theme={null} curl -s "https://api.nano-gpt.com/api/v1/models?detailed=true" \ | jq '.data[] | select(.supported_service_tiers | length > 0) | {id, supported_service_tiers}' ``` For example: ```json theme={null} { "id": "openai/gpt-6.1-sol", "supported_service_tiers": ["flex", "fast", "priority"] } ``` * `flex` requests lower-cost, variable-capacity processing. * `fast` is the preferred public spelling for higher-priority OpenAI processing. * `priority` remains accepted as a legacy alias and may still be the provider-native name on compatible non-OpenAI routes. * An empty array means the model supports only the default service tier. The basic `GET /api/v1/models` response intentionally omits this field for OpenAI compatibility. The [Models page](https://nano-gpt.com/models) also displays service-tier badges for visual discovery. Provider-specific availability can differ when you explicitly force a route; see [Provider Selection](/api-reference/miscellaneous/provider-selection). ### Discovering video-capable models For multimodal input, call `GET /api/v1/models?detailed=true` and select a model whose catalog entry advertises video input. Catalog fields are additive, so inspect both the architecture modalities and capability flags when present: ```json theme={null} { "id": "google/gemini-3.1-flash-lite", "architecture": { "input_modalities": ["text", "image", "video"] }, "capabilities": { "video_input": true } } ``` An explicitly selected model without video capability is rejected before provider dispatch and billing. Automatic fallback keeps only routes that preserve the requested video input. See [Video Input](/api-reference/miscellaneous/video-input) for the endpoint content shapes and source rules. ### Sorting model lists `GET /api/v1/models` supports `sort=favorites` and `sort=mostused`. When `sort` is present, NanoGPT returns the same model list the caller would normally receive, but reordered by the selected ranking. Sorting only affects models that would already be visible to the caller. It does not add or hide models. * `sort=favorites`: Orders models by the authenticated account's recent model usage. * `sort=mostused`: Orders models by global completed model usage. * Unused or unranked models remain in the response after ranked models, in the normal catalog order. * `sort=favorites` requires a valid API key to personalize the order. If no valid API key is provided, it falls back to normal ordering. * `sort=mostused` does not require authentication. * Invalid `sort` values are ignored. * Can be combined with `detailed=true`. Examples: ```bash theme={null} curl -H "Authorization: Bearer $NANOGPT_API_KEY" \ "https://api.nano-gpt.com/api/v1/models?sort=favorites" ``` ```bash theme={null} curl "https://api.nano-gpt.com/api/v1/models?sort=mostused" ``` ```bash theme={null} curl -H "Authorization: Bearer $NANOGPT_API_KEY" \ "https://api.nano-gpt.com/api/v1/models?detailed=true&sort=favorites" ``` ```bash theme={null} curl "https://api.nano-gpt.com/api/v1/models?detailed=true&sort=mostused" ``` ### `capabilities` (detailed mode) Common capability flags: | Field | Type | Description | | - | - | - | | `vision` | boolean | Supports image inputs | | `reasoning` | boolean | Supports extended thinking/reasoning | | `tool_calling` | boolean | Supports function/tool calling | | `parallel_tool_calls` | boolean | Supports multiple tool calls in parallel | | `structured_output` | boolean | Supports structured/JSON output modes | | `pdf_upload` | boolean | Supports PDF/document inputs | | `video_input` | boolean | Supports video inputs for text or multimodal understanding | ## Authentication Authentication is optional but enables user-specific pricing in detailed mode: | Header | Format | Required | Description | | - | - | - | - | | `Authorization` | `Bearer {api_key}` | Optional | API key for user-specific pricing | | `x-api-key` | `{api_key}` | Optional | Alternative API key header | Notes: * Invalid or missing API keys still return a list of models. We simply omit user-specific pricing considerations in `detailed=true` mode. * With a valid key, the canonical `/api/v1/models` may apply your account’s subscription visibility preference (see Endpoint Variants). ## Response Formats ### Basic Response (Default) Standard OpenAI-compatible format without pricing information: ```json theme={null} { "object": "list", "data": [ { "id": "openai/gpt-6.1-sol", "object": "model", "created": 1790640000, "owned_by": "openai" }, { "id": "anthropic/claude-opus-5.5", "object": "model", "created": 1790035200, "owned_by": "anthropic" } ] } ``` ### Detailed Response Enhanced format with model descriptions, context lengths, and pricing: ```json theme={null} { "object": "list", "data": [ { "id": "openai/gpt-6.1-sol", "object": "model", "created": 1790640000, "owned_by": "openai", "name": "GPT 6.1 Sol", "description": "GPT-6.1 Sol delivers near-Astra performance at a lower cost for complex coding, computer use, and professional work. It supports text and image input, tool calling, structured outputs, and reasoning from low through max.", "context_length": 1050000, "max_output_tokens": 128000, "supported_service_tiers": [ "flex", "fast", "priority" ], "capabilities": { "vision": true, "video_input": false, "audio_input": false, "reasoning": true, "tool_calling": true, "parallel_tool_calls": false, "structured_output": true, "pdf_upload": true, "batch_api": true }, "pricing": { "prompt": 2, "completion": 10, "cacheReadInputPer1kTokens": 0.0001, "cacheWriteInputPer1kTokens": 0.0025, "currency": "USD", "unit": "per_million_tokens" } }, { "id": "anthropic/claude-opus-5.5", "object": "model", "created": 1790035200, "owned_by": "anthropic", "name": "Claude Opus 5.5", "description": "Claude Opus 5.5 is Anthropic's flagship model for agentic coding, computer use, complex knowledge work, and long-running tasks, with improved efficiency and more natural communication.", "context_length": 1000000, "max_output_tokens": 128000, "supported_service_tiers": [], "capabilities": { "vision": true, "video_input": false, "audio_input": false, "reasoning": true, "tool_calling": true, "parallel_tool_calls": false, "structured_output": true, "pdf_upload": true, "batch_api": true }, "pricing": { "prompt": 4, "completion": 20, "cacheReadInputPer1kTokens": 0.0002, "cacheWriteInputPer1kTokens": 0.005, "cacheWriteInputPer1kTokens1h": 0.008, "currency": "USD", "unit": "per_million_tokens" } } ] } ``` ## Field Descriptions ### Basic Fields (Always Present) | Field | Type | Description | | - | - | - | | `id` | string | Unique model identifier | | `object` | string | Always "model" for OpenAI compatibility | | `created` | number | Unix timestamp of response creation | | `owned_by` | string | Model provider (openai, anthropic, meta, google, etc.) | ### Enhanced Fields (Detailed Mode Only) | Field | Type | Description | | - | - | - | | `name` | string | Human-readable model name | | `description` | string | Detailed model description | | `context_length` | number or null | Total context window shared by input and generated output (null if not available) | | `max_output_tokens` | number | Maximum output tokens (null if not available) | | `capabilities` | object | Feature flags (e.g., `vision: boolean`) | | `supported_service_tiers` | string\[] | Alternate service tiers accepted by the model. An empty array means only the default tier is available. | | `pricing` | object | Pricing information object | | `icon_url` | string | Path/URL for a small provider icon | | `cost_estimate` | string or object | Internal hints (for example `"$"` / `"$$"` or `{ cheap: true }`) | | `category` | string | Optional category (e.g., `"flagship"`, `"mini"`, `"reasoning"`) | | `distillationPolicy` | object | Optional API-only distillation metadata. See [Distillation Policy](/api-reference/miscellaneous/distillation-policy). | ### Pricing Object Structure | Field | Type | Description | | - | - | - | | `prompt` | number | Cost per million input tokens in USD | | `completion` | number | Cost per million output tokens in USD | | `cacheReadInputPer1kTokens` | number | Optional. Cost per 1,000 cached input tokens read, in USD | | `cacheWriteInputPer1kTokens` | number | Optional. Cost per 1,000 input tokens written to the prompt cache with the default 5-minute lifetime, in USD | | `cacheWriteInputPer1kTokens1h` | number | Optional. Cost per 1,000 input tokens written to the prompt cache with a 1-hour lifetime (`ttl: "1h"`, see [Prompt Caching](/api-reference/miscellaneous/prompt-caching)), in USD | | `currency` | string | Always "USD" | | `unit` | string | Always "per_million_tokens". Applies to `prompt` and `completion` only | Fields ending in `Per1kTokens` are USD per 1,000 tokens. Multiply them by 1,000 for the per-million price shown on the [pricing page](https://nano-gpt.com/api-pricing): Claude Opus 5.5's `cacheWriteInputPer1kTokens1h` of `0.008` is \$8.00 per million tokens. Cache prices are left out for models with no cache pricing. These are base-context prices; models whose prices rise with prompt length also list [long-context tiers](#long-context-pricing). ### Long-Context Pricing Some models charge more once a prompt passes a threshold. A request whose prompt is longer than the threshold is billed entirely at that tier's prices: every input, cached and output token, not only the tokens past the threshold. Prompt length counts all input tokens, cached ones included. A model lists up to two tiers, and each tier lists every price that applies in it, including any that equal the base price. | Field | Type | Description | | - | - | - | | `firstContextThresholdTokens` | number | Optional. Prompts longer than this many tokens are billed at the `AboveFirstThreshold` prices | | `inputPer1kTokensAboveFirstThreshold`, `outputPer1kTokensAboveFirstThreshold` | number | Input and output prices above the first threshold, in USD per 1,000 tokens | | `cacheReadInputPer1kTokensAboveFirstThreshold`, `cacheWriteInputPer1kTokensAboveFirstThreshold`, `cacheWriteInputPer1kTokens1hAboveFirstThreshold` | number | Cache read, 5-minute cache write and 1-hour cache write prices above the first threshold, in USD per 1,000 tokens, when the model has those cache prices | | `highContextThresholdTokens` | number | Optional. Prompts longer than this many tokens are billed at the `Above200k` prices. Despite the field names, the threshold is not always 200,000 | | `highContextThresholdCountsOutputTokens` | boolean | Optional. `true` when input plus output tokens count toward `highContextThresholdTokens` (Grok 4.3 and Grok Build) | | `inputPer1kTokensAbove200k`, `outputPer1kTokensAbove200k` | number | Input and output prices above the high threshold, in USD per 1,000 tokens | | `cacheReadInputPer1kTokensAbove200k`, `cacheWriteInputPer1kTokensAbove200k`, `cacheWriteInputPer1kTokens1hAbove200k` | number | Cache read, 5-minute cache write and 1-hour cache write prices above the high threshold, in USD per 1,000 tokens, when the model has those cache prices | Claude Haiku 5.5, for example, costs more once a prompt passes 100,000 tokens. A 1-hour cache write costs `0.0002` ($0.20 per million tokens) up to that point and `0.001` ($1.00 per million tokens) beyond it: ```json theme={null} "pricing": { "prompt": 0.1, "completion": 0.5, "cacheReadInputPer1kTokens": 0.00001, "cacheWriteInputPer1kTokens": 0.000125, "cacheWriteInputPer1kTokens1h": 0.0002, "firstContextThresholdTokens": 100000, "inputPer1kTokensAboveFirstThreshold": 0.0005, "outputPer1kTokensAboveFirstThreshold": 0.0025, "cacheReadInputPer1kTokensAboveFirstThreshold": 0.00005, "cacheWriteInputPer1kTokensAboveFirstThreshold": 0.000625, "cacheWriteInputPer1kTokens1hAboveFirstThreshold": 0.001, "currency": "USD", "unit": "per_million_tokens" } ``` ### Distillation Policy Where available, text model records include a `distillationPolicy` object with `status`, `label`, `basis`, `sourceUrl`, and `note`. This indicates whether model outputs may be used for model training, fine-tuning, distillation, or similar model-improvement workflows under NanoGPT's recorded interpretation of model licenses and provider terms. ```json theme={null} { "distillationPolicy": { "status": "allowed", "label": "License permits distillation", "basis": "permissive-open-weights", "sourceUrl": "https://example.com/license-or-terms", "note": "Short explanation of the policy signal." } } ``` Use the explore endpoints when you need to filter for distillation-allowed text models: ```http theme={null} GET /api/explore/text-models?distillation=allowed ``` ```http theme={null} GET /api/explore/search?type=text&q=qwen&distillation=allowed ``` The filter applies only to text models. Responses include `meta.distillation: "allowed"` when the filter is used and `meta.distillation: "all"` otherwise. Provider route policy can differ from model-level policy. Use `GET /api/models/:canonicalId/providers` and inspect each provider row's `distillationPolicy` before relying on a specific route for distillation. This metadata is informational and is not legal advice. Provider terms and model licenses can change, and licenses may impose attribution, naming, acceptable-use, or derivative-model restrictions even when distillation is allowed. ## Usage Examples ### Basic Request ```bash theme={null} curl "https://api.nano-gpt.com/api/v1/models" ``` ### Detailed Request ```bash theme={null} curl "https://api.nano-gpt.com/api/v1/models?detailed=true" ``` ### Sort by Favorites ```bash theme={null} curl -H "Authorization: Bearer $NANOGPT_API_KEY" \ "https://api.nano-gpt.com/api/v1/models?sort=favorites" ``` ### Sort by Most Used ```bash theme={null} curl "https://api.nano-gpt.com/api/v1/models?sort=mostused" ``` ### Detailed and Sorted ```bash theme={null} curl -H "Authorization: Bearer $NANOGPT_API_KEY" \ "https://api.nano-gpt.com/api/v1/models?detailed=true&sort=favorites" ``` ```bash theme={null} curl "https://api.nano-gpt.com/api/v1/models?detailed=true&sort=mostused" ``` ### Detailed with Authentication ```bash theme={null} curl "https://api.nano-gpt.com/api/v1/models?detailed=true" \ -H "Authorization: Bearer your_api_key_here" ``` ### Alternative API Key Header ```bash theme={null} curl "https://api.nano-gpt.com/api/v1/models?detailed=true" \ -H "x-api-key: your_api_key_here" ``` ## Endpoint Variants In addition to the canonical `/api/v1/models`, two filtered variants are available: ### 1) GET /api/v1/models (canonical) * Returns all visible text models (excludes internal free/helper selector models except `auto-model*`). * If your account has an active subscription and you have not enabled “Also show paid models”, the list is automatically restricted to only subscription-included models. * If you enable “Also show paid models” in settings, it returns the full set again. Examples: ```bash theme={null} curl -H "Authorization: Bearer $NANOGPT_API_KEY" \ https://api.nano-gpt.com/api/v1/models ``` ```bash theme={null} curl -H "Authorization: Bearer $NANOGPT_API_KEY" \ "https://api.nano-gpt.com/api/v1/models?detailed=true" ``` ### 2) GET /api/subscription/v1/models (subscription-only) * Always returns only models included in the NanoGPT subscription (equivalent to our `isTextEligible(modelId)` filter). * Ignores the user’s “Also show paid models” preference; it is always subscription-only. * Supports `?detailed=true` and API key–aware pricing metadata. Examples: ```bash theme={null} curl https://api.nano-gpt.com/api/subscription/v1/models ``` ```bash theme={null} curl -H "x-api-key: $NANOGPT_API_KEY" \ "https://api.nano-gpt.com/api/subscription/v1/models?detailed=true" ``` ### 3) GET /api/paid/v1/models (paid/extras) * Returns only models that are NOT part of the subscription (paid/premium/extras). * Supports `?detailed=true` and API key–aware pricing metadata. Examples: ```bash theme={null} curl https://api.nano-gpt.com/api/paid/v1/models ``` ```bash theme={null} curl -H "Authorization: Bearer $NANOGPT_API_KEY" \ "https://api.nano-gpt.com/api/paid/v1/models?detailed=true" ``` ### Choosing the Right Endpoint * Use `/api/subscription/v1/models` for curated lists guaranteed to be subscription-included (e.g., sub-only integrations). * Use `/api/paid/v1/models` to focus on paid or premium models. * Use `/api/v1/models` for the canonical list and let the account’s “Also show paid models” preference decide visibility. ## Errors and Limits * These endpoints typically return `200` with a list. If an invalid API key is provided, the list still returns and simply omits user-specific pricing considerations in `detailed=true` mode. * Standard CORS and rate limiting apply. In overload scenarios you may receive `429` with: ```json theme={null} { "code": "rate_limited", "message": "Rate limit exceeded" } ``` ## Backwards Compatibility * Default response format unchanged * All existing fields preserved * New fields are additive only * No breaking changes to existing integrations ## Related Endpoints * [Image models](/api-reference/endpoint/image-models) - List image model capabilities and supported parameters * [Video models](/api-reference/endpoint/video-models) - List video model capabilities and supported parameters * [Audio models](/api-reference/endpoint/audio-models) - List text-to-speech and speech-to-text models * [Embedding models](/api-reference/endpoint/embedding-models) - List embedding model dimensions, token limits, and pricing * [/api/v1/embeddings](/api-reference/endpoint/embeddings) - Create embeddings using the available embedding models * [Provider Selection](/api-reference/miscellaneous/provider-selection) - Discover model providers and set provider preferences * `/api/subscription/v1/models` - Subscription-included text models * `/api/paid/v1/models` - Paid or premium text models ## Notes * Scope: These endpoints list text-chat models. For image, video, audio, embedding and decision catalogs, use the dedicated model catalog pages linked above. * Fields are subject to change as new capabilities or providers are added. We aim to remain OpenAI-API compatible for basic consumers (`id`/`object`/`created`/`owned_by`). # Moderation Models Source: https://docs.nano-gpt.com/api-reference/endpoint/moderation-models GET /v1/moderation-models List available content moderation models ## Overview Use `GET /api/v1/moderation-models` to list the moderation models currently available to your account. The response includes model capabilities, context limits, and pricing. Model availability and capabilities can change over time. Use this endpoint as the source of truth before choosing a model for `POST /api/v1/moderations` or [Inline Moderation](/api-reference/miscellaneous/inline-moderation). ## Endpoint ```text theme={null} GET https://api.nano-gpt.com/api/v1/moderation-models ``` ## Authentication An API key is required. * `Authorization: Bearer YOUR_API_KEY` * `x-api-key: YOUR_API_KEY` ## Query Parameters | Parameter | Type | Default | Description | | - | - | - | - | | `detailed` | boolean | `true` | When `false`, returns a compact OpenAI-style model list. | ## Examples ```bash theme={null} curl https://api.nano-gpt.com/api/v1/moderation-models \ -H "Authorization: Bearer $NANOGPT_API_KEY" ``` ```bash theme={null} curl "https://api.nano-gpt.com/api/v1/moderation-models?detailed=false" \ -H "Authorization: Bearer $NANOGPT_API_KEY" ``` ## Response The detailed response returns a model list with capability and pricing metadata. Exact fields can vary by model. ```json theme={null} { "object": "list", "data": [ { "id": "moderation-model-id", "object": "model", "created": 1704067200, "owned_by": "model-owner", "context_length": 128000, "capabilities": { "text": true, "image": true, "batch": true }, "pricing": { "prompt": 0.10, "completion": 0.00, "currency": "USD", "unit": "per_million_tokens" } } ] } ``` ## Notes * This is a paid API feature. * Some moderation models support text only; others support both text and image inputs. * Batch support can vary by model. * Pricing details are returned by this endpoint and can vary by selected model. # Moderations Source: https://docs.nano-gpt.com/api-reference/endpoint/moderations POST /v1/moderations Classify text and image content for safety ## Overview Use `POST /api/v1/moderations` to classify text, image, or mixed content for safety before you store, display, or send user-generated content to another model endpoint. If you want NanoGPT to run a paid input safety preflight automatically before supported generation requests, use [Inline Moderation](/api-reference/miscellaneous/inline-moderation) instead. The endpoint is synchronous and returns an OpenAI-compatible moderation response shape where practical. It is a paid API feature and bills proportionally to usage with no separate minimum charge. ## Endpoint ```text theme={null} POST https://api.nano-gpt.com/api/v1/moderations ``` ## Authentication An API key is required. * `Authorization: Bearer YOUR_API_KEY` * `x-api-key: YOUR_API_KEY` ## Model Selection The `model` field is optional. If omitted, NanoGPT uses the default moderation model. Available input types, batch support, context limits, and pricing depend on the selected model. Use [Moderation Models](/api-reference/endpoint/moderation-models) before choosing a model instead of hardcoding capabilities. ## Request Body | Field | Type | Required | Description | | - | - | - | - | | `model` | string | No | Moderation model ID. Omit to use the default moderation model. | | `input` | string, array, or content parts | Yes | Content to classify. | ## Input Examples ### Single Text Input ```json theme={null} { "model": "moderation-model-id", "input": "Text to classify." } ``` ### Batch Text Input ```json theme={null} { "model": "moderation-model-id", "input": [ "First item to classify.", "Second item to classify." ] } ``` Batch support can vary by model. If a selected model does not support batched input, the API returns an error before billing. ### Text Content Part ```json theme={null} { "model": "moderation-model-id", "input": [ { "type": "text", "text": "Text to classify." } ] } ``` ### Image Input ```json theme={null} { "model": "moderation-model-id", "input": [ { "type": "image_url", "image_url": { "url": "https://example.com/image.png" } } ] } ``` Image support depends on the selected model. Text-only models reject image input before billing. ## Example ```bash theme={null} curl https://api.nano-gpt.com/api/v1/moderations \ -H "Authorization: Bearer $NANOGPT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "moderation-model-id", "input": "Text to classify for safety." }' ``` ## Response ```json theme={null} { "id": "modr_...", "model": "moderation-model-id", "results": [ { "flagged": false, "categories": { "category_name": false }, "category_scores": { "category_name": 0.01 } } ], "usage": { "prompt_tokens": 12, "completion_tokens": 100, "total_tokens": 112 } } ``` | Field | Description | | - | - | | `flagged` | `true` when the selected model classifies the content as unsafe. | | `categories` | Category-level boolean results. Exact category names are model-dependent. | | `category_scores` | Category-level confidence scores when available. Exact category names are model-dependent. | | `usage` | Token usage used for billing and diagnostics. | ## Billing The endpoint is paid and bills proportionally to usage. There is no extra minimum charge. General billing behavior: * Input tokens are billed according to the selected moderation model's input rate. * Output tokens may be billed when the selected model returns billable classification output. * NanoGPT performs a preflight balance check before dispatching the request. * The final charge is based on measured or estimated usage recorded for the completed request. * Pricing details are returned by `GET /api/v1/moderation-models`. ## Rate Limits And Access Controls The endpoint uses standard NanoGPT API authentication, balance checks, API-key limits, and account/team access controls. * API keys can be subject to model allowlists. * API keys can be subject to spending and token limits. * Team billing and team restrictions apply where configured. * Requests can be rate limited. ## Errors Errors follow the standard NanoGPT/OpenAI-compatible error shape: ```json theme={null} { "error": { "message": "Invalid request parameters. Please check your input and try again.", "type": "invalid_request_error", "code": "unsupported_input_modality", "param": "input" } } ``` | Status | Code | Meaning | | - | - | - | | 400 | `empty_input` | The request did not include moderatable text or image content. | | 400 | `unsupported_input_modality` | The selected model does not support the submitted input type. | | 400 | `unsupported_batch_input` | The selected model does not support batched input. | | 400 | `context_length_exceeded` | The input is too large for the selected model. | | 400 | `zero_data_retention` | The API key, account or team requires Zero Data Retention and the selected moderation model does not offer it. | | 401 | `missing_api_key` or `invalid_api_key` | Authentication failed. | | 402 | varies | The account does not have enough balance. | | 403 | `paid_features_disabled` | Paid API features are disabled for the account. | | 403 | `provider_not_allowed` | The API key's provider list does not include the selected moderation model's provider. | | 404 | `model_not_found` | The requested moderation model does not exist or is unavailable. | | 429 | `rate_limit_exceeded` | The caller exceeded a rate limit. | | 503 | `provider_error` or similar | The upstream moderation service was temporarily unavailable or returned an invalid response. | # NSFW Image Classification Source: https://docs.nano-gpt.com/api-reference/endpoint/nsfw-image POST /nsfw/image Binary NSFW classification for up to 10 image URLs or data URLs per request ## Overview The NSFW Image Classification endpoint performs **binary classification** on image URLs (or base64 data URLs) and returns whether each image contains NSFW concepts. Send up to **10 images per request**. ## Authentication Include your API key in the request header: ``` x-api-key: YOUR_API_KEY ``` Alternatively, you can use Bearer token authentication: ``` Authorization: Bearer YOUR_API_KEY ``` ## Request ### Headers ``` Content-Type: application/json x-api-key: YOUR_API_KEY ``` ### Body parameters You may provide images in **any** of the following fields. The endpoint accepts **up to 10 images per request**. | Parameter | Type | Required | Description | | - | - | - | - | | `image_urls` | string \| string\[] | No | Primary input field. One URL or an array of URLs. | | `imageUrls` | string \| string\[] | No | Alias for `image_urls`. | | `imageUrl` | string | No | Alias for a single image URL. | | `imageDataUrl` | string | No | Base64 data URL for a single image. | | `imageDataUrls` | string\[] | No | Base64 data URLs for multiple images. | | `model` | string | No | Only supported value is `nsfw-classifier` (default). | At least one image field is required. If more than 10 images are provided, only the **first 10** are processed and billed. ### Example request ```json theme={null} { "image_urls": [ "https://example.com/image-1.jpg", "https://example.com/image-2.jpg" ] } ``` ## Response ### Success (200) ```json theme={null} { "model": "nsfw-classifier", "requestId": "", "inputCount": 2, "cost": 0.003, "currency": "USD", "truncated": false, "has_nsfw_concepts": [false, true], "is_nsfw": true } ``` ### Response fields * `model`: The classifier model used. * `requestId`: Request ID (if available; helpful for support). * `inputCount`: Number of images processed (max 10). * `cost`: Final charged amount (after discounts and currency conversion). * `currency`: `USD` or `XNO` depending on payment source. * `truncated`: `true` if more than 10 images were provided. * `has_nsfw_concepts`: List of booleans (one per image, in input order). * `is_nsfw`: `true` if any image was flagged. ## Errors ### 400 – Invalid or policy violation * Missing or invalid image URLs * JSON parsing error * Policy violation (returns a safety error message) ```json theme={null} { "error": "No valid image URLs provided" } ``` ### 401 – Unauthorized ```json theme={null} { "error": "Unauthorized" } ``` ### 429 – Rate limit or API key usage limits ```json theme={null} { "error": "Rate limit exceeded" } ``` ### 500 – Server or provider failure ```json theme={null} { "error": "NSFW classification failed" } ``` ## Billing Notes * Charged **\$0.0015 per image** actually sent to the classifier. * If more than 10 images are provided, only the **first 10** are billed/processed. * Discounts and referral policies apply as with other endpoints. ## Code Examples ```bash cURL theme={null} curl -X POST https://api.nano-gpt.com/api/nsfw/image \ -H "Content-Type: application/json" \ -H "x-api-key: YOUR_API_KEY" \ -d '{ "image_urls": [ "https://example.com/image-1.jpg", "https://example.com/image-2.jpg" ] }' ``` ```python Python theme={null} import requests api_key = "YOUR_API_KEY" payload = { "image_urls": [ "https://example.com/image-1.jpg", "https://example.com/image-2.jpg" ] } response = requests.post( "https://api.nano-gpt.com/api/nsfw/image", headers={ "Content-Type": "application/json", "x-api-key": api_key }, json=payload ) print(response.json()) ``` ```javascript JavaScript theme={null} const apiKey = 'YOUR_API_KEY'; const response = await fetch('https://api.nano-gpt.com/api/nsfw/image', { method: 'POST', headers: { 'Content-Type': 'application/json', 'x-api-key': apiKey }, body: JSON.stringify({ image_urls: [ 'https://example.com/image-1.jpg', 'https://example.com/image-2.jpg' ] }) }); const data = await response.json(); console.log(data); ``` # Personalized Models Source: https://docs.nano-gpt.com/api-reference/endpoint/personalized-models GET /personalized/v1/models > [!NOTE] > > These examples use the direct API host, `https://api.nano-gpt.com`. It has no IPv6 address, so clients with only IPv6 should use `https://nano-gpt.com` with the same paths. See [API Hosts](/api-reference/miscellaneous/api-hosts). # Personalized Models API Curated, OpenAI‑compatible model listing scoped to each account’s preferences. This endpoint returns only the text models you have marked as “visible” in Settings → Models, regardless of whether they are subscription or paid models. * GET `/api/personalized/v1/models` See also: * Canonical models list: `GET /api/v1/models` * Subscription‑only list: `GET /api/subscription/v1/models` * Paid‑only list: `GET /api/paid/v1/models` ## Compatibility & Response Shape The response mirrors OpenAI’s Models API: ```json theme={null} { "object": "list", "data": [ { /* model */ }, ... ] } ``` Each model contains at least: ```json theme={null} { "id": "openai/gpt-6.1-sol", "object": "model", "created": 1736966400, "owned_by": "openai" } ``` Use `?detailed=true` to include additional fields like `name`, `description`, `context_length`, `capabilities`, `pricing`, `icon_url`, and `cost_estimate`. ## Authentication An API key is required. * `Authorization: Bearer ` * or `x-api-key: ` If the key is missing or invalid, the endpoint returns `401`. ## Personalization Rules * The list is filtered by your account’s visible text models (configured in the NanoGPT web app under Settings → Models → “Visible Text Models”). * This endpoint ignores the user preference “Also show paid models.” If you marked paid models as visible, they appear here even if you generally hide paid models elsewhere. * If you have not set any preferences, the endpoint falls back to NanoGPT defaults (`visible === true` in our model registry). ## Examples Basic list: ```bash theme={null} curl -H "Authorization: Bearer $NANOGPT_API_KEY" \ https://api.nano-gpt.com/api/personalized/v1/models ``` Detailed list with pricing/capabilities: ```bash theme={null} curl -H "x-api-key: $NANOGPT_API_KEY" \ "https://api.nano-gpt.com/api/personalized/v1/models?detailed=true" ``` Sample detailed item: ```json theme={null} { "id": "openai/gpt-6.1-sol", "object": "model", "created": 1736966400, "owned_by": "openai", "name": "GPT-5.2", "description": "OpenAI flagship general-purpose model", "context_length": 128000, "capabilities": { "vision": false }, "pricing": { "prompt": 2.50, "completion": 10.00, "currency": "USD", "unit": "per_million_tokens" }, "icon_url": "/icons/OpenAI.svg", "cost_estimate": { "cheap": false } } ``` ## Managing Your Visible Models The recommended way to customize your personalized list is via the NanoGPT web UI: * Open Settings → Models → “Visible Text Models”. * Toggle visibility and categories as needed; changes are saved to your account. Advanced (web session only): * GET `/api/user/model-visibility` — returns your saved preferences as `{ modelPreferences: { visibleTextModels, modelCategories } }`. * POST `/api/user/model-visibility` — upserts preferences. Cookie‑based session auth is required (not API‑key auth). Payload shape: ```json theme={null} { "visibleTextModels": { "openai/gpt-6.1-sol": true, "anthropic/claude-opus-4.5": false }, "modelCategories": { "openai/gpt-6.1-sol": "General" } } ``` Keys outside NanoGPT’s known model ids are ignored. ## Notes * This route is explicitly dynamic (no shared caching across keys). * Model ids and metadata evolve as providers update their catalogs; keep consumers resilient to new fields. * Personalized results may include paid models even if `/api/v1/models` hides them for your account (by design). # Receive Nano Source: https://docs.nano-gpt.com/api-reference/endpoint/receive-nano POST /receive-nano Process pending Nano transactions for the account # Request Billing Source: https://docs.nano-gpt.com/api-reference/endpoint/request-billing GET /v1/usage/requests/{request_id} Look up a recorded primary charge and token usage by request ID for 24 hours. `GET /api/v1/usage/requests/{request_id}` returns the recorded cost and token usage for one primary charge from the **last 24 hours**. Capture `X-Request-ID` from the inference response headers before reading SSE and use the **same API key** for the lookup. No dates or other query parameters are accepted. For chat completions, omit the incoming `X-Request-ID` header and capture the server-generated ID from each response. Save it as soon as the response headers arrive, before consuming the stream; it is the ID to use for this lookup. After a [model fallback](/api-reference/miscellaneous/provider-selection#model-fallbacks), use `x_nanogpt_pricing.requestId` instead. `X-Request-ID` keeps the first attempt's ID, and the charge belongs to the attempt that answered. ```sh theme={null} curl 'https://api.nano-gpt.com/api/v1/usage/requests/req_example' \ -H "Authorization: Bearer $NANOGPT_API_KEY" ``` ```json theme={null} { "object": "request_billing", "request_id": "req_example", "created_at": "2026-09-17T10:00:01.000000Z", "expires_at": "2026-09-18T10:00:01.000000Z", "as_of": "2026-09-17T10:00:05.000000Z", "cost": "0.00123456", "currency": "USD", "cost_scope": "primary_charge", "usage": { "input_tokens": 123, "output_tokens": 45, "reasoning_tokens": null } } ``` ## What cost means `cost` is the exact amount recorded on the matching primary charge, expressed as a decimal **string** in `currency` (`USD` or `XNO`). The lookup does not recalculate prices. A recorded zero is returned as zero; a missing charge is never converted to zero. Refunds and separately billed extras, such as a separate search charge, are excluded. Components already incorporated in the primary charge's amount remain included. This is the original recorded primary cost, not an all-in total or a net amount after refunds. A later refund does not reduce this field. A completed transaction record is also not proof that balance collection has finished. Tokens are recorded accounting values and may have been estimated for an interrupted stream. Missing, invalid or unsafe-sized counts are `null`. Reasoning tokens may already be included in output tokens; do not add them again. No prompts, responses, provider routing, internal identifiers or arbitrary transaction metadata are returned. ## Availability and request IDs The window is rolling, including across UTC midnight. A charge is eligible when its accounting timestamp is no more than the database's current time and is strictly less than 24 hours old. `expires_at` is that timestamp plus 24 hours; access ends at that instant. This timestamp can precede insertion when delayed billing is replayed. Replay does not reset the lookup window. Financial records are retained; this endpoint simply stops exposing older charges. Billing can be asynchronous, especially after a disconnect, so the charge might not be available immediately. A charge recorded only after its window expires cannot be recovered through this endpoint. Expired, unavailable and inaccessible records all return the same 404; this does not prove that a request was free. If you supply your own `X-Request-ID`, use a unique value for every execution, including a retry that sends a new inference request. The header is a correlation ID, **not an idempotency key**: reusing it does not prevent another charge. After a disconnect, look up the original ID to recover its cost; retrying the lookup does not rerun inference. If you also retry inference, keep the two execution IDs separate. If more than one eligible primary charge matches within the window, the endpoint returns **409 `ambiguous_request_id`**, without choosing one, summing different attempts, or returning their details. Uniqueness is checked within the window only; reusing an expired ID can resolve to a newer execution. Only completed primary charges with the exact stored public request ID are covered. Other endpoints are supported only when they persist that identity and key/issuer attribution. Related child IDs and archived records are not followed. ## Authentication The inference key can read only its own charges attributed to its originating account in the same NanoGPT tenant. Team-paid charges remain visible to the originating actor's key; team ownership or membership does not grant broader access. Missing or inconsistent historical attribution can make a charge unavailable. Revoked/expired keys, deleted/merged issuers, and different keys cannot retrieve the original key's charges. Rotation does not transfer access. Authentication is fresh and existing key Origin restrictions apply. Use `Authorization` or `x-api-key`; cookies, management credentials and partner tokens grant no access. Conflicting credentials are rejected; equivalent supported prefix/case forms are accepted. ## Polling and errors Make the first lookup about two seconds after a disconnect or completion. A 404 includes `Retry-After: 30`: wait **at least 30 seconds**, plus a small random delay, before the next lookup. Honor `Retry-After` on 429 and 503 responses too; do not cap a larger server-requested delay at 30 seconds. For a network failure without a response, back off with jitter from two seconds up to 30 seconds. Stop on 200. Stop and correct the request or seek support on 400, 401, 403 or 409; do not automatically rerun inference to resolve a billing lookup error. This API does not expose a `finalized` flag and clients do not need to keep polling for later refunds. Clients are responsible for polling and honoring retry delays. The shared budgets are **60 lookups/minute per key** and **300/minute per trusted IP**, including unsuccessful lookups. Coordinate polling across concurrent requests. If no charge appears, stop retries no later than 24 hours after the original request and retain its ID for support. This is a retry limit, not a promise that every billing record will become available within 24 hours. | Status | Meaning | | - | - | | 200 | One recorded primary charge, with exact cost, currency, tokens and expiry. | | 400 | Invalid request ID, unsupported query parameters, or conflicting credentials. | | 401 / 403 | Credential, issuer or key-policy rejection; stop and correct access. | | 404 | No eligible charge visible to this key. May be delayed, expired, inaccessible or absent; never assume zero cost. Wait at least the indicated 30 seconds before retrying. | | 409 | Multiple eligible primary charges match this ID; do not automatically retry or infer a total. | | 429 | Quota exceeded; honor `Retry-After`. | | 503 | The billing lookup is temporarily unavailable; honor `Retry-After`. | Every response uses `Cache-Control: private, no-store, max-age=0`, private/no-store CDN headers and `Vary: Authorization, x-api-key`. ## Capture the ID before reading a stream This JavaScript example saves the ID when the response headers arrive. Keep it even if reading the body fails. `model` and `messages` are the values from your normal chat request, and `apiKey` is your NanoGPT API key. ```js theme={null} const response = await fetch('https://api.nano-gpt.com/api/v1/chat/completions', { method: 'POST', headers: { Authorization: `Bearer ${apiKey}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ model, messages, stream: true }), }); const requestId = response.headers.get('x-request-id'); // Save requestId before consuming response.body with your SSE parser. // If the stream disconnects, keep that ID and follow the polling guidance above. ``` Use the HTTP response header, not a completion ID from a JSON body or SSE event. If the connection fails before headers arrive and no ID was captured, this endpoint cannot identify that execution for you. For a later lookup, use the same key and the captured ID: ```js theme={null} if (requestId) { const lookup = await fetch( `https://api.nano-gpt.com/api/v1/usage/requests/${encodeURIComponent(requestId)}`, { headers: { Authorization: `Bearer ${apiKey}` } }, ); if (lookup.ok) { const billing = await lookup.json(); // Preserve billing.cost as a decimal string, or use a decimal library. } else { // Handle lookup.status and lookup.headers.get('retry-after') as above. } } ``` `Retry-After` may contain seconds or an HTTP date; respect its full delay. For aggregate spend and refunds over a date range, use [Usage](/api-reference/endpoint/usage). # Rerank Source: https://docs.nano-gpt.com/api-reference/endpoint/rerank Order text documents by relevance to a query `POST /api/v1/rerank` scores each document against a query and returns them from most to least relevant. List the available models with `GET /api/v1/rerank-models`. ```bash theme={null} curl https://api.nano-gpt.com/api/v1/rerank \ -H "Authorization: Bearer $NANOGPT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "nvidia/Nemotron-3.5-Rerank-8B-BF16", "query": "How do I reset my password?", "documents": [ "Open Settings and choose Reset password.", "Our office is closed on Sundays." ], "top_n": 1, "return_documents": true }' ``` ```json theme={null} { "id": "rerank-393a019d-e3f5-4c06-af5b-65a89e6cfd73", "model": "nvidia/Nemotron-3.5-Rerank-8B-BF16", "results": [ { "index": 0, "relevance_score": -1.8285, "document": { "text": "Open Settings and choose Reset password." } } ], "usage": { "prompt_tokens": 38, "total_tokens": 38 } } ``` ## Request | Field | Type | Required | Description | | - | - | - | - | | `model` | string | Yes | `nvidia/Nemotron-3.5-Rerank-8B-BF16` | | `query` | string | Yes | Non-empty text | | `documents` | string\[] | Yes | 1 to 1,024 non-empty text strings. Images aren't supported | | `top_n` | integer | No | How many results to return, from 1 to the number of documents. Defaults to all | | `return_documents` | boolean | No | Include each document's text in the results. Defaults to `false` | Other fields are rejected. Streaming isn't supported. Each query and document pair can use up to 32,768 tokens, and a request up to 300,000. These checks are a conservative estimate based on text size in bytes. ## Response | Field | Description | | - | - | | `results[].index` | The document's zero-based position in your `documents` array | | `results[].relevance_score` | A raw score where higher means more relevant. It's a logit, not a probability, and can be negative | | `results[].document.text` | The document's text, if you set `return_documents` | | `usage` | `prompt_tokens` and `total_tokens` | Results are sorted by descending score, and tied scores keep their original order. ## Pricing \$0.05 per million input tokens. Every document is scored and billed, including those `top_n` leaves out. The `x-nanogpt-cost-usd` response header shows the cost of the request. ## Errors | Status | Meaning | | - | - | | 400 | An invalid parameter, or `context_length_exceeded` or `input_batch_too_large` when a limit above is exceeded | | 401 | The API key is missing or invalid | | 404 | The model wasn't found | | 429 | A [rate limit](/api-reference/miscellaneous/rate-limits) was reached | | 503 | The service is temporarily unavailable. Retry | # Responses Source: https://docs.nano-gpt.com/api-reference/endpoint/responses POST /v1/responses Create a response with the OpenAI-compatible Responses API. Compatible models can use the Responses-only hosted tool-search pilot by adding a nanogpt:tool_search or tool_search entry and marking function tools with defer_loading: true. The NanoGPT Advisor extension is available for non-streaming, foreground, platform-billed pay-as-you-go API-key requests that do not use client tools, structured output, inline moderation, BYOK, accountless payment, memory, or server-side content enhancements. > [!NOTE] > > These examples use the direct API host, `https://api.nano-gpt.com`. It has no IPv6 address, so clients with only IPv6 should use `https://nano-gpt.com` with the same paths. See [API Hosts](/api-reference/miscellaneous/api-hosts). > [!NOTE] > > To set reasoning effort through a custom model ID, append `:reasoning-effort/high` (also `none`, `low`, `medium`, `xhigh`, or `max`). NanoGPT strips the suffix before routing and uses it as the default `reasoning.effort`. `:reasoning-effort/none` requests disabled reasoning where the model supports it. Explicit body generation settings, including enabled thinking, take precedence over `none`. The suffix does not bypass model/provider restrictions. See [Reasoning Effort Suffixes](/api-reference/miscellaneous/model-suffixes#reasoning-effort-suffixes). > [!NOTE] > > `/v1/responses` accepts **compressed request bodies** (`Content-Encoding: gzip`, `deflate`, or `br`) on authenticated JSON requests — useful for long conversations, where compressed uploads cut time-to-first-token. See [Compressed Request Bodies](/api-reference/miscellaneous/request-compression). ## Overview The `/v1/responses` API is an OpenAI Responses API-compatible endpoint for creating AI model responses. It supports: * Stateless and stateful (conversation threading) chat completions * Streaming responses via Server-Sent Events (SSE) * Background (async) processing for long-running requests * Response storage and retrieval * Function/tool calling support * Multimodal inputs (images, video, files) for supported models > [!NOTE] > > Decision models (Jev, Liquid D1, PPLX Decider v1.2, Clef and Clef Flash) use `text.format: {"type":"questions","questions":{...}}`, accept only non-streaming user text, and return the answer object as JSON text in `output_text`. `usage.estimated_cost` is returned by default; send `include_usage: true` for the exact `usage.cost`. See [Decisions](/api-reference/endpoint/decisions) for complete examples and limitations. > [!NOTE] > > **Large request bodies:** The examples below use `https://api.nano-gpt.com/api/v1`, which takes request bodies up to 32 MiB (compressed and decompressed). `https://nano-gpt.com` has an edge limit of about 4.5 MB per request, compressed or not; use `https://api.nano-gpt.com` for large requests. Long-running agents may need the direct host and a model available there. > [!NOTE] > > **Accountless x402 payments**: Non-streaming `POST /api/v1/responses` requests can be quoted without an account or API key on supported deployments when the initial quote request includes `x-x402: true`. Streaming and background Responses have implementation coverage but are not part of the stable public accountless contract. This endpoint supports accountless x402 payments where listed by `GET /api/v1/x402/endpoints`, including Lightning L402 when advertised. See [Accountless x402 API Payments](/api-reference/miscellaneous/x402) for the full flow. > [!NOTE] > > Provider selection is available for supported open-source models. `X-Provider` explicitly selects a provider for the request and is always billed pay-as-you-go at the selected provider's price, including provider-selection markup. For provider-selection-capable models, `model` may include routing preference suffixes such as `:fast` (alias for `:speed`) and `:cheap` (alias for `:price`). These are billed like explicit provider selection and follow the same conflict rules. For subscription users, sending `X-Provider` bypasses subscription coverage for that request; `X-Billing-Mode: paygo` is only needed when forcing pay-as-you-go without an explicit provider or when saved provider preferences should apply to subscription-included traffic. See [Provider Selection](/api-reference/miscellaneous/provider-selection), [Model Suffixes](/api-reference/miscellaneous/model-suffixes), and [Pay-As-You-Go Billing Override](/api-reference/miscellaneous/billing-override). > [!NOTE] > > **Advisor extension:** Non-streaming pay-as-you-go API-key requests can include an `advisor` object so the executor model can consult one different model before returning its final answer. Use `mode: "auto"` to let the executor decide or `mode: "required"` to require a consultation attempt. Each completed model phase is billed separately. Advisor is a NanoGPT extension, not part of the standard OpenAI request schema. See [Advisor](/api-reference/miscellaneous/advisor). > [!NOTE] > > **Hosted tool search:** Compatible models can discover relevant functions from large deferred catalogs. Add `nanogpt:tool_search` and mark functions with `defer_loading: true`. This pilot is Responses-only. See [Hosted tool search](/api-reference/miscellaneous/hosted-tool-search). ## Authentication Use an API key for normal authenticated billing: ``` Authorization: Bearer YOUR_API_KEY ``` Or alternatively: ``` x-api-key: YOUR_API_KEY ``` For API-key requests, you can optionally pass `x-team-id` to choose team context when team defaults are evaluated (for example, retention defaults). For supported accountless x402 requests, omit `Authorization` and `x-api-key`, and include `x-x402: true` to receive a payment quote. The advertised schemes, including Lightning L402 when enabled, are listed by `GET /api/v1/x402/endpoints`. If you receive `401 missing_api_key` immediately, check that the initial quote request includes `x-x402: true`. Without that header, NanoGPT does not enter the x402 quote flow. ## Endpoints * `POST /v1/responses` - Create a new response from the model * `GET /v1/responses` - Returns endpoint information * `GET /v1/responses/{id}` - Retrieve a stored response by ID * `DELETE /v1/responses/{id}` - Delete a stored response (soft delete) ## Batch processing For high-volume work that does not need an immediate response, `/v1/responses` requests can be submitted through the [Batch API](/api-reference/endpoint/batches). Responses batches are non-streaming, stateless, use direct OpenAI models, and run with `store: false`. Function and custom tools, structured text output, and remote or data-URL images are supported; video input remains unsupported in Responses Batch. Stateful features, provider-hosted tools, file references, and NanoGPT-only request extensions are not. ## BYOK Encryption (Stored Responses) If you set `store: true`, you can optionally encrypt the stored response at rest using your own key or passphrase. To encrypt a stored response, include one of these headers on `POST /v1/responses`: * `x-encryption-key: YOUR_ENCRYPTION_KEY` * `x-encryption-passphrase: YOUR_PASSPHRASE` When retrieving or deleting an encrypted response, include the same header you used at creation time. Example: ```bash theme={null} # Create an encrypted, stored response curl -X POST https://api.nano-gpt.com/api/v1/responses \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -H "x-encryption-key: YOUR_ENCRYPTION_KEY" \ -d '{ "model": "openai/gpt-6.1-sol", "input": "Sensitive information", "store": true }' # Retrieve it later (must include the same encryption header) curl https://api.nano-gpt.com/api/v1/responses/resp_abc123 \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "x-encryption-key: YOUR_ENCRYPTION_KEY" ``` ## Create Response ### Request ```http theme={null} POST /v1/responses Content-Type: application/json Authorization: Bearer YOUR_API_KEY ``` ### Request Body For [inline reasoning effort updates](/api-reference/miscellaneous/inline-reasoning-effort), keep the request-level `reasoning.effort` constant. A trailing update controls the current response; preserve its position when replaying output or continuing with `previous_response_id`. Adjacent updates, automatic truncation, and `reasoning.exclude: true` are unsupported with these updates. | Parameter | Type | Required | Description | | - | - | - | - | | `model` | string | Yes, unless `models` is sent | Model ID to use for the response. Provider-selection-capable models may include routing preference suffixes such as `:fast`, `:speed`, `:cheap`, `:price`, `:latency`, `:throughput`, `:floor`, `:tools`, `:caching`, `:cache`, or `:cached`. | | `models` | string\[] | No | Models to try in order if one fails before any output is sent. `model` goes first. At most 4 in total. The model that answered is billed, and so is a failed attempt its provider charged for. With two or more different models it needs an API key and can't be combined with `background: true`. See [Model fallbacks](/api-reference/miscellaneous/provider-selection#model-fallbacks). | | `provider` | string or object | No | Provider selection controls for this request. See [Provider controls on Responses and Messages](/api-reference/miscellaneous/provider-selection#provider-controls-on-responses-and-messages), including which controls return an error on a native route. | | `input` | string or array | Yes | The input prompt or array of input items. Astra and Fable 5.1 also accept [inline reasoning effort updates](/api-reference/miscellaneous/inline-reasoning-effort) as `configuration_update` items. | | `advisor` | object | No | NanoGPT extension that lets the executor consult one different, client-selected model. Initially limited to non-streaming, pay-as-you-go API-key requests. See [Advisor](/api-reference/miscellaneous/advisor). | | `instructions` | string | No | System instructions for the model | | `max_output_tokens` | integer | No | Maximum tokens in the response (minimum: 16) | | `max_tool_calls` | integer | No | Maximum number of built-in tool calls, such as web searches and page opens, in one response. Support depends on the route. On GPT and o-series models with native web search (a `{ "type": "web_search" }` tool or an `:online` suffix), calls past the cap are not run or billed. Without it, native search is capped at 5 calls, except on instant chat variants and deep-research models | | `temperature` | number | No | Sampling temperature (0-2). If omitted, NanoGPT does not force a value and the routed provider/model default applies (OpenAI defaults to 1.0). Not supported by reasoning-capable models | | `top_p` | number | No | Nucleus sampling parameter. Not supported by reasoning-capable models | | `presence_penalty` | number | No | Presence penalty for sampling (-2.0 to 2.0) | | `frequency_penalty` | number | No | Frequency penalty for sampling (-2.0 to 2.0) | | `top_logprobs` | integer | No | Number of top logprobs to return (0-20) | | `tools` | array | No | Array of tools available to the model. Compatible models can use [hosted tool search](/api-reference/miscellaneous/hosted-tool-search) with deferred function definitions. | | `tool_choice` | string or object | No | Tool use: `auto`, `none`, `required`, `{ type: "function", name: "..." }`, or `{ type: "allowed_tools", ... }` | | `parallel_tool_calls` | boolean | No | Allow multiple tool calls in parallel | | `stream` | boolean | No | Enable streaming responses (default: false) | | `stream_options` | object | No | Streaming options: `{ include_obfuscation?: boolean }` | | `store` | boolean | No | Store the response locally for later retrieval/threading/background processing. Set `false` to disable stored Responses API data for the request. | | `retention_days` | integer or null | No | Per-request retention override in days (`0..365`). `null` means no request-level override | | `retentionDays` | integer or null | No | Alias for `retention_days`. If both are sent, values must match | | `previous_response_id` | string | No | Link to previous response for conversation threading | | `reasoning` | object | No | Reasoning configuration. Setting `reasoning.effort` to any non-`none` value explicitly requests reasoning mode. | | `text` | object | No | Text output configuration (format + verbosity) | | `metadata` | object | No | Custom metadata (max 16 keys, 64 char keys, 512 char values) | | `truncation` | string | No | Truncation strategy: `auto` or `disabled` | | `user` | string | No | Unique user identifier | | `seed` | integer | No | Optional integer forwarded on model/provider routes that support seeded sampling. This may improve reproducibility but does not guarantee identical output. Results can change if NanoGPT selects a different automatic or fallback route, or if the provider changes its backend. | | `conversation` | object | No | Conversation context: `{ id?: string, messages?: InputItem[] }` | | `include` | string\[] | No | Additional fields to include in response | | `safety_identifier` | string | No | Safety tracking identifier | | `prompt_cache_key` | string | No | Key for prompt caching | | `background` | boolean | No | Enable background/async processing | | `service_tier` | string | No | Service tier: `"auto"`, `"default"`, `"flex"`, `"fast"`, or the legacy `"priority"` alias. See [Service tiers (Flex and Fast/Priority)](#service-tiers-priority) near the end. | ### Reproducibility guidance Seeded generation is best-effort. To reduce avoidable variation: * Keep the exact model, input, instructions, tools, and sampling settings unchanged. * Select a specific provider where possible. * Disable automatic fallbacks where supported when route consistency matters. * Use a low or zero `temperature` where supported. * Do not treat seeded output as byte-identical. Record provider, route, and system-fingerprint metadata when NanoGPT exposes reliable values. NanoGPT will publish a seed-support matrix when reliable route-level capability data is available. Until then, do not infer seed support from endpoint compatibility alone. ### Response Storage And Retention NanoGPT supports local Responses API storage for features that need server-side state, including response retrieval, `previous_response_id` threading, and background processing. Set `store: false` to disable stored Responses API data for a request: ```json theme={null} { "model": "gpt-5.2", "input": "Hello", "store": false } ``` When response storage is enabled and no override applies, stored Responses API records are retained for up to 7 days. You can override retention per request with either `retentionDays` or `retention_days`: ```json theme={null} { "model": "gpt-5.2", "input": "Hello", "store": true, "retentionDays": 3 } ``` or: ```json theme={null} { "model": "gpt-5.2", "input": "Hello", "store": true, "retention_days": 3 } ``` A retention value of `0` means do not retain stored response data for that request: ```json theme={null} { "model": "gpt-5.2", "input": "Hello", "store": true, "retentionDays": 0 } ``` Valid per-request retention values are integers from `0` to `365` days, or `null` to use the next configured default. If both `retentionDays` and `retention_days` are sent, they must match. Team and user defaults are configurable through API endpoints, not the main web Settings page today. Team owners/admins can set `responses_retention_days` with `PATCH /api/teams/{teamUuid}/settings`; users can set `responsesRetentionDays` with `POST /api/user/responses-retention`. See [Teams: response retention defaults](/api-reference/teams#user-response-retention-default). ### Retention Resolution Effective retention for `/v1/responses` resolves in this order: 1. Request override (`retention_days` / `retentionDays`) 2. Team setting (`responses_retention_days`) 3. User setting (`responsesRetentionDays`) 4. Platform default (`7` days) Rules: * `retention_days` and `retentionDays` accept integer values `0..365`, or `null`. * `null` means "no request override" and falls back to team/user/platform defaults. * If both request fields are provided, they must match. * Invalid retention values return `400` with `invalid_request_error`. * `0` enables zero-retention behavior for that request. * Existing clients that omit retention fields keep default behavior (team/user/platform retention resolution). With effective retention `0`: * `previous_response_id` is rejected. * `background` is rejected. API-key team context for retention defaults: * If `x-team-id` is present and the caller is a member, that team is used. * Otherwise, the API uses the caller session's default team (`default_team_uuid` / `default_team_id`) when membership is valid. ### Input Types The `input` parameter accepts either a simple string or an array of input items. #### Simple String Input ```json theme={null} { "model": "openai/gpt-6.1-sol", "input": "What is the capital of France?" } ``` #### Array Input ```json theme={null} { "model": "openai/gpt-6.1-sol", "input": [ { "type": "message", "role": "user", "content": "What is the capital of France?" } ] } ``` ### Input Item Types | Type | Description | | - | - | | `message` | A message with role and content | | `function_call` | A tool/function call made by the model | | `function_call_output` | The result of a tool/function call | | `custom_tool_call` | A custom tool call made by the model | | `custom_tool_call_output` | The result of a custom tool call | | `reasoning` | A reasoning item returned by the model and replayed as conversation history | | `item_reference` | A reference to a stored response output item | | `mcp_list_tools` | A list of tools returned by an MCP server | | `mcp_call` | An MCP tool call returned by the model | | `additional_tools` | A Responses Lite tool-catalog update | | `configuration_update` | An inline reasoning-effort update for supported models | | `web_search_call` | A provider web-search call replayed from a previous response | | `web_extractor_call` | A provider web-extraction call replayed from a previous response | | `image_generation_call` | A provider image-generation call replayed from a previous response | | `computer_call` | A provider computer-use call replayed from a previous response | | `computer_call_output` | The screenshot result of a computer-use call | | `file_search_call` | A provider file-search call replayed from a previous response | | `code_interpreter_call` | A provider code-interpreter call replayed from a previous response | Hosted-tool call items are provider-owned history records. Send them back unchanged, including their `id`, `status`, and provider-specific fields, and continue with the same compatible native Responses model. NanoGPT rejects invented or incomplete envelopes and returns `hosted_tool_history_model_not_supported` when the selected model/provider cannot consume that history type. #### Message Item ```json theme={null} { "type": "message", "role": "user", "content": "Hello, how are you?" } ``` Supported roles: `user`, `assistant`, `system`, `developer` Content can be a string or an array of content parts: ```json theme={null} { "type": "message", "role": "user", "content": [ { "type": "input_text", "text": "What's in this image?" }, { "type": "input_image", "image_url": "https://example.com/image.jpg" } ] } ``` ### Content Part Types | Type | Description | | - | - | | `input_text` | Text input | | `input_image` | Image input (via URL or file_id) | | `input_video` | Video input (via HTTPS URL or video data URL) | | `input_file` | File input | | `output_text` | Text output (includes annotations/logprobs) | | `refusal` | Model refusal | #### Image Input ```json theme={null} { "type": "input_image", "image_url": "https://example.com/image.jpg", "detail": "auto" } ``` The `detail` parameter can be: `auto`, `low`, or `high`. For many or large images, prefer public HTTPS URLs over inline base64 data. See [Image Input](/api-reference/endpoint/chat-completion#image-input) for the 32 MiB request limit on `https://api.nano-gpt.com` (compressed and decompressed) and when to send images inline. `https://nano-gpt.com` has an edge limit of about 4.5 MB per request, compressed or not; use `https://api.nano-gpt.com` for large requests. #### Video Input Use `input_video` for video understanding on a model that advertises video input: ```json theme={null} { "model": "google/gemini-3.1-flash-lite", "input": [{ "type": "message", "role": "user", "content": [ { "type": "input_text", "text": "Summarize the action." }, { "type": "input_video", "video_url": "data:video/mp4;base64,AAAA..." } ] }] } ``` `video_url` may be a public HTTPS URL or a valid `data:video/*;base64,...` URL. Chat-style `video_url` content parts are accepted as a compatibility alias, but `input_video` is the canonical Responses shape. `input_file` is treated as video only when NanoGPT can safely identify it from a `video/*` MIME type, video data URL, or recognized video filename/URL extension. PDFs, audio files, and unknown or opaque files are not silently treated as video. An opaque `file_id` is not resolved for Responses video input; it returns `video_file_id_not_supported`. Video is currently rejected in Responses Batch. Segment offsets are validated but no current public text-model route can honor them; valid offsets return `video_segment_not_supported`. #### Function Call Item ```json theme={null} { "type": "function_call", "id": "fc_123", "call_id": "call_abc123", "name": "get_weather", "arguments": "{\"location\": \"Paris\"}" } ``` #### Function Call Output Item ```json theme={null} { "type": "function_call_output", "call_id": "call_abc123", "output": "{\"temperature\": 22, \"condition\": \"sunny\"}" } ``` #### Stateless Output Replay Clients that use `store: false` and do not use `previous_response_id` can replay the response `output` items in the next request. Preserve output items such as `reasoning` and `web_search_call`; NanoGPT accepts them as ordered conversation history for compatible native Responses models. ```json theme={null} { "model": "openai/gpt-5.6-luna", "store": false, "tools": [ { "type": "web_search", "external_web_access": false } ], "input": [ { "type": "message", "role": "user", "content": [{ "type": "input_text", "text": "Find the latest result." }] }, { "type": "web_search_call", "id": "ws_123", "status": "completed", "action": { "type": "search", "query": "latest result" } }, { "type": "message", "id": "msg_123", "role": "assistant", "status": "completed", "content": [{ "type": "output_text", "text": "Here is the result." }] }, { "type": "message", "role": "user", "content": [{ "type": "input_text", "text": "Continue." }] } ] } ``` In practice, append the provider-returned `output` array rather than constructing hosted-tool call items yourself. ## Tools Provide function tools and built-in tools the model can use: ### Function Tool Define functions that the model can call: ```json theme={null} { "model": "openai/gpt-6.1-sol", "input": "What's the weather in Paris?", "tools": [ { "type": "function", "name": "get_weather", "description": "Get current weather for a location", "parameters": { "type": "object", "properties": { "location": { "type": "string", "description": "City name" } }, "required": ["location"] }, "strict": false } ], "tool_choice": "auto" } ``` A request can declare up to 1,024 tools, counting `tools` and any `additional_tools` input items, with up to 1 MiB (1,048,576 bytes) of tool JSON. Larger catalogs return a 400 with `too_many_tools` or `tool_spec_too_large`. For bigger catalogs, use hosted tool search. ### Hosted Tool Search For large function catalogs, add one `nanogpt:tool_search` entry (or its `tool_search` alias) and mark discoverable functions with `defer_loading: true`: ```json theme={null} { "model": "openai/gpt-5.5", "input": "Find the weather in Amsterdam", "tools": [ { "type": "nanogpt:tool_search", "max_results": 5 }, { "type": "function", "name": "weather_forecast", "description": "Get the weather forecast for a city", "parameters": { "type": "object", "properties": { "city": { "type": "string" } }, "required": ["city"] }, "defer_loading": true } ], "tool_choice": "auto" } ``` The search activity is returned as `tool_search_call`. A selected function is still returned as a normal `function_call`; your client executes it and sends `function_call_output`. Deferred functions don't count toward the 1,024-tool and 1 MiB limits; the whole `tools` array can hold up to 2,000 entries. See [Hosted tool search](/api-reference/miscellaneous/hosted-tool-search) for limits, billing, authorization, and compatibility. ### Web Search Tool ```json theme={null} { "type": "web_search", "external_web_access": false, "search_context_size": "low", "user_location": { "type": "approximate", "country": "US", "city": "San Francisco", "region": "California" } } ``` `external_web_access: false` selects offline/cache-only search; it does **not** disable the tool. The model can still search cached or indexed content and return `web_search_call` items. Omit the web-search tool when you need to disable search entirely. If `external_web_access` is omitted, live access is enabled by default. The legacy `web_search_preview` variants ignore this field and behave as though it were `true`. ### File Search Tool ```json theme={null} { "type": "file_search", "vector_store_ids": ["vs_..."], "max_num_results": 10, "ranking_options": { "ranker": "auto", "score_threshold": 0.5 } } ``` ### Code Interpreter Tool ```json theme={null} { "type": "code_interpreter", "container": { "type": "auto" } } ``` ### MCP Tool ```json theme={null} { "type": "mcp", "server_label": "my-server", "server_url": "https://...", "headers": { "Authorization": "Bearer ..." }, "require_approval": "auto" } ``` ### Image Generation Tool ```json theme={null} { "type": "image_generation" } ``` ### Tool Choice Use `allowed_tools` to restrict which tools the model may choose from: ```json theme={null} { "tool_choice": { "type": "allowed_tools", "tools": [{ "type": "function", "name": "get_weather" }], "mode": "auto" } } ``` ### Function Tool Normalization Function tools in responses always include nullable fields: ```json theme={null} { "type": "function", "name": "get_weather", "description": null, "parameters": null, "strict": null } ``` ## Reasoning Configuration Use `reasoning` to control depth and visibility of reasoning output: ```json theme={null} { "model": "anthropic/claude-opus-4.5", "input": "Solve this complex problem...", "reasoning": { "effort": "high", "summary": "auto" } } ``` | Parameter | Values | Description | | - | - | - | | `effort` | `none`, `minimal`, `low`, `medium`, `high`, `xhigh` | Reasoning depth. Any value other than `none` explicitly requests reasoning mode. | | `summary` | `none`, `auto`, `detailed`, `concise` | Reasoning summary format | | `exclude` | `true`, `false` | Controls output visibility (hides reasoning fields/blocks). It does not inherently disable reasoning compute. | ## Text/Format Configuration Control response format and verbosity: ```json theme={null} { "model": "openai/gpt-6.1-sol", "input": "List 3 colors", "text": { "format": { "type": "json_object" }, "verbosity": "medium" } } ``` ### Text Parameter Structure ```json theme={null} { "format": { "type": "text" } | { "type": "json_object" } | { "type": "json_schema", "json_schema": { ... } }, "verbosity": "low" | "medium" | "high" } ``` ### Format Types * `{ "type": "text" }` - Plain text (default) * `{ "type": "json_object" }` - JSON object output * `{ "type": "json_schema", "json_schema": { ... } }` - Structured JSON with schema ### Verbosity Values * `low` - Short, compact responses * `medium` - Balanced detail * `high` - Most detailed output ### JSON Schema Format ```json theme={null} { "text": { "format": { "type": "json_schema", "json_schema": { "name": "color_list", "schema": { "type": "object", "properties": { "colors": { "type": "array", "items": { "type": "string" } } } }, "strict": true } } } } ``` ## Response Format ### Successful Response ```json theme={null} { "id": "resp_abc123", "object": "response", "created_at": 1699000000, "completed_at": 1699000001, "model": "openai/gpt-6.1-sol", "status": "completed", "instructions": null, "previous_response_id": null, "tools": [], "tool_choice": "auto", "parallel_tool_calls": false, "truncation": "disabled", "text": { "format": { "type": "text" }, "verbosity": "medium" }, "reasoning": null, "temperature": 1, "top_p": 1, "presence_penalty": 0, "frequency_penalty": 0, "top_logprobs": 0, "max_output_tokens": null, "max_tool_calls": null, "user": null, "store": true, "background": false, "safety_identifier": null, "prompt_cache_key": null, "output": [ { "type": "message", "id": "msg_xyz789", "role": "assistant", "status": "completed", "content": [ { "type": "output_text", "text": "The capital of France is Paris.", "annotations": [], "logprobs": [] } ] } ], "output_text": "The capital of France is Paris.", "usage": { "input_tokens": 15, "output_tokens": 10, "total_tokens": 25, "input_tokens_details": { "cached_tokens": 0 }, "output_tokens_details": { "reasoning_tokens": 0 } }, "metadata": {}, "service_tier": "auto" } ``` ### Response Fields All fields below are always present; nullable values indicate an option was not set. | Field | Type | Description | | - | - | - | | `id` | string | Unique response identifier (format: `resp_*`) | | `object` | string | Always `"response"` | | `created_at` | integer | Unix timestamp of creation | | `completed_at` | integer or null | Unix timestamp when response completed | | `model` | string | Model used for the response | | `status` | string | Response status | | `instructions` | string or null | System instructions used | | `previous_response_id` | string or null | ID of previous response in conversation | | `tools` | array | Tools available (normalized with nullable fields) | | `tool_choice` | string or object | Tool choice setting used | | `parallel_tool_calls` | boolean | Whether parallel tool calls were enabled | | `truncation` | string | Truncation strategy: `auto` or `disabled` | | `text` | object | Resolved text configuration | | `reasoning` | object or null | Reasoning configuration | | `temperature` | number | Temperature used | | `top_p` | number | Top-p value used | | `presence_penalty` | number | Presence penalty used | | `frequency_penalty` | number | Frequency penalty used | | `top_logprobs` | number | Top logprobs setting | | `max_output_tokens` | integer or null | Max output tokens setting | | `max_tool_calls` | integer or null | Max tool calls setting | | `user` | string or null | User identifier | | `store` | boolean | Whether response was stored | | `background` | boolean | Whether processed in background | | `safety_identifier` | string or null | Safety identifier | | `prompt_cache_key` | string or null | Prompt cache key | | `output` | array | Array of output items | | `output_text` | string | Convenience field with concatenated text output | | `usage` | object | Token usage statistics | | `error` | object | Error details (if status is `failed`) | | `incomplete_details` | object | Details if status is `incomplete` | | `metadata` | object | Custom metadata (if provided) | | `service_tier` | string | Service tier used (echoed when provided) | ### Usage Object The `usage` object always includes token details: ```json theme={null} { "input_tokens": 100, "output_tokens": 50, "total_tokens": 150, "input_tokens_details": { "cached_tokens": 0 }, "output_tokens_details": { "reasoning_tokens": 0 } } ``` ### Response Status Values | Status | Description | | - | - | | `queued` | Background request is queued | | `in_progress` | Request is being processed | | `completed` | Request completed successfully | | `incomplete` | Response was truncated | | `failed` | Request failed with error | | `cancelled` | Request was cancelled | ### `reasoning` Response Field ```json theme={null} { "effort": "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | null, "summary": "none" | "auto" | "detailed" | "concise" | null } ``` ### `text` Response Field (Resolved) ```json theme={null} { "format": { "type": "text" | "json_object" | "json_schema", "...": "..." }, "verbosity": "low" | "medium" | "high" | undefined } ``` ### Output Item Types All output items include a `status` field. #### Message Output ```json theme={null} { "type": "message", "id": "msg_123", "role": "assistant", "status": "completed", "content": [ { "type": "output_text", "text": "Response text here", "annotations": [], "logprobs": [] } ] } ``` #### Function Call Output ```json theme={null} { "type": "function_call", "id": "fc_123", "call_id": "call_abc", "name": "get_weather", "arguments": "{\"location\": \"Paris\"}", "status": "completed" } ``` #### Hosted Tool Search Call ```json theme={null} { "type": "tool_search_call", "id": "ts_123", "status": "completed" } ``` This item records discovery activity. It does not execute or approve a client function. A revealed function selected by the model appears separately as `function_call`. #### Reasoning Output (reasoning-capable models) ```json theme={null} { "type": "reasoning", "id": "reasoning_123", "status": "completed", "summary": [ { "type": "summary_text", "text": "I analyzed the problem by..." } ], "content": [ { "type": "reasoning_text", "text": "Detailed reasoning goes here." } ], "encrypted_content": null } ``` #### Web Search Call Output ```json theme={null} { "type": "web_search_call", "id": "ws_123", "status": "completed", "action": { "query": "search query" }, "results": [{ "url": "...", "title": "...", "snippet": "..." }] } ``` #### Image Generation Call Output ```json theme={null} { "type": "image_generation_call", "id": "ig_123", "status": "completed", "result": { "b64_json": "...", "url": "...", "revised_prompt": "..." } } ``` #### Computer Call Output ```json theme={null} { "type": "computer_call", "id": "cc_123", "call_id": "call_abc123", "status": "completed", "action": { "type": "click" }, "pending_safety_checks": [{ "id": "...", "code": "...", "message": "..." }] } ``` ### Output Item Status Values | Status | Description | | - | - | | `completed` | Item finished successfully | | `in_progress` | Item still being generated | | `incomplete` | Item was truncated/interrupted | ### Output Text Parts Output text parts include annotations and logprobs: ```json theme={null} { "type": "output_text", "text": "Hello world", "annotations": [], "logprobs": [ { "token": "Hello", "logprob": -0.5, "bytes": [72, 101, 108, 108, 111], "top_logprobs": [ { "token": "Hello", "logprob": -0.5, "bytes": [72, 101, 108, 108, 111] }, { "token": "Hi", "logprob": -1.2, "bytes": [72, 105] } ] } ] } ``` ### Annotation Types #### URL Citation ```json theme={null} { "type": "url_citation", "start_index": 0, "end_index": 10, "url": "https://...", "title": "Page Title" } ``` #### File Citation ```json theme={null} { "type": "file_citation", "start_index": 0, "end_index": 10, "file_id": "file_..." } ``` #### File Path ```json theme={null} { "type": "file_path", "start_index": 0, "end_index": 10, "file_id": "file_..." } ``` ## Streaming See also: [Streaming Protocol (SSE)](/api-reference/miscellaneous/streaming-protocol). Enable streaming to receive incremental response updates: ```json theme={null} { "model": "openai/gpt-6.1-sol", "input": "Write a short story", "stream": true } ``` ### Streaming Response The response is delivered as Server-Sent Events (SSE): ``` data: {"type":"response.created","response":{...},"sequence_number":0} data: {"type":"response.in_progress","response":{...},"sequence_number":1} data: {"type":"response.output_item.added","output_index":0,"item":{...},"sequence_number":2} data: {"type":"response.output_text.delta","item_id":"msg_...","output_index":0,"content_index":0,"delta":"The ","logprobs":[...],"sequence_number":3} data: {"type":"response.output_text.delta","item_id":"msg_...","output_index":0,"content_index":0,"delta":"capital ","logprobs":[...],"sequence_number":4} data: {"type":"response.output_text.done","item_id":"msg_...","output_index":0,"content_index":0,"text":"The capital of France is Paris.","logprobs":[...],"sequence_number":10} data: {"type":"response.completed","response":{...},"sequence_number":11} data: [DONE] ``` ### Streaming Event Types | Event | Description | | - | - | | `response.created` | Response object created | | `response.in_progress` | Processing started | | `response.output_item.added` | New output item started | | `response.output_item.done` | Output item completed | | `response.content_part.added` | Content part started | | `response.content_part.done` | Content part completed | | `response.output_text.delta` | Incremental text chunk | | `response.output_text.done` | Text content completed | | `response.reasoning.delta` | Incremental reasoning text | | `response.reasoning.done` | Reasoning content completed | | `response.function_call_arguments.delta` | Incremental function arguments | | `response.function_call_arguments.done` | Function call completed | | `response.completed` | Response completed successfully | | `response.incomplete` | Response truncated | | `response.failed` | Response failed | ### Updated Event Fields * All content/output events include `item_id` for the parent output item. * Text delta/done events include `logprobs`. Example `response.output_text.delta`: ```json theme={null} { "type": "response.output_text.delta", "item_id": "msg_...", "output_index": 0, "content_index": 0, "delta": "Hello", "logprobs": [...], "sequence_number": 5 } ``` ## Conversation Threading Chain responses together for multi-turn conversations. You can use `previous_response_id` or the `conversation` object (`id` or `messages`) to manage context. ### First Request ```json theme={null} { "model": "openai/gpt-6.1-sol", "input": "My name is Alice." } ``` Response includes `id`: `"resp_abc123"` ### Follow-up Request ```json theme={null} { "model": "openai/gpt-6.1-sol", "input": "What is my name?", "previous_response_id": "resp_abc123" } ``` The model has access to the conversation history and responds: "Your name is Alice." Note: `previous_response_id` requires authentication, `store: true` on previous responses, and effective retention greater than `0`. ## Background Mode For long-running requests, use background mode to receive an immediate response and poll for results. ### Initiate Background Request ```json theme={null} { "model": "openai/gpt-6.1-sol", "input": "Write a detailed analysis...", "background": true } ``` ### Immediate Response (202 Accepted) ```json theme={null} { "id": "resp_abc123", "object": "response", "created_at": 1699000000, "model": "openai/gpt-6.1-sol", "status": "queued", "output": [] } ``` ### Poll for Completion ```http theme={null} GET /v1/responses/resp_abc123 Authorization: Bearer YOUR_API_KEY ``` Keep polling until `status` is `completed`, `failed`, or `incomplete`. Constraints: * Cannot be combined with `stream: true` * Requires authentication * Effective retention must be greater than `0` * Maximum processing time: approximately 800 seconds ## Retrieve Response ```http theme={null} GET /v1/responses/{id} Authorization: Bearer YOUR_API_KEY ``` ### Response Returns the full response object (same format as POST response). ### Errors * `404` - Response not found or belongs to different account * `401` - Authentication required/invalid ## Delete Response ```http theme={null} DELETE /v1/responses/{id} Authorization: Bearer YOUR_API_KEY ``` ### Response ```json theme={null} { "id": "resp_abc123", "object": "response.deleted", "deleted": true } ``` ## Error Handling ### Error Response Format ```json theme={null} { "error": { "code": "missing_required_parameter", "message": "model is required" } } ``` ### HTTP Status Codes | HTTP Status | Description | | - | - | | `400` | Invalid request parameters | | `401` | Missing or invalid API key | | `403` | Insufficient permissions | | `404` | Resource not found | | `429` | Rate limit exceeded | | `500` | Internal server error | | `503` | Service unavailable | ### Common Error Codes | Code | Description | | - | - | | `missing_required_parameter` | Required parameter not provided | | `model_not_found` | Specified model does not exist | | `response_not_found` | Response ID not found | | `invalid_response_id` | Invalid response ID format | | `invalid_request_error` | Invalid request shape/value (for example retention out of range or mismatched alias fields) | | `authentication_required` | No API key provided | | `invalid_api_key` | API key is invalid or inactive | ## Complete Examples ### Simple Text Completion ```bash theme={null} curl -X POST https://api.nano-gpt.com/api/v1/responses \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_API_KEY" \ -d '{ "model": "openai/gpt-6.1-sol", "input": "Explain quantum computing in one sentence." }' ``` ### Multi-turn Conversation ```bash theme={null} # First turn curl -X POST https://api.nano-gpt.com/api/v1/responses \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_API_KEY" \ -d '{ "model": "openai/gpt-6.1-sol", "input": "I want to learn Python programming." }' # Second turn (using response ID from first request) curl -X POST https://api.nano-gpt.com/api/v1/responses \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_API_KEY" \ -d '{ "model": "openai/gpt-6.1-sol", "input": "Where should I start?", "previous_response_id": "resp_abc123" }' ``` ### Streaming Response ```bash theme={null} curl -X POST https://api.nano-gpt.com/api/v1/responses \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_API_KEY" \ -d '{ "model": "openai/gpt-6.1-sol", "input": "Write a haiku about programming", "stream": true }' ``` ### Per-request Retention Override ```bash theme={null} curl -X POST https://api.nano-gpt.com/api/v1/responses \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_API_KEY" \ -d '{ "model": "gpt-4o", "input": "hello", "store": true, "retention_days": 3 }' ``` ### Function Calling ```bash theme={null} curl -X POST https://api.nano-gpt.com/api/v1/responses \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_API_KEY" \ -d '{ "model": "openai/gpt-6.1-sol", "input": "What is the weather in Tokyo?", "tools": [ { "type": "function", "name": "get_weather", "description": "Get current weather for a location", "parameters": { "type": "object", "properties": { "location": { "type": "string" } }, "required": ["location"] } } ] }' ``` ### Submitting Tool Results ```bash theme={null} curl -X POST https://api.nano-gpt.com/api/v1/responses \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_API_KEY" \ -d '{ "model": "openai/gpt-6.1-sol", "input": [ { "type": "message", "role": "user", "content": "What is the weather in Tokyo?" }, { "type": "function_call", "id": "fc_1", "call_id": "call_123", "name": "get_weather", "arguments": "{\"location\": \"Tokyo\"}" }, { "type": "function_call_output", "call_id": "call_123", "output": "{\"temperature\": 18, \"condition\": \"cloudy\"}" } ] }' ``` ### Image Input (Vision) ```bash theme={null} curl -X POST https://api.nano-gpt.com/api/v1/responses \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_API_KEY" \ -d '{ "model": "openai/gpt-6.1-sol", "input": [ { "type": "message", "role": "user", "content": [ { "type": "input_text", "text": "What is in this image?" }, { "type": "input_image", "image_url": "https://example.com/photo.jpg", "detail": "auto" } ] } ] }' ``` ### Video Input (Understanding) Video input is separate from video generation and is available only on models advertising video capability. See the [Video Input guide](/api-reference/miscellaneous/video-input) for source rules, limits, YouTube behavior, and validation errors. ### JSON Output ```bash theme={null} curl -X POST https://api.nano-gpt.com/api/v1/responses \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_API_KEY" \ -d '{ "model": "openai/gpt-6.1-sol", "input": "List the planets in our solar system", "text": { "format": { "type": "json_object" } } }' ``` ### Background Processing ```bash theme={null} # Start background request curl -X POST https://api.nano-gpt.com/api/v1/responses \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_API_KEY" \ -d '{ "model": "openai/gpt-6.1-sol", "input": "Generate a comprehensive report...", "background": true }' # Poll for results curl https://api.nano-gpt.com/api/v1/responses/resp_abc123 \ -H "Authorization: Bearer YOUR_API_KEY" ``` ## Limitations 1. Deep research models: Deep research variants are not supported. 2. GPU-TEE streaming: Streaming is not supported for GPU-TEE models. Use `/v1/chat/completions` for these models. 3. Background mode: Maximum duration is approximately 800 seconds. 4. Metadata limits: Maximum 16 keys, 64 character key names, 512 character values. 5. Hosted tool search: Available only on compatible models in foreground Responses requests. It cannot currently be combined with background mode or other hosted built-ins. See [Hosted tool search](/api-reference/miscellaneous/hosted-tool-search). ## Service tiers (Flex and Fast/Priority) Set `service_tier` to request a non-default capacity tier on providers that support service tiers: * `auto` or omitted: use NanoGPT's normal routing and the provider default. * `default`: request the provider's standard tier where the provider accepts an explicit default value. * `flex`: request lower-cost, variable-capacity processing where supported. * `fast`: request lower-latency, higher-priority processing where supported. * `priority`: legacy alias for `fast` on OpenAI models; compatible non-OpenAI providers may continue to use the Priority name. Before sending a tiered request, call [`GET /api/v1/models?detailed=true`](/api-reference/endpoint/models) and inspect the selected model's `supported_service_tiers` array. The basic model list intentionally omits this field for OpenAI compatibility. An empty array means the model supports only the default tier. Behavior notes: * Service tier availability is model- and provider-specific. The detailed model API is the programmatic source of truth; [model pages](https://nano-gpt.com/models) show the same support as badges. * Flex and Fast/Priority tiers are only applied when the routed provider supports them. * Header provider overrides (like `X-Provider`) and explicit provider selection are honored for pricing and x402 estimates. * Provider-native web search can force routing; tier pricing follows that routing. * If you explicitly force a provider that does not support service tiers, the requested tier may be ignored by the upstream provider, or routing and pricing may differ from the default route. Billing note: * Flex tier billing uses flex pricing where applicable. * Fast/Priority tier billing uses the applicable higher-priority pricing. * High-context pricing may also apply for models and providers with separate high-context SKUs, such as `es2k` pricing for GPT-5.5/GPT-5.4 where available. ### Example: flex tier ```json theme={null} { "model": "openai/gpt-5.5", "input": "Say hi in one sentence.", "service_tier": "flex" } ``` ### Example: fast tier ```json theme={null} { "model": "openai/gpt-5.5", "input": "Say hi in one sentence.", "service_tier": "fast" } ``` Use `"priority"` instead only when maintaining compatibility with an older integration or a provider route that still uses that name. ## Response Headers All responses include: | Header | Description | | - | - | | `X-Request-ID` | Unique request/response identifier | | `Content-Type` | `application/json` or `text/event-stream` | # Web Scraping Source: https://docs.nano-gpt.com/api-reference/endpoint/scrape-urls POST /scrape-urls Extract clean, formatted content from web pages. Returns both raw HTML content and formatted markdown. ## Overview The NanoGPT Web Scraping API allows you to extract clean, formatted content from web pages. It uses the Firecrawl service to scrape URLs and returns both raw HTML content and formatted markdown. You can also call this tool through the unified [Data API](/api-reference/endpoint/data-api) at `POST /api/v1/data/url/scrape`. The Data API preserves this endpoint's request body, response body, billing, and validation behavior while adding discovery and dispatch metadata. ## Authentication The API supports two authentication methods: ### 1. API Key Authentication (Recommended) Include your API key in the request header: ``` x-api-key: YOUR_API_KEY ``` ### 2. Bearer Token Authentication ``` Authorization: Bearer YOUR_API_KEY ``` ## Accountless x402 Payment For accountless payment, prefer the public Data API path: ```bash theme={null} curl -i https://api.nano-gpt.com/api/v1/data/url/scrape \ -H "Content-Type: application/json" \ -H "x-x402: true" \ -d '{ "urls": ["https://nano-gpt.com"], "stealthMode": false }' ``` To request an accountless x402 quote, send the API request without `Authorization` or `x-api-key`, and include `x-x402: true`. NanoGPT will return `402 Payment Required` with available payment options. This endpoint supports accountless x402 payments where listed by `GET /api/v1/x402/endpoints`, including Lightning L402 when advertised. See [Accountless x402 API Payments](/api-reference/miscellaneous/x402) for the full flow. If you receive `401 missing_api_key` immediately, check that the initial quote request includes `x-x402: true`. Without that header, NanoGPT does not enter the x402 quote flow. ## Request Format ### Headers ``` Content-Type: application/json x-api-key: YOUR_API_KEY ``` ### Request Body ```json theme={null} { "urls": [ "https://example.com/article", "https://blog.com/post", "https://news.site.com/story" ], "stealthMode": false } ``` ### Parameters | Parameter | Type | Required | Description | | - | - | - | - | | urls | string\[] | Yes | Array of URLs to scrape. Maximum 5 URLs per request. | | stealthMode | boolean | No | Optional. Default `false`. When `true`, multiplies the upfront per-URL charge by 5 and routes requests through the stealth proxy. | | provider | string | No | Optional. `"auto"` (default) or `"linkup"`. `"linkup"` reads pages with Linkup and does not support `stealthMode`. | #### Stealth scraping (optional) Set `stealthMode: true` to run requests through Firecrawl’s stealth proxy for tougher targets. Stealth scraping costs 5× the standard per-URL rate and still counts toward the configured URL cap. The web UI exposes the same toggle, so use this field to mirror that behavior from the API. ```jsonc theme={null} POST /api/scrape-urls { "urls": ["https://example.com/restricted"], "stealthMode": true } ``` The response `summary` includes `stealthModeUsed` so you can track when the surcharge applied. ### URL Requirements * Must be valid HTTP or HTTPS URLs * Must have standard web ports (80, 443, or default) * Cannot be localhost, private IPs, or metadata endpoints * YouTube URLs are not supported (use the YouTube transcription endpoint instead) ## Response Format ### Success Response (200 OK) ```json theme={null} { "results": [ { "url": "https://example.com/article", "success": true, "title": "Article Title", "content": "Raw HTML content...", "markdown": "# Article Title\n\nFormatted markdown content..." }, { "url": "https://invalid.site.com", "success": false, "error": "Failed to scrape URL" } ], "summary": { "requested": 3, "processed": 3, "successful": 2, "failed": 1, "totalCost": 0.002, "stealthModeUsed": false } } ``` ### Response Fields #### results Array of scraping results for each URL: * `url` (string): The URL that was scraped * `success` (boolean): Whether the scraping was successful * `title` (string, optional): Page title if successfully scraped * `content` (string, optional): Raw HTML content * `markdown` (string, optional): Formatted markdown version of the content * `error` (string, optional): Error message if scraping failed #### summary Summary statistics for the request: * `requested` (number): Number of URLs in the original request * `processed` (number): Number of valid URLs that were processed * `successful` (number): Number of URLs successfully scraped * `failed` (number): Number of URLs that failed to scrape * `totalCost` (number): Total cost in USD (only for successful scrapes) * `stealthModeUsed` (boolean): Indicates whether stealth mode was enabled for any processed URLs ## Error Responses ### 400 Bad Request ```json theme={null} { "error": "Please provide an array of URLs to scrape" } ``` ### 401 Unauthorized ```json theme={null} { "error": "Invalid session" } ``` ### 402 Payment Required ```json theme={null} { "error": "Insufficient balance" } ``` ### 409 Conflict ```json theme={null} { "error": "Your saved firecrawl key could not be read. Save it again on the BYOK page or remove it.", "code": "byok_credential_unreadable" } ``` ### 429 Too Many Requests ```json theme={null} { "error": "Rate limit exceeded. Please wait before sending another request." } ``` ### 500 Internal Server Error ```json theme={null} { "error": "An error occurred while processing your request" } ``` ## Pricing * **Cost**: \$0.001 per successfully scraped URL * **Billing**: You are only charged for URLs that are successfully scraped * **Payment Methods**: USD balance or Nano (XNO) cryptocurrency * **Your own key**: If you save a Firecrawl, Berrycrawl or Linkup key on the [BYOK page](https://nano-gpt.com/byok), reads it serves are free on NanoGPT and your provider bills you directly. Balance checks skip them. See [Page reading keys](/api-reference/miscellaneous/byok#page-reading-keys). * **Note (inline chat scraping)**: Inline URL scraping inside `POST /api/v1/chat/completions` (via `scraping: true`) is billed separately at **\$0.0015 per successfully scraped URL**. Use this endpoint when you want explicit URL lists and the lower standalone price. ## Rate Limits * **Default**: 30 requests per minute per IP address * **With API Key**: 30 requests per minute per API key ## Code Examples ```bash cURL theme={null} curl -X POST https://api.nano-gpt.com/api/scrape-urls \ -H "Content-Type: application/json" \ -H "x-api-key: YOUR_API_KEY" \ -d '{ "urls": [ "https://example.com/article", "https://blog.com/post" ] }' ``` ```python Python theme={null} import requests api_key = "YOUR_API_KEY" urls = [ "https://example.com/article", "https://blog.com/post" ] response = requests.post( "https://api.nano-gpt.com/api/scrape-urls", headers={ "Content-Type": "application/json", "x-api-key": api_key }, json={"urls": urls} ) data = response.json() for result in data["results"]: if result["success"]: print(f"Title: {result['title']}") print(f"Markdown: {result['markdown'][:200]}...") else: print(f"Failed to scrape {result['url']}: {result['error']}") ``` ```javascript JavaScript/TypeScript theme={null} const apiKey = 'YOUR_API_KEY'; const urls = [ 'https://example.com/article', 'https://blog.com/post' ]; const response = await fetch('https://api.nano-gpt.com/api/scrape-urls', { method: 'POST', headers: { 'Content-Type': 'application/json', 'x-api-key': apiKey }, body: JSON.stringify({ urls }) }); const data = await response.json(); data.results.forEach(result => { if (result.success) { console.log(`Title: ${result.title}`); console.log(`Markdown: ${result.markdown.substring(0, 200)}...`); } else { console.log(`Failed to scrape ${result.url}: ${result.error}`); } }); ``` ## Best Practices 1. **Batch Requests**: Send multiple URLs in a single request (up to 5) to minimize API calls 2. **Error Handling**: Always check the `success` field for each result before accessing content 3. **Content Size**: Scraped content is limited to 100KB per URL 4. **URL Validation**: Validate URLs on your end before sending to reduce failed requests 5. **Markdown Format**: Use the markdown field for better readability and formatting ## Limitations * Maximum 5 URLs per request * Maximum content size: 100KB per URL * No JavaScript rendering (static content only) ## FAQ **Q: Why was my URL rejected?** A: URLs can be rejected for several reasons: * Invalid format (not HTTP/HTTPS) * Pointing to localhost or private IPs * Using non-standard ports * Being a YouTube URL (use the YouTube transcription endpoint) **Q: Can I scrape JavaScript-heavy sites?** A: The scraper fetches static HTML content. Sites that rely heavily on JavaScript may not return complete content. **Q: What happens if a URL fails to scrape?** A: You are not charged for failed URLs. The response will include an error message for that specific URL. **Q: Is there a sandbox/test environment?** A: You can test with your regular API key. Since you're only charged for successful scrapes, failed attempts during testing won't cost anything. # v1/audio/speech (TTS + Music) Source: https://docs.nano-gpt.com/api-reference/endpoint/speech POST https://api.nano-gpt.com/api/v1/audio/speech ## Overview Synthesize speech (TTS) or generate music with a single request. The OpenAI-compatible `POST /v1/audio/speech` endpoint returns audio bytes directly in the HTTP response. Optional chunked streaming is available with `stream: true`. In streaming mode, audio bytes are delivered progressively as generated, which reduces time-to-first-byte (TTFB) for real-time playback. Default behavior is unchanged: omit `stream` (or set `false`) to receive one buffered audio file after generation completes. When you use a music model (for example `Minimax-Music-02`), the `input` field is treated as a music prompt (not text to speak) and `voice` is ignored. For a dedicated music guide and model list, see `api-reference/music-generation.mdx`. ## Endpoint * Method/Path: `POST https://api.nano-gpt.com/api/v1/audio/speech` * Auth: `Authorization: Bearer ` * Required header: `Content-Type: application/json` ## Request Parameters | Parameter | Type | Default | Description | | - | - | - | - | | `model` | string | None | Audio-speech model ID (TTS or music). | | `input` | string | None | Text to speak (TTS) or a music prompt (music models). | | `voice` | string | None | Voice preset for TTS. Ignored for music models. If your client requires this field, pass any string (for example `"alloy"`). | | `response_format` | string | `mp3` | Output format when supported by the selected provider/model. | | `speed` | number | `1` | Speaking rate multiplier for TTS (for example `0.5`-`2.0`). Ignored for music models. | | `instructions` | string | None | Voice/style instructions (supported by some models/providers). | | `stream` | boolean | `false` | When `true`, returns chunked audio bytes progressively. | Notes: * Some provider-backed models may support additional fields; accepted parameters vary by model. * For unsupported models, `stream: true` is ignored and the endpoint returns the normal buffered response. ## Streaming Support (TTS Models) | Model | Provider | Streaming Support | | - | - | - | | `tts-1` | OpenAI | Yes | | `tts-1-hd` | OpenAI | Yes | | `gpt-4o-mini-tts` | OpenAI | Yes | | `Elevenlabs-Turbo-V2.5` | ElevenLabs (via FAL) | Yes | | `Elevenlabs-V3` | ElevenLabs (via FAL) | Yes | All other TTS models (Gemini, Inworld, Kokoro, Qwen, MiniMax, and others) ignore `stream` and return buffered responses. ## Response Behavior ### Non-streaming (default) * Status: `200 OK` * Body: complete audio file returned once generation finishes * Headers: typically includes `Content-Length` ### Streaming (`stream: true`) * Status: `200 OK` * Body: audio bytes arrive progressively in chunks * Headers: no `Content-Length`; uses `Transfer-Encoding: chunked` * Client can start playback/processing as soon as the first chunk arrives * `Content-Type` by provider: * OpenAI TTS models: matches the selected output format (for example `audio/mpeg`, `audio/wav`, `audio/opus`, `audio/flac`, `audio/aac`, `audio/pcm`) * ElevenLabs TTS models: always `audio/mpeg` ### Errors * If an error happens before streaming starts, the API returns the standard OpenAI-style JSON error envelope: ```json theme={null} { "error": { "message": "...", "type": "invalid_request_error", "param": null, "code": "invalid_request" } } ``` * If streaming fails after bytes have started, the connection is terminated and clients may receive partial/corrupt audio. Common error types: `invalid_model`, `invalid_voice`, `unsupported_format`, `input_too_long`, `rate_limit_exceeded`. ## Examples ### Non-streaming request (unchanged) ```bash theme={null} curl -X POST \ -H "Authorization: Bearer $NANOGPT_API_KEY" \ -H "Content-Type: application/json" \ https://api.nano-gpt.com/api/v1/audio/speech \ -d '{ "model": "gpt-4o-mini-tts", "input": "Hello from NanoGPT!", "voice": "alloy", "response_format": "mp3" }' \ --output speech.mp3 ``` ### Streaming request (cURL) ```bash theme={null} curl -X POST \ -H "Authorization: Bearer $NANOGPT_API_KEY" \ -H "Content-Type: application/json" \ https://api.nano-gpt.com/api/v1/audio/speech \ -d '{ "model": "gpt-4o-mini-tts", "input": "Hello, this is a streaming test with a longer message to observe progressive chunking.", "voice": "alloy", "response_format": "mp3", "stream": true }' \ --output speech.mp3 ``` ### OpenAI Node.js SDK (streaming) ```ts theme={null} import OpenAI from "openai"; import { createWriteStream } from "node:fs"; const client = new OpenAI({ apiKey: process.env.NANOGPT_API_KEY, baseURL: "https://api.nano-gpt.com/api/v1", }); const response = await client.audio.speech.create({ model: "gpt-4o-mini-tts", voice: "alloy", input: "Hello from the streaming API!", response_format: "mp3", stream: true, }); if (!response.body) throw new Error("Missing response body stream"); const out = createWriteStream("output.mp3"); const reader = response.body.getReader(); while (true) { const { done, value } = await reader.read(); if (done) break; out.write(Buffer.from(value)); } out.end(); ``` ### OpenAI Python SDK (streaming) ```python theme={null} from openai import OpenAI client = OpenAI( api_key="your-nanogpt-api-key", base_url="https://api.nano-gpt.com/api/v1", ) with client.audio.speech.with_streaming_response.create( model="gpt-4o-mini-tts", voice="alloy", input="Hello from the streaming API!", response_format="mp3", extra_body={"stream": True}, ) as response: with open("output.mp3", "wb") as f: for chunk in response.iter_bytes(chunk_size=4096): f.write(chunk) ``` ### Compare TTFB (streaming vs non-streaming) ```bash theme={null} curl -X POST https://api.nano-gpt.com/api/v1/audio/speech \ -H "Authorization: Bearer $NANOGPT_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model":"gpt-4o-mini-tts","input":"A longer sentence to demonstrate the streaming improvement.","voice":"alloy","stream":true}' \ -o streaming.mp3 \ -w "\nTTFB: %{time_starttransfer}s\nTotal: %{time_total}s\n" ``` ## Notes & Limits * Max input length: depends on model; measured in characters or tokens. For short, interactive prompts, prefer under \~1-2k characters. * Typical latency: scales with input length and output format; compressed formats like `mp3` are often faster than `wav`. * Usage metering: billed by input characters for TTS models; output file size does not affect billing. ## Audio Format Support by Provider | Provider | Supported `response_format` values | | - | - | | OpenAI (`tts-1`, `tts-1-hd`, `gpt-4o-mini-tts`) | `mp3` (default), `opus`, `aac`, `flac`, `wav`, `pcm` | | ElevenLabs (`Elevenlabs-Turbo-V2.5`, `Elevenlabs-V3`) | Always returns `audio/mpeg` (MP3). `response_format` is ignored. | ## Voices * Voice IDs vary by model/provider. See model-specific voices on Text-to-Speech: `api-reference/text-to-speech.mdx`. * `GET /api/v1/audio-models?type=tts` lists each model's voices under `supported_parameters.voices`. ## Errors & Troubleshooting * `invalid_model`, `invalid_voice`, `unsupported_format`: Verify `model`, `voice`, and `response_format`. * `input_too_long`: Reduce length; split long text into chunks and stitch audio client-side. * `rate_limit_exceeded`: Exponential backoff; retry after the window resets. * Network/client tips: set `Accept` to your preferred audio type and write raw response bytes directly to a file/stream. ## Security * Do not expose API keys in browsers. Proxy via your server. * Redact PII in logs; avoid logging raw text/audio in production. * Rate-limit public routes. ## Pricing, Quotas, and Rate Limits * Billing is based on input character count, not output audio size. * For streaming requests, billing is recorded after the first audio chunk is confirmed. If the upstream provider fails before any audio is produced, no charge is applied. * If the client disconnects mid-stream after audio starts, the charge still applies because generation already began upstream. * Rate limits: per-minute/day caps; contact support to request increases. See `api-reference/miscellaneous/pricing.mdx` and `api-reference/miscellaneous/rate-limits.mdx`. ## Migration from Job-based TTS Already using the async `POST /tts` + `GET /tts/status` flow? * When to switch: choose `v1/audio/speech` for short prompts, low latency, and direct playback; keep job-based TTS for long/batch generation and webhook workflows. * Parameter mapping: `text` -> `input`, `voice` stays `voice`, and output format can be requested with `response_format` when supported. * Retries/timeouts: `v1/audio/speech` returns inline; implement client-side timeouts and simple retries on 5xx. ## See Also * Async/job-based TTS: `api-reference/endpoint/tts.mdx` * TTS Status polling: `api-reference/endpoint/tts-status.mdx` # Subscription Usage Source: https://docs.nano-gpt.com/api-reference/endpoint/subscription-usage GET /subscription/v1/usage Read subscription token quotas and billing-routing advice for your inference API key. ## Choose the right credential For a quota widget or monitoring script, use a [Usage only management token](/api-reference/management-api). It can read subscription quotas without permission to run models or spend your balance. This endpoint uses an **inference API key** and also returns billing-routing advice specific to that key. Management tokens are accepted only at `GET /api/management/v1/subscription/usage`. ## Request * Method: `GET` * Path: `/api/subscription/v1/usage` (alias: `/api/v1/subscription/usage`) * Auth: `Authorization: Bearer ` or `x-api-key: ` ```bash theme={null} curl https://api.nano-gpt.com/api/subscription/v1/usage \ -H "Authorization: Bearer $NANOGPT_API_KEY" ``` ## Response The response includes `active`, `state`, `limits`, `dailyInputTokens`, `weeklyInputTokens`, `dailyImages`, `period`, and `routing`. See the [quota example and field definitions](/api-reference/management-api#read-subscription-usage) for the shared usage fields. The inference-authenticated response also includes subscription metadata and `allowOverage`. Input-token quotas count tokens, not operation counts or dollars. Image quotas count images. `percentUsed` is a fraction and may exceed 1. Quota `resetAt` values are UNIX epoch milliseconds; `period.currentPeriodEnd` is an ISO timestamp or null. Use returned limits and reset times instead of hardcoding them. A null quota/limit is not configured or applicable. When a lookup is unavailable, counters are null with `degraded: true`. Display **unknown**, not a full allowance. Token-based trials also include `usageUnits`, `tokenLimits`, and `tokens`. ## Billing-routing advice Use `routing.recommendedMode` when choosing between included subscription usage and pay-as-you-go billing: | Value | Meaning | | - | - | | `subscription` | This key permits subscription billing and quota is available or temporarily unknown, rather than known to be exhausted | | `paygo` | Subscription use is unavailable or exhausted and the key's policy permits paid-balance spending | | `unavailable` | Neither billing mode is usable under the known subscription and key policy | `routing.reason` explains the recommendation. `subscriptionQuotaAvailable` is `true`, `false`, or `null` (unknown). The weekly routing calculation includes the service's small enforcement allowance, so the displayed base quota can be exhausted before the recommendation switches to paid usage. The advice checks billing policy and known subscription quotas. It does not check current cash balance, consumed non-zero request/spend caps, the cost of a particular request, or provider health. The generation endpoint remains authoritative. A configured zero daily request or input-token cap makes the recommendation unavailable. `active: true` alone does not prove quota remains, and a zero cash balance does not prove included subscription tokens are exhausted. Use [Check Balance](/api-reference/endpoint/check-balance) separately when you need cash balances. Clients can reuse advice briefly, but should refresh it after quota or billing errors. Never force a subscription-only key onto paid billing. Retain the NanoGPT request ID when reporting a transient billing issue. # TEE Attestation Source: https://docs.nano-gpt.com/api-reference/endpoint/tee-attestation GET /v1/tee/attestation Fetch TEE attestation report for a model Fetch a TEE attestation report for a given model. See [TEE Verification](/api-reference/tee-verification). # TEE Signature Source: https://docs.nano-gpt.com/api-reference/endpoint/tee-signature GET /v1/tee/signature/{requestId} Fetch the signed receipt for a chat request, using its X-Receipt-Id value or response body id. The key must belong to the account that made the request. Fetch the signed receipt for a chat request executed in a TEE. See [TEE Verification](/api-reference/tee-verification). # Speech-to-Text Transcription Source: https://docs.nano-gpt.com/api-reference/endpoint/transcribe POST /transcribe Transcribe audio (and supported video formats) into text using speech recognition models. Supports multiple languages, diarization (model-dependent), and various formats. Most models return synchronous results; some models (for example Elevenlabs-STT and voice cloning workflows) return asynchronous job IDs. ## Overview The Speech-to-Text transcription endpoint converts audio files into text using state-of-the-art speech recognition models. Supports multiple languages, speaker diarization, and various audio formats. Looking for a drop-in OpenAI-compatible STT endpoint? Use `POST /api/v1/audio/transcriptions`. See `api-reference/endpoint/audio-transcriptions.mdx`. ## Supported Models * **Whisper-Large-V3**: High-accuracy transcription (\~\$0.0005/min) - Synchronous * **Wizper**: Fast and efficient transcription (\$0.01/min) - Synchronous * **Elevenlabs-STT**: Premium transcription with diarization (\$0.03/min) - Asynchronous * **gpt-4o-mini-transcribe**: Efficient OpenAI transcription (\$0.003/min) - Synchronous * **gpt-4o-mini-transcribe-2025-03-20**: Snapshot (\$0.003/min) - Synchronous * **gpt-4o-mini-transcribe-2025-12-15**: Snapshot (\$0.003/min) - Synchronous * **gpt-4o-mini-transcribe-latest**: Alias (\$0.003/min) - Synchronous * **openai-whisper-with-video**: Video-to-text transcription (\$0.06/min) - Synchronous * **qwen-voice-clone**: Voice cloning (\$0.25/run) - Asynchronous * **minimax-voice-clone**: Voice cloning (\$1.00/run) - Asynchronous ## Upload Methods ### Direct File Upload (≤3MB) ```python Python theme={null} import requests def transcribe_file(file_path): headers = {"x-api-key": "YOUR_API_KEY"} with open(file_path, 'rb') as audio_file: files = {'audio': ('audio.mp3', audio_file, 'audio/mpeg')} data = { 'model': 'Whisper-Large-V3', 'language': 'en' } response = requests.post( "https://api.nano-gpt.com/api/transcribe", headers=headers, files=files, data=data ) return response.json() result = transcribe_file("meeting.mp3") print(result['transcription']) ``` ```javascript JavaScript theme={null} const formData = new FormData(); formData.append('audio', audioFile); formData.append('model', 'Whisper-Large-V3'); formData.append('language', 'auto'); const response = await fetch('https://api.nano-gpt.com/api/transcribe', { method: 'POST', headers: { 'x-api-key': 'YOUR_API_KEY' }, body: formData }); const result = await response.json(); console.log(result.transcription); ``` ```bash cURL theme={null} curl -X POST https://api.nano-gpt.com/api/transcribe \ -H "x-api-key: YOUR_API_KEY" \ -F "audio=@meeting.mp3" \ -F "model=Whisper-Large-V3" \ -F "language=en" ``` ### URL Upload (≤500MB) ```python Python theme={null} import requests def transcribe_url(audio_url): headers = { "x-api-key": "YOUR_API_KEY", "Content-Type": "application/json" } data = { "audioUrl": audio_url, "model": "Wizper", "language": "auto" } response = requests.post( "https://api.nano-gpt.com/api/transcribe", headers=headers, json=data ) return response.json() result = transcribe_url("https://example.com/audio.mp3") print(result['transcription']) ``` ```javascript JavaScript theme={null} const response = await fetch('https://api.nano-gpt.com/api/transcribe', { method: 'POST', headers: { 'x-api-key': 'YOUR_API_KEY', 'Content-Type': 'application/json' }, body: JSON.stringify({ audioUrl: 'https://example.com/audio.mp3', model: 'Wizper', language: 'auto' }) }); const result = await response.json(); console.log(result.transcription); ``` ```bash cURL theme={null} curl -X POST https://api.nano-gpt.com/api/transcribe \ -H "x-api-key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "audioUrl": "https://example.com/audio.mp3", "model": "Wizper", "language": "auto" }' ``` ## Advanced Features - Speaker Diarization Use Elevenlabs-STT for speaker identification (asynchronous processing): ```python Python theme={null} import requests import time def transcribe_with_speakers(audio_url): headers = { "x-api-key": "YOUR_API_KEY", "Content-Type": "application/json" } # Submit transcription job data = { "audioUrl": audio_url, "model": "Elevenlabs-STT", "diarize": True, "tagAudioEvents": True } response = requests.post( "https://api.nano-gpt.com/api/transcribe", headers=headers, json=data ) if response.status_code == 202: job_data = response.json() # Poll for results status_data = { "runId": job_data['runId'], "cost": job_data.get('cost'), "paymentSource": job_data.get('paymentSource'), "isApiRequest": True } while True: status_response = requests.post( "https://api.nano-gpt.com/api/transcribe/status", headers=headers, json=status_data ) result = status_response.json() if result.get('status') == 'completed': return result elif result.get('status') == 'failed': raise Exception(f"Transcription failed: {result.get('error')}") time.sleep(5) result = transcribe_with_speakers("https://example.com/meeting.mp3") # Access speaker segments for segment in result['diarization']['segments']: print(f"{segment['speaker']}: {segment['text']}") ``` ## Language Support Supports 97+ languages with auto-detection: ```python theme={null} # Common language codes languages = { "auto": "Auto-detect", "en": "English", "es": "Spanish", "fr": "French", "de": "German", "zh": "Chinese", "ja": "Japanese", "ar": "Arabic" } ``` ## Response Examples ### Synchronous Response (most models) ```json theme={null} { "transcription": "Hello, this is a test transcription.", "metadata": { "fileName": "audio.mp3", "fileSize": 1234567, "chargedDuration": 2.5, "actualDuration": 2.5, "language": "en", "cost": 0.0012, "currency": "USD", "model": "Whisper-Large-V3" } } ``` ### Asynchronous Response (Elevenlabs-STT and voice cloning) Initial response (202): ```json theme={null} { "runId": "abc123def456", "status": "pending", "model": "Elevenlabs-STT", "cost": 0.075, "paymentSource": "USD" } ``` Final response (when completed): ```json theme={null} { "status": "completed", "transcription": "Speaker 1: Hello everyone. Speaker 2: Hi there!", "metadata": { ... }, "diarization": { "segments": [ { "speaker": "Speaker 1", "text": "Hello everyone", "start": 0.5, "end": 1.5 } ] }, "words": [ { "text": "Hello", "start": 0.5, "end": 0.9, "type": "word", "speaker_id": "speaker_0" } ] } ``` # Speech-to-Text Status Source: https://docs.nano-gpt.com/api-reference/endpoint/transcribe-status POST /transcribe/status Check the status of an asynchronous transcription job (Elevenlabs-STT). Poll this endpoint to get the transcription results when the job is completed. ## Overview Check the status of an asynchronous transcription job (Elevenlabs-STT). Poll this endpoint to get transcription results when the job is completed. ## Usage This endpoint is used with the Elevenlabs-STT model which processes transcriptions asynchronously. After submitting a transcription job, you'll receive a `runId` that you use to check the status. ```python Python theme={null} import requests import time def check_transcription_status(run_id, job_data): headers = { "x-api-key": "YOUR_API_KEY", "Content-Type": "application/json" } status_data = { "runId": run_id, "cost": job_data.get('cost'), "paymentSource": job_data.get('paymentSource'), "isApiRequest": True, "fileName": job_data.get('fileName'), "fileSize": job_data.get('fileSize'), "chargedDuration": job_data.get('chargedDuration'), "diarize": job_data.get('diarize', False) } response = requests.post( "https://api.nano-gpt.com/api/transcribe/status", headers=headers, json=status_data ) return response.json() def wait_for_completion(run_id, job_data, max_attempts=60): for attempt in range(max_attempts): result = check_transcription_status(run_id, job_data) status = result.get('status') if status == 'completed': return result elif status == 'failed': raise Exception(f"Transcription failed: {result.get('error')}") print(f"Status: {status} (attempt {attempt + 1}/{max_attempts})") time.sleep(5) raise Exception("Transcription timed out") # Usage job_data = {"runId": "abc123", "cost": 0.075, "paymentSource": "USD"} result = wait_for_completion("abc123", job_data) print(result['transcription']) ``` ```javascript JavaScript theme={null} async function checkTranscriptionStatus(runId, jobData) { const response = await fetch('https://api.nano-gpt.com/api/transcribe/status', { method: 'POST', headers: { 'x-api-key': 'YOUR_API_KEY', 'Content-Type': 'application/json' }, body: JSON.stringify({ runId: runId, cost: jobData.cost, paymentSource: jobData.paymentSource, isApiRequest: true, fileName: jobData.fileName, fileSize: jobData.fileSize, chargedDuration: jobData.chargedDuration, diarize: jobData.diarize || false }) }); return await response.json(); } async function waitForCompletion(runId, jobData, maxAttempts = 60) { for (let attempt = 0; attempt < maxAttempts; attempt++) { const result = await checkTranscriptionStatus(runId, jobData); const status = result.status; if (status === 'completed') { return result; } else if (status === 'failed') { throw new Error(`Transcription failed: ${result.error}`); } console.log(`Status: ${status} (attempt ${attempt + 1}/${maxAttempts})`); await new Promise(resolve => setTimeout(resolve, 5000)); } throw new Error('Transcription timed out'); } // Usage const jobData = {runId: "abc123", cost: 0.075, paymentSource: "USD"}; const result = await waitForCompletion("abc123", jobData); console.log(result.transcription); ``` ```bash cURL theme={null} # Check status curl -X POST https://api.nano-gpt.com/api/transcribe/status \ -H "x-api-key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "runId": "abc123def456", "cost": 0.075, "paymentSource": "USD", "isApiRequest": true, "fileName": "meeting.mp3", "fileSize": 2345678, "chargedDuration": 2.5, "diarize": true }' ``` ## Status Values * **`pending`**: Job is queued for processing * **`processing`**: Transcription is in progress * **`completed`**: Transcription finished successfully * **`failed`**: Transcription failed (check error field) ## Response Examples ### Pending/Processing ```json theme={null} { "status": "processing" } ``` ### Completed ```json theme={null} { "status": "completed", "transcription": "Speaker 1: Hello everyone. Speaker 2: Hi there!", "metadata": { "fileName": "meeting.mp3", "fileSize": 2345678, "chargedDuration": 2.5, "actualDuration": 2.47, "language": "en", "cost": 0.075, "currency": "USD", "model": "Elevenlabs-STT" }, "words": [ { "text": "Hello", "start": 0.5, "end": 0.9, "type": "word", "speaker_id": "speaker_0" } ], "diarization": { "segments": [ { "speaker": "Speaker 1", "text": "Hello everyone", "start": 0.5, "end": 1.5 } ] } } ``` ### Failed ```json theme={null} { "status": "failed", "error": "Audio file could not be processed" } ``` # Text-to-Speech Source: https://docs.nano-gpt.com/api-reference/endpoint/tts POST /tts Convert text into natural-sounding speech using various TTS models from different providers. Supports multiple languages, voices, and customization options including speed control, voice instructions, and audio format selection. ## Overview Convert text into natural-sounding speech using various TTS models. Supports multiple languages, voices, and customization options including speed control and voice instructions. Looking for synchronous, low‑latency TTS that returns audio bytes directly? See [Speech](/api-reference/endpoint/speech) (POST `/v1/audio/speech`). Want to clone a custom voice from a reference audio clip? See [Voice Cloning](/api-reference/endpoint/voice-cloning). ## Supported Models * **Kokoro-82m**: 44 multilingual voices (\$0.001/1k chars) * **Elevenlabs-Turbo-V2.5**: Premium quality with style controls (\$0.06/1k chars) * **tts-1**: OpenAI standard quality (\$0.015/1k chars) * **tts-1-hd**: OpenAI high definition (\$0.030/1k chars) * **gpt-4o-mini-tts**: Ultra-low cost (\$0.0006/1k chars) * **MiniMax Speech models**: Supports cloned voices via custom voice IDs (see [Voice Cloning](/api-reference/endpoint/voice-cloning)) * **Qwen-3-TTS-1.7B**: Supports cloned voices via speaker embeddings (see [Voice Cloning](/api-reference/endpoint/voice-cloning)) ## Basic Usage ```python Python theme={null} import requests def text_to_speech(text, model="Kokoro-82m", voice=None, **kwargs): headers = { "x-api-key": "YOUR_API_KEY", "Content-Type": "application/json" } payload = { "text": text, "model": model } if voice: payload["voice"] = voice payload.update(kwargs) response = requests.post( "https://api.nano-gpt.com/api/tts", headers=headers, json=payload ) if response.status_code == 200: content_type = response.headers.get('content-type', '') if 'application/json' in content_type: # JSON response with audio URL data = response.json() audio_response = requests.get(data['audioUrl']) with open('output.wav', 'wb') as f: f.write(audio_response.content) else: # Binary audio data (OpenAI models) with open('output.mp3', 'wb') as f: f.write(response.content) return response else: raise Exception(f"Error: {response.status_code}") # Basic usage text_to_speech( "Hello! Welcome to our service.", model="Kokoro-82m", voice="af_bella" ) ``` ```javascript JavaScript theme={null} async function textToSpeech(text, options = {}) { const payload = { text: text, model: options.model || 'Kokoro-82m', ...options }; const response = await fetch('https://api.nano-gpt.com/api/tts', { method: 'POST', headers: { 'x-api-key': 'YOUR_API_KEY', 'Content-Type': 'application/json' }, body: JSON.stringify(payload) }); if (response.ok) { const contentType = response.headers.get('content-type'); if (contentType.includes('application/json')) { const data = await response.json(); console.log('Audio URL:', data.audioUrl); return data; } else { // Binary audio data const audioBlob = await response.blob(); const url = URL.createObjectURL(audioBlob); console.log('Audio blob URL:', url); return { audioBlob, url }; } } else { throw new Error(`Error: ${response.status}`); } } // Usage textToSpeech('Hello world!', { model: 'Kokoro-82m', voice: 'af_bella', speed: 1.1 }); ``` ```bash cURL theme={null} curl -X POST https://api.nano-gpt.com/api/tts \ -H "x-api-key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "text": "Hello! Welcome to our service.", "model": "Kokoro-82m", "voice": "af_bella", "speed": 1.0 }' ``` ## Async Status and Result Retrieval Some TTS models run asynchronously. When queued, the API returns HTTP 202 with a ticket containing a `runId` and `model`. Use the TTS Status endpoint to poll until the job is complete. Synchronous models return audio immediately and do not require status polling. ### Endpoints * Submit TTS: `POST /api/tts` * Check TTS Status (async only): `GET /api/tts/status?runId=...&model=...` ### When you see status: "pending" If your initial `POST /api/tts` returns HTTP 202 with a body like: ```json theme={null} { "status": "pending", "runId": "98b0d593-fe8d-49b8-89c9-233022232297", "model": "Elevenlabs-Turbo-V2.5", "charged": true, "cost": 0.0050388, "paymentSource": "USD", "isApiRequest": true } ``` …the request is queued. Poll the Status endpoint using the `runId` and `model`. If present, include `cost`, `paymentSource`, and `isApiRequest` from the ticket when polling to help with automatic refunds if the upstream provider later rejects content. ### cURL — Submit, then Poll ```bash cURL theme={null} # 1) Submit TTS curl -X POST https://api.nano-gpt.com/api/tts \ -H 'x-api-key: YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "text": "Hello there!", "model": "Elevenlabs-Turbo-V2.5", "voice": "Rachel", "speed": 1.0 }' # 2) If response is 202/pending, poll using returned values curl "https://api.nano-gpt.com/api/tts/status?runId=98b0d593-fe8d-49b8-89c9-233022232297&model=Elevenlabs-Turbo-V2.5&cost=0.0050388&paymentSource=USD&isApiRequest=true" \ -H 'x-api-key: YOUR_API_KEY' # 3) On completion, you'll receive an audioUrl # { # "status": "completed", # "audioUrl": "https://.../file.mp3", # "contentType": "audio/mpeg", # "model": "Elevenlabs-Turbo-V2.5" # } ``` ```javascript JavaScript theme={null} async function submitTTS({ text, model = 'Elevenlabs-Turbo-V2.5', voice = 'Rachel', speed = 1 }) { const res = await fetch('https://api.nano-gpt.com/api/tts', { method: 'POST', headers: { 'x-api-key': 'YOUR_API_KEY', 'Content-Type': 'application/json' }, body: JSON.stringify({ text, model, voice, speed }) }); if (res.status === 202) { const ticket = await res.json(); return await pollTTSStatus(ticket); } if (!res.ok) { const err = await res.json().catch(() => ({})); throw new Error(err.error || 'TTS request failed'); } // Synchronous: either JSON with URL or binary audio const ct = res.headers.get('content-type') || ''; if (ct.includes('application/json')) { const json = await res.json(); return json.audioUrl; } const blob = await res.blob(); return URL.createObjectURL(blob); // play via