---
title: "POST /v1/chat/completions"
method: POST
path: "/v1/chat/completions"
---

# POST /v1/chat/completions

`POST /v1/chat/completions`

## Request

- Base URL: `https://nano-gpt.com/api`
- URL: `https://nano-gpt.com/api/v1/chat/completions`
- Auth: one of:
  - HTTP bearer
  - none

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.

## Headers

- `X-Provider` string
- `X-Billing-Mode` string
- `x-x402` 'true'

## Request body

- ChatCompletionRequest
  - `model` string, required: The model to use for completion. The model value may include supported model suffixes, including web search (':online', ':online/<provider>'), memory (':memory', ':memory-<days>'), reasoning visibility (':reasoning-exclude'), thinking variants where listed by the model catalog (':thinking'), and provider routing preferences for eligible models (':fast', ':cheap', ':caching', etc.). Model ID or compatibility alias. Append :reasoning-effort/<effort>, where effort is none, low, medium, high, xhigh, or max, to supply a default reasoning_effort. The suffix is stripped before model routing and is not listed as a separate model. Explicit reasoning generation settings take precedence, including enabled thinking when the suffix is none. The none suffix requests disabled reasoning where supported; it does not bypass model/provider restrictions. Other effort levels remain model/provider-specific.
  - `billing_mode` string: Billing override to force pay-as-you-go without an explicit provider, or to apply saved provider preferences to subscription-included traffic. Accepted values (case-insensitive): paygo, pay-as-you-go, pay_as_you_go, paid, payg.
  - `billingMode` string: Alias for billing_mode.
  - `provider` union: Optional provider override or structured provider routing controls for provider-selection-capable models. A string explicitly selects one provider. An object can set soft order, hard pins, exclusions, sort preference, price caps, fallback behavior, and parameter-capability requirements.
    - string: Provider ID or accepted provider display name/alias.
    - ProviderRoutingObject: Structured per-request provider routing controls. Per-request controls take precedence over saved provider preferences and are not merged with them.
      - `order` string[]: Soft provider preference order. NanoGPT tries these providers first when possible, but this does not hard-pin routing to only these providers. Unknown providers are ignored.
      - `only` string[]: Hard provider pin. NanoGPT restricts routing to these providers and fails instead of silently routing elsewhere. Unknown providers return a structured 400 error with code provider_unknown_provider.
      - `ignore` string[]: Providers to exclude from routing. Unknown providers are ignored.
      - `sort` 'speed' | 'throughput' | 'latency' | 'price' | 'auto' | 'none' | 'default': Routing preference. speed, throughput, latency, and price actively request that strategy. auto, none, and default are accepted to suppress stored/default routing preferences without requesting a provider sort.
      - `quantizations` string[]: Hard allowlist of model weight quantization levels. Providers without matching known quantization metadata are excluded unless unknown is included explicitly.
      - `min_quantization` 'int4' | 'fp4' | 'fp6' | 'int8' | 'fp8' | 'fp16' | 'bf16' | 'fp32': Minimum model weight quantization precision floor. Quantizations are ordered by bit width; integer and floating-point formats with the same bit width are treated as equivalent. unknown is not valid because it cannot be compared to a precision floor.
      - `max_price` object: Optional provider price caps in USD per 1 million tokens. Pricing checks are best-effort when provider pricing is unknown.
        - `prompt` number: Maximum prompt/input price in USD per 1 million tokens.
        - `completion` number: Maximum completion/output price in USD per 1 million tokens.
      - `allow_fallbacks` boolean: When false, disables cross-provider fallback for this request.
      - `require_parameters` boolean: When true, requires the selected provider to support the requested parameters on routes that support parameter-level capability checks.
  - `caching` boolean: When true, route to an available provider that is marked as prompt/input-caching capable for the requested provider-selection model. If no usable cache-capable provider exists, the request fails instead of falling back to a non-cache-capable provider. This is provider capability routing only; it does not add cache_control markers, configure cache TTLs, or force a cache write. The model suffixes ':caching', ':cache', and ':cached' request the same behavior.
  - `stickyprovider` boolean: Top-level routing control for caching: true. When caching is true, defaults to true and prefers the previously recorded provider for later matching requests from the same API key or session when still usable. Set false to require a cache-capable provider without sticky routing.
  - `stickyProvider` boolean: CamelCase alias for top-level stickyprovider. Distinct from prompt_caching.stickyProvider, which controls explicit prompt-cache failover behavior.
  - `messages` object[], required: Array of message objects with role and content; content-less system/developer configuration_update messages are supported for Astra and Fable 5.1, including trailing updates.
    - `role` 'system' | 'user' | 'assistant' | 'developer', required: The role of the message author
    - `content` union: Message content as a simple string or an array of multimodal parts
      - string
      - MessageContentPart[]
        - `type` 'text' | 'image_url' | 'video_url' | 'input_text' | 'input_audio' | 'input_video' | 'video' | 'input_file' | 'file' | 'document' | 'tool_use' | 'tool_result', required: Content block type
        - `text` string: Text content when type is 'text'
        - `image_url` object: Image reference for multimodal prompts
          - `url` string: HTTPS URL or base64 data URL for the image
          - `detail` 'low' | 'high' | 'auto': Requested image resolution detail
        - `input_audio` object: Inline audio input payload
          - `data` string: Base64 encoded audio bytes
          - `format` string: Audio format (e.g. wav, mp3)
        - `video_url` VideoUrl: Canonical Chat Completions video reference. Use a public HTTPS URL or a data:video/*;base64,... URL.
          - `url` string, required: Public HTTPS URL or video base64 data URL.
          - `detail` 'auto' | 'low' | 'high'
          - `start_offset` number: Validated segment start; current public text-model routes return video_segment_not_supported.
          - `end_offset` number: Validated segment end; current public text-model routes return video_segment_not_supported.
        - `start_offset` number
        - `end_offset` number
        - `cache_control` object: Prompt caching control applied to this content block for explicit caching flows (primarily Claude).
          - `type` 'ephemeral': Cache type. Claude currently exposes the 'ephemeral' tier for 5m/1h TTLs.
          - `ttl` '5m' | '1h': Optional TTL override for this block.
    - `configuration_update` InlineConfigurationUpdate: Ordered effort control for Astra and Fable 5.1. A trailing update applies to the generated response. Keep baseline effort unchanged and replay each update in its original position; adjacent updates are rejected. See /api-reference/miscellaneous/inline-reasoning-effort.
      - `reasoning` InlineReasoningEffort, required
        - `effort` 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max', required: Astra: low, medium, high, xhigh. Fable 5.1: low, medium, high, xhigh, max; minimal maps to low. Other models and none are unsupported for inline updates.
  - `stream` boolean: Whether to stream the response
  - `service_tier` 'auto' | 'default' | 'flex' | 'fast' | 'priority': Optional processing tier. Use `flex` for lower-cost variable-capacity processing or `fast` for higher-priority processing where supported. `priority` remains accepted as a legacy alias for Fast on OpenAI models. Discover model support with `GET /api/v1/models?detailed=true` and inspect `supported_service_tiers`; the basic model list intentionally omits this field.
  - `temperature` number: Classic randomness control. Accepts any decimal between 0-2. If omitted, NanoGPT does not force a value and the routed provider/model default applies
  - `max_tokens` integer: Upper bound on generated tokens. If omitted, NanoGPT does not enforce an explicit default and the routed provider/model default applies
  - `top_p` number: Nucleus sampling. When set below 1.0, trims candidate tokens to the smallest set whose cumulative probability exceeds top_p. Works well as an alternative to tweaking temperature
  - `frequency_penalty` number: Penalizes tokens proportionally to how often they appeared previously. Negative values encourage repetition; positive values discourage it
  - `presence_penalty` number: Penalizes tokens based on whether they appeared at all. Good for keeping the model on topic without outright banning words
  - `repetition_penalty` number: Penalizes tokens that already appear in the conversation, on most providers including the prompt. 1 turns it off and values above 1 discourage repetition. Values below 1 encourage repetition and can cause misspelled words and endless loops, especially with long prompts. Unlike frequency_penalty and presence_penalty, the neutral value is 1, not 0
  - `top_k` integer: Caps sampling to the top-k highest probability tokens per step
  - `top_a` number: Combines top-p and temperature behavior; leave unset unless a model description explicitly calls for it
  - `min_p` number: Ensures each candidate token probability exceeds a floor (0-1). Helpful for stopping models from collapsing into low-entropy loops
  - `tfs` number: Tail free sampling. Values between 0-1 let you shave the long tail of the distribution; 1.0 disables the feature
  - `eta_cutoff` number: Cut probabilities as soon as they fall below the specified tail threshold
  - `epsilon_cutoff` number: Cut probabilities as soon as they fall below the specified tail threshold
  - `typical_p` number: Typical sampling (aka entropy-based nucleus). Works like top_p but preserves tokens whose surprise matches the expected entropy
  - `mirostat_mode` 0 | 1 | 2: Enables Mirostat sampling for models that support it. Set to 1 or 2 to activate
  - `mirostat_tau` number: Mirostat target entropy parameter. Used when mirostat_mode is enabled
  - `mirostat_eta` number: Mirostat learning rate parameter. Used when mirostat_mode is enabled
  - `min_tokens` integer: For providers that support it, enforces a minimum completion length before stop conditions fire
  - `stop` union: Stop sequences. Accepts string or array of strings. Values are passed directly to upstream providers
    - string
    - string[]
  - `stop_token_ids` integer[]: Numeric array that lets callers stop generation on specific token IDs. Not supported by many providers
  - `include_stop_str_in_output` boolean: When true, keeps the stop sequence in the final text. Not supported by many providers
  - `ignore_eos` boolean: Allows completions to continue even if the model predicts EOS internally. Useful for long creative writing runs
  - `no_repeat_ngram_size` integer: Extension that forbids repeating n-grams of the given size. Not supported by many providers
  - `custom_token_bans` integer[]: List of token IDs to fully block
  - `logit_bias` object: Object mapping token IDs to additive logits. Works just like OpenAI's version
  - `logprobs` union: When true or a number, forwards the request to providers that support returning token-level log probabilities
    - boolean
    - integer
  - `prompt_logprobs` boolean: Requests logprobs on the prompt itself when the upstream API allows it
  - `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.
  - `web_search` union: Web search for this request. `true` turns search on with the default provider (native search on GPT-5+ and o-series models, Linkup elsewhere); `false` leaves search off unless an `:online` model suffix turns it on. `webSearch` and the legacy `linkup` object are accepted aliases; when more than one is sent, `web_search` wins, then `webSearch`. See the Web Search section of the chat completion guide for provider-specific options.
    - boolean
    - object
      - `enabled` boolean: Must be true for the object to turn on search.
      - `provider` 'native' | 'linkup' | 'tavily' | 'brave' | 'sofya' | 'exa' | 'kagi' | 'perplexity' | 'valyu' | 'firecrawl': Search provider. `native` uses the model's own search (GPT-5+ and o-series, Claude 4+, Gemini 3+, Grok 4.20+; not image, multi-agent, or `:free` variants). Unsupported models fall back to the suffix's provider, or Linkup.
      - `depth` string: Search depth: `standard` or `deep` for most providers; Exa also accepts `fast`, `auto`, `neural`, `instant`, and `deep-reasoning`.
      - `search_context_size` 'low' | 'medium' | 'high': Native search only. How much search context the model uses (default `medium`; OpenAI deep-research models always use `medium`).
      - `user_location` object: Native search on GPT-5+ and o-series models only; may be ignored when a fallback route serves the request. Approximate user location; `userLocation` is accepted as an alias.
        - `type` 'approximate'
        - `country` string: Two-letter ISO country code, for example `US`.
        - `city` string
        - `region` string
        - `timezone` string: IANA time zone, for example `America/Los_Angeles`.
  - `web_search_options` object: OpenAI-compatible web search options. Turns on web search with the default provider (native search on GPT-5+ and o-series models, Linkup elsewhere). Ignored when the request also sends `web_search`, `webSearch`, or `linkup`, and on models that already search on their own. When an `:online/<provider>` suffix is present, its provider and depth are kept. The NanoGPT help model rejects a non-empty object.
    - `search_context_size` 'low' | 'medium' | 'high': Passed to native search. Never selects deep search.
    - `user_location` object: Approximate user location, passed to native search on GPT-5+ and o-series models.
      - `type` 'approximate'
      - `approximate` object
        - `country` string
        - `city` string
        - `region` string
        - `timezone` string
  - `max_tool_calls` integer: Maximum number of built-in tool calls, such as native web searches, page opens and searches within a page, the model can make in one response. Applies to requests NanoGPT sends to OpenAI's Responses API, including GPT-5+ and o-series native search and your own OpenAI key (BYOK); calls past the cap are not run or billed. Other routes, and rerouted requests such as Auto Model, ignore it.
  - `prompt_caching` object: Helper to tag leading messages for explicit prompt-caching control (primarily Claude flows). Providers with implicit caching support (including OpenAI, Gemini, and many open-source provider routes) do not require this helper. NanoGPT injects cache_control blocks on each message up to the specified index before forwarding upstream. If cut_after_message_index is omitted, NanoGPT selects a cache boundary automatically.
    - `enabled` boolean: Whether to enable prompt caching on this request
    - `ttl` '5m' | '1h': Cache time-to-live ('5m' or '1h')
    - `cut_after_message_index` integer: Zero-based index of the last message that should be cached. All messages up to and including this index receive the same cache_control block.
    - `stickyProvider` boolean: When true, avoids failover to preserve prompt cache consistency. If a fallback would be required, the request can return 503 instead.
  - `reasoning_effort` 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh': Controls reasoning depth and acts as an explicit reasoning-mode signal. Any value other than "none" requests reasoning/thinking behavior. Use "none" to explicitly disable reasoning.
  - `reasoning` object: Reasoning configuration. `exclude` controls output visibility (hides reasoning fields/blocks) and does not inherently disable reasoning compute. `effort` controls depth, and `delta_field` switches to legacy `reasoning_content` fields.
    - `exclude` boolean: When true, omits reasoning fields from the response
    - `effort` 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh': Alias for reasoning_effort. If both are provided, top-level reasoning_effort is authoritative for Chat Completions request shaping.
    - `delta_field` 'reasoning_content': When set to "reasoning_content", uses legacy reasoning_content fields instead of reasoning
  - `reasoning_delta_field` 'reasoning_content': Shorthand for reasoning.delta_field
  - `reasoning_content_compat` boolean: Shorthand to force legacy reasoning_content fields in the response
  - `advisor` AdvisorConfig: Allows the executor model to consult one different advisor model. Auto mode lets the executor decide whether to consult; required mode forces one consultation request. Advisor is non-streaming and available only for platform-billed pay-as-you-go API-key requests. Subscriptions, BYOK, accountless x402, Private Mode, inline moderation, client tools, structured outputs, memory, and server-side content enhancements are rejected before orchestration. Each completed executor, advisor, and continuation phase is billed separately.
    - `model` string, required: Explicit advisor model ID. Automatic model selection and the executor's resolved model are not allowed.
    - `instructions` string
    - `mode` 'auto' | 'required': Auto lets the executor decide whether to consult. Required forces exactly one internal consultation request before the final answer.
    - `max_uses` 1
    - `max_completion_tokens` integer: Optional advisor output-token limit. When omitted, NanoGPT does not impose an Advisor-specific output cap and the selected model/provider defaults apply.
    - `forward_transcript` false

## Response `200`

Chat completion response

- ChatCompletionResponse
  - `id` string: Unique identifier for the completion
  - `object` string: Object type, always 'chat.completion'
  - `created` integer: Unix timestamp of when the completion was created
  - `choices` object[]: Array of completion choices
    - `index` integer: Index of the choice
    - `message` object
      - `role` 'assistant': Role of the completion message
      - `content` string: Content of the completion message
      - `reasoning` string: Optional reasoning output (when supported and not excluded)
      - `reasoning_content` string: Legacy alias of reasoning (only present when legacy compatibility is enabled)
      - `reasoning_details` object[]: Optional structured reasoning metadata (when available)
    - `finish_reason` 'stop' | 'length' | 'content_filter': Reason why the completion finished
  - `usage` object
    - `prompt_tokens` integer: Number of tokens in the prompt
    - `prompt_tokens_details` object: Optional details about prompt token accounting
      - `cached_tokens` integer: Cached input tokens (when prompt caching is used)
    - `cache_creation_input_tokens` integer: Input tokens written to cache on this request (when prompt caching is used)
    - `cache_read_input_tokens` integer: Input tokens read from cache on this request (when prompt caching is used)
    - `completion_tokens` integer: Number of tokens in the completion
    - `completion_tokens_details` object: Optional breakdown of completion token accounting
      - `reasoning_tokens` integer: Reasoning tokens within the completion (when reported)
    - `reasoning_tokens` integer: Reasoning tokens within the completion (when reported)
    - `total_tokens` integer: Total number of tokens used
  - `service_tier` string: Service tier used (echoed when provided on the request)
  - `advisor` AdvisorResponseMetadata: Advisor orchestration outcome. Top-level usage and pricing aggregate billable phases that returned usage, including an HTTP-success advisor phase whose output was unusable; the optional per-phase objects provide reconciliation detail.
    - `id` string, required
    - `mode` 'auto' | 'required', required
    - `executor_model` string, required
    - `advisor_model` string, required
    - `requested` boolean, required: Whether the executor emitted the internal consultation request.
    - `consulted` boolean, required: Whether an advisor child call was attempted.
    - `successful` boolean, required: Whether the advisor returned usable advice.
    - `consultation_count` 0 | 1, required
    - `max_uses` 1, required
    - `status` 'not_used' | 'completed' | 'failed', required
    - `error` string: Present when consultation failed but the executor could continue.
    - `usage` AdvisorPhaseBreakdown
      - `executor` object
      - `advisor` object
      - `continuation` object
      - `total` object
    - `pricing` AdvisorPhaseBreakdown
      - `executor` object
      - `advisor` object
      - `continuation` object
      - `total` object

## Other responses

- `400`: Unexpected error. Video errors include video_input_not_supported, invalid_video_url_scheme, invalid_video_data_url, invalid_video_base64, invalid_video_mime_type, missing_video_source, video_file_id_not_supported, video_attachment_too_large, video_attachment_limit_exceeded, invalid_video_segment, video_segment_not_supported, and youtube_video_route_not_supported.
- `402`: Payment Required - authenticated insufficient balance or opted-in accountless x402 quote for supported non-streaming requests

## Changes

- **2026-11-03** `cc8b07d75689`: 2 breaking, 9 info
  - added `subschema #1` to the `messages/items/` request property `allOf` list
  - the `repetition_penalty` request property's min was increased to `0.00`
  - added the new optional request property `max_tool_calls`
  - added the new optional request property `messages/items/configuration_update`
  - …7 more

[Operation history](https://skmtc.dev/nano-gpt/apis/nanogpt-api/changes/v1/chat/completions/post.md)

---

[API](https://skmtc.dev/nano-gpt/apis/nanogpt-api.md) - [All operations](https://skmtc.dev/nano-gpt/apis/nanogpt-api/llms.txt) - [OpenAPI document](https://skmtc.dev/nano-gpt/apis/nanogpt-api/revisions/cc8b07d75689?raw)