POST/v1/completions

Text Completions

Legacy OpenAI text completion endpoint.

The legacy OpenAI Completions dialect. Same auth, policy, and validation path as chat (stop ≤ 4 applies). Prefer Chat Completions for new integrations.

Request body

Field	Type	Required	Notes
`model`	string	yes	A curated alias.
`prompt`	string \| string[]	yes	The text to complete.
`stream`	boolean	no	SSE streaming of `text_completion` chunks, terminated by `data: [DONE]`. Requires `stream_options.include_usage: true`.
`stream_options.include_usage`	boolean	with `stream: true`	Must be `true` when streaming. Usage is metered from the final stream chunk, which the model only sends when asked, and the gateway cannot add the flag on this endpoint. A streaming request without it is 400 `invalid_request` (`param: "stream_options.include_usage"`).
`stop`	string \| string[] \| null	no	At most 4 sequences → 400 `invalid_stop_sequences`.
`max_tokens`	integer	no	Also sizes the prepaid credit reservation.
`top_p`	number	no	Nucleus sampling. Must be in `(0, 1]` → a numeric value outside that range (notably `0`, an empty nucleus) is 400 `invalid_request` (`param: "top_p"`). Omit for the model default.
`temperature`	number	no	Forwarded to the provider unchanged.

Code sample

curl https://api.<domain>/v1/completions \
  -H "Authorization: Bearer $TOKENFACTORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "prompt": "Write a haiku about APIs."
  }'

Response

{
  "id": "cmpl-1",
  "object": "text_completion",
  "created": 1724680001,
  "model": "gpt-4o",
  "choices": [
    { "index": 0, "text": "…", "finish_reason": "stop", "logprobs": null }
  ],
  "usage": { "prompt_tokens": 6, "completion_tokens": 20, "total_tokens": 26 },
  "provider_metadata": { "provider": "openai", "actual_model": "gpt-4o-2024-08-06" }
}

The same strip-list and provider_metadata guarantees as chat apply.

Streaming

curl https://api.<domain>/v1/completions \
  -H "Authorization: Bearer $TOKENFACTORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "prompt": "Write a haiku about APIs.",
    "stream": true,
    "stream_options": {"include_usage": true}
  }'

The last data chunk before data: [DONE] carries usage. Leaving out stream_options.include_usage (or setting it to false) returns:

{
  "error": {
    "message": "Streaming /v1/completions requires stream_options.include_usage=true (usage is metered from the final stream chunk); set it, or use stream:false or /v1/chat/completions",
    "type": "invalid_request_error",
    "code": "invalid_request",
    "param": "stream_options.include_usage",
    "request_id": "…"
  }
}

The request is refused before it reaches the model and before any credit is reserved, so it is not billed. Chat Completions streams need no flag: the gateway adds it there.

Errors

Standard error surface (400, 401, 402, 403, 404, 410, 413, 429, 502, 503, 504) — see Errors.