Chat completions

The main endpoint. Send a conversation, get the next assistant turn. The request and response follow the OpenAI Chat Completions format, so existing clients and frameworks work unchanged.

POST/v1/chat/completions

Request#

curl https://api.ahurasense.com/v1/chat/completions \
  -H "Authorization: Bearer $AHURA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-sonnet-5",
    "messages": [
      {"role": "system", "content": "You are a terse assistant."},
      {"role": "user", "content": "Explain rate limiting in two sentences."}
    ],
    "temperature": 0.3,
    "max_tokens": 200
  }'

Body parameters

modelstringrequired: A catalog id from Models. Optional only when the request carries X-Ahura-Preset, in which case the preset’s model is used.
messagesarrayrequired: The conversation so far, oldest first, at least one message. Roles are system, developer, user, assistant and tool. content is a string, an array of content parts, or null for an assistant message that only carries tool calls.
streambooleanoptionaldefault false: Return the answer as server-sent events as it is generated. See Streaming.
temperaturenumber, 0 to 2optional: Sampling temperature. 0 is deterministic and makes the request eligible for the response cache.
top_pnumber, 0 to 1optional: Nucleus sampling. Set this or temperature, not both.
max_tokensintegeroptional: Upper bound on generated tokens. On models that reason before answering, the bound covers reasoning tokens too; a small value can leave no room for the visible answer. See reasoning tokens.
reasoning_effortstringoptional: How much a hosted model thinks before it answers: none, minimal, low, medium, high, xhigh or max. Any other value is rejected with 400. Passed through to partner models. See Reasoning effort.
ninteger, 1 to 8optionaldefault 1: How many alternative completions to generate. Each is billed.
stopstring or arrayoptional: Up to four sequences at which generation stops.
presence_penaltynumber, -2 to 2optional: Positive values push the model toward new topics.
frequency_penaltynumber, -2 to 2optional: Positive values discourage repeating the same lines.
toolsarrayoptional: Functions the model may call, in the OpenAI tool format. See Tool calling.
tool_choicestring or objectoptional: auto, none, required, or {"type":"function","function":{"name":"…"}} to force one tool.
response_formatobjectoptional: {"type":"json_object"} for JSON mode. See Structured outputs.
seedintegeroptional: A best-effort request for repeatable sampling. Part of the cache key.
userstringoptional: Your identifier for the end user, for your own abuse tracking. Not part of the cache key and not stored on zero-retention keys.

Other fields in the body are passed through to the model unchanged, so provider-specific options keep working where the model supports them. Unknown fields are never an error.

Response#

A chat completion object. The fields below are always present.

200 OK

{
  "id": "chatcmpl-8f1c…",
  "object": "chat.completion",
  "created": 1757320000,
  "model": "claude-sonnet-5",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "Rate limiting caps how many requests …" },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 31,
    "completion_tokens": 48,
    "total_tokens": 79
  }
}

Field	Meaning
`choices[].message`	The assistant turn. Carries `tool_calls` instead of `content` when the model decided to call a tool.
`choices[].finish_reason`	`stop`, `length` (hit `max_tokens`), `tool_calls`, or `content_filter`.
`usage`	Token counts the request is billed on. Some backends add `prompt_tokens_details.cached_tokens` or a `reasoning_tokens` count.
`model`	The backend’s own spelling of the model. Use the `X-Ahura-Model` header for the catalog id.

The gateway adds headers to every response. The ones you will use most: X-Ahura-Request-Id to identify a call, X-Ahura-Model for the id that served it, X-Ahura-Cache to see whether the cache answered, and X-Ahura-RateLimit-Remaining to pace yourself. The full list, and the optional request headers, are under Authentication.

Multimodal content#

A user message’s content may be an array of parts. Text parts are {"type":"text","text":"…"}; image parts are {"type":"image_url","image_url":{"url":"…"}} with an https URL or a data: URI. Check the model’s vision capability first; a model without it will refuse or ignore the image.

Errors#

Every error is a JSON envelope with a code you can switch on. The codes specific to this endpoint:

400 invalid_request: the body failed validation; the message names the field.
400 model_required: no model and no preset that supplies one.
403 model_not_allowed: the key’s allowlist does not include this model.
404 model_not_found: not a catalog id.
503 model_unavailable: the model is in the catalog but switched off.

The complete list, including authentication, cap and rate-limit responses, is on the Errors page.

Something missing or wrong on this page? Tell us, and quote the page title.