Chat completions and streaming

Set stream to true for server-sent event chunks. Consumers must handle an interrupted connection, partial output, and a terminal completion marker.

Use request IDs from response headers when diagnosing a failed or interrupted stream.

Request

curl -N https://api.codius.ai/v1/v1/chat/completions \
  -H "Authorization: Bearer $CODIUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MODEL_ID",
    "messages": [
      { "role": "user", "content": "Explain this function." }
    ],
    "stream": true,
    "stream_options": { "include_usage": true }
  }'

The response uses text/event-stream. Each event contains a data: line whose JSON value is an OpenAI-compatible chat.completion.chunk. The stream terminates with exactly one:

data: [DONE]

When stream_options.include_usage is true, the final JSON chunk before [DONE] carries the usage block.

Client behavior

1. Read headers before consuming the body and retain x-codius-request-id.
2. Parse SSE framing; do not assume a network read equals one complete event.
3. Append text deltas in order and separately accumulate tool-call deltas by choice and tool-call index.
4. Treat [DONE] as successful protocol completion.
5. If the connection closes first, keep already-rendered output only as partial UI state; do not represent it as a complete model response.

Cancellation and retries

Cancel by aborting the HTTP request. Cancellation may occur after some usage has already been processed.

Do not automatically replay an interrupted tool-using request unless the application can prevent duplicate side effects. For a read-only prompt, a bounded retry can start a new request after transient 429 or 5xx responses. Record each request ID separately.

Non-streaming

Set stream to false or omit it to receive one chat.completion JSON object. Non-streaming is simpler for short background work, but the client waits for the complete response and must still enforce its own request timeout.

See the generated chat-completions operation for the complete request schema and supported fields.