Documentation · API reference

Completions

POST https://api-staging.heimdallm.com/api/v1/completions

The older OpenAI text-completions shape — prompt in, text out — kept deliberately because many SDKs and tools still speak it. It is one thin route over the same inference core as chat. Requires a bearer API key. Routing, fallbacks and provider preferences work exactly as on chat completions. Set "stream": true for text deltas over SSE. Not every endpoint serves this API; one that does not answers 502.

Request body

Field	Type	Notes
`model`	string	Model id, optionally with a routing suffix. Required unless `models` is given.
`models`	string[] (≤ 20)	Fallback model list.
`prompt`	string / string[]	Required. An array is joined with newlines for cost estimation and sent as is.
`stream`	boolean	Emit text deltas over SSE. Defaults to false.
`temperature`	number	0 to 2.
`top_p`	number	Greater than 0 and at most 1. Zero returns `400`; it is not replaced with a default.
`top_k`	integer	≥ −1; `-1` disables this filter where the endpoint declares it.
`frequency_penalty`	number	−2 to 2.
`presence_penalty`	number	−2 to 2.
`repetition_penalty`	number	Greater than 0 and at most 2; requires endpoint declaration.
`seed`	integer	Best-effort determinism.
`stop`	string / string[]	Up to 8 stop sequences.
`max_tokens`	integer	Completion ceiling, 1 to 1,048,576; also bounds the credit hold.
`logprobs`	integer / null	0 to 5.
`echo`	boolean	Return the prompt with the completion, where supported.
`suffix`	string	Text after the insertion point, where supported.
`user`	string (≤ 256)	Opaque end-user identifier.
`provider`	object	Provider preferences.
`route`	string	Deprecated routing alias: `fallback` groups by model; `sort` orders across models. Explicit `provider.sort.partition` takes precedence.

The adapter forwards known text-completion fields. top_k and repetition_penalty require an endpoint declaration in supported_parameters. Chat-only members, marketplace routing preferences and unknown members are omitted from the upstream body.

Example

curl https://api-staging.heimdallm.com/api/v1/completions \
-H "Authorization: Bearer $HEIMDALL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "model": "deepseek/deepseek-v4-flash-0731-abliterated",
  "prompt": "The three smallest primes are",
  "max_tokens": 16
}'

{
  "id": "gen-41d0aa2b9c3e",
  "object": "text_completion",
  "created": 1755300000,
  "model": "deepseek/deepseek-v4-flash-0731-abliterated",
  "provider": "ImpCC",
  "choices": [
    {
      "index": 0,
      "text": " 2, 3 and 5.",
      "finish_reason": "stop",
      "native_finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 6,
    "completion_tokens": 8,
    "total_tokens": 14,
    "cost": 0.0000038
  }
}

Response fields

Field	Type	Notes
`id`	string	The generation id; also the `X-Generation-Id` header.
`object`	string	`text_completion`.
`created`	integer	Unix seconds.
`model`	string	The model that served the request.
`provider`	string	The serving provider's display name. (Heimdallm)
`choices[].text`	string	The completion text.
`choices[].finish_reason`	string	`stop`, `length`, `tool_calls`, `content_filter` or `error`.
`choices[].native_finish_reason`	string	The provider's raw finish reason.
`choices[].logprobs`	object	Present when requested and supported.
`usage`	object	Token counts and `cost` in USD, as on chat completions.

Streaming

Set "stream": true and use curl -N to read each frame as it arrives. Each data: frame contains an object with object: "text_completion"; append each choice's text to that choice's answer. The final successful chunk has empty choices and carries usage, including cost, before data: [DONE] ends the stream. Usage is based on provider measurements; missing usage is not a measured zero.

A failure before the stream commits returns an ordinary HTTP error. After commitment, the final error frame follows the chat error convention: a chat.completion.chunk with error and choices[0].finish_reason: "error", followed by [DONE]. Usage observed before a failure is settled by the same billing rules as chat. A partial answer is never continued by another provider.

X-Generation-Id identifies both response formats. Successful non-streaming replies also carry X-Provider-Name; streamed chunks carry the serving provider in provider.

Completions

Request body#

Example#

Response fields#

Streaming#

Request body

Example

Response fields

Streaming