Text completions

Behavior

Requires a completion deployment, not messages.

Endpoint and authentication

POST /v1/completions

Use an XHub API key: Authorization: Bearer . Do not use upstream provider credentials as gateway keys.

Use the gateway root Base URL shown in the playground, without appending /v1; send requests to the full endpoint path above.

Request example

curl "$XHUB_BASE_URL/v1/completions" \
  -H "Authorization: Bearer $XHUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"YOUR_MODEL_NAME","prompt":"Write a short greeting.","max_tokens":64}'

Request parameters

Field	Type	Description
model	string · required	Public model name; deployment must support this protocol.
prompt	string or array · required	Text completion prompt.
max_tokens / temperature / stream	integer / number / boolean	Output ceiling, sampling and SSE.

Success response

{
  "object": "text_completion",
  "choices": [
    {
      "index": 0,
      "text": "Hello!",
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 3,
    "completion_tokens": 2,
    "total_tokens": 5
  }
}

Field	Type
object	string
choices	object[]
choices[].index	number
choices[].text	string
choices[].finish_reason	string
usage	object
usage.prompt_tokens	number
usage.completion_tokens	number
usage.total_tokens	number

Errors and troubleshooting

HTTP	Meaning
400	Invalid request. Check JSON, parameters and query.
401	Missing or invalid XHub credential.
403	Permission denied. Check model scope or policy.
429	Limit exceeded. Inspect response details and Retry-After.