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

# POST /v1/completions

`POST /v1/completions`

## Request

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

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.

## Headers

- `X-Provider` string
- `X-Billing-Mode` string

## Request body

- CompletionRequest
  - `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.).
  - `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.
  - `prompt` string, required: The text prompt to complete
  - `max_tokens` integer: Upper bound on generated tokens. If omitted, NanoGPT does not enforce an explicit default and the routed provider/model default applies
  - `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
  - `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
  - `stream` boolean: Whether to stream the response
  - `stop` union: Stop sequences. Accepts string or array of strings. Values are passed directly to upstream providers
    - string
    - string[]
  - `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_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.

## Response `200`

Text completion response

- CompletionResponse
  - `id` string: Unique identifier for the completion
  - `object` string: Object type, always 'text_completion'
  - `created` integer: Unix timestamp of when the completion was created
  - `model` string: Model used for completion
  - `choices` object[]: Array of completion choices
    - `text` string: The completed text
    - `index` integer: Index of the choice
    - `logprobs` object, nullable: Log probabilities of tokens (if requested)
    - `finish_reason` 'stop' | 'length' | 'content_filter': Reason why the completion finished
  - `usage` object
    - `prompt_tokens` integer: Number of tokens in the prompt
    - `completion_tokens` integer: Number of tokens in the completion
    - `total_tokens` integer: Total number of tokens used

## Other responses

- `400`: Unexpected error

## Changes

- **2026-11-03** `cc8b07d75689`: 1 breaking, 1 info
  - the `repetition_penalty` request property's min was increased to `0.00`
  - the `repetition_penalty` request property default value `1` was added

[Operation history](https://skmtc.dev/nano-gpt/apis/nanogpt-api/changes/v1/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)