Chat Completions

Generate chat completions from a list of messages — the primary endpoint for text generation with all supported models.

POST/v1/chat/completions

Generate a chat completion from a list of messages. This is the primary endpoint for text generation with all supported models.

The parameter tables below list the common fields shared across models. Each model may support additional model-specific parameters (e.g. vision input, tool calling, JSON mode). For the exhaustive list of parameters a given model accepts, open its details page at Models and switch to the API tab — the parameter reference there is generated from the model's declared capabilities.

Request body

Parameter	Type	Required	Description
`model`	string	Yes	Model ID (e.g. "gpt-4o-mini", "claude-sonnet-4-6")
`messages`	array	Yes	Array of message objects. Each has a `role` (`system`, `user`, or `assistant`) and `content` that's either a plain string or an array of content blocks (`text`, `image_url`, `document_url`). `system` sets the AI's behavior; `user` is your message; `assistant` is a prior AI reply.
`temperature`	number	No	Controls randomness. 0 = deterministic/focused, 1 = balanced (default), 2 = highly creative/random.
`max_tokens`	integer	No	Maximum tokens to generate
`stream`	boolean	No	Stream response as SSE. Default: false
`top_p`	number	No	Nucleus sampling parameter (0–1)
`stop`	string \| string[]	No	Up to 4 stop sequences. The model stops generating when it hits one.
`frequency_penalty`	number	No	-2.0 to 2.0. Positive values penalize repeated tokens. Default: 0
`presence_penalty`	number	No	-2.0 to 2.0. Positive values push the model toward new topics. Default: 0
`seed`	integer	No	Reproducibility seed. Same seed + params returns similar output (best-effort).
`response_format`	object	No	`{ type: "json_object" }` or `{ type: "json_schema", json_schema: ... }` for structured output. Model support varies — see the model's API tab.
`tools`	array	No	Function definitions the model can call. Paired with `tool_choice`. Available on tool-capable models only.

PDF input. Attach a PDF on a user message by passing a content block with { type: "document_url", document_url: { url: ... } }. Up to 5 PDFs per request, 32 MB each. Only models with the documents capability accept this block — every Claude model, the GPT-4.1, GPT-5 and GPT-6 families, the Gemini models and Nova 2 Lite. Check capabilities.documents on GET /v1/models or the model's API tab; other models return 400 with details.code: "documents_not_supported".

Example request

import Tchavi from '@tchavi/sdk';

const client = new Tchavi({ apiKey: 'YOUR_API_KEY' });

const response = await client.chat.completions.create({
  model: 'gpt-4o-mini',
  messages: [
    { role: 'system', content: 'You are a helpful assistant.' },
    { role: 'user', content: 'What is the capital of Benin?' },
  ],
  temperature: 0.7,
});

console.log(response.choices[0].message.content);
console.log('Credits used:', response.tchavi.credits_used);

Example response

JSON

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1711234567,
  "model": "gpt-4o-mini",
  "system_fingerprint": null,
  "service_tier": null,
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "The capital of Benin is Porto-Novo.",
        "refusal": null
      },
      "finish_reason": "stop",
      "logprobs": null
    }
  ],
  "usage": {
    "prompt_tokens": 24,
    "completion_tokens": 12,
    "total_tokens": 36,
    "prompt_tokens_details": { "cached_tokens": 0, "cache_write_tokens": 0, "audio_tokens": 0 },
    "completion_tokens_details": { "reasoning_tokens": 0, "audio_tokens": 0 }
  },
  "tchavi": {
    "budget_group": "BUDGET",
    "model_credits_per_1k": { "input": 1, "output": 2 },
    "model_type": "chat",
    "credits_used": 3,
    "credits_remaining": 1297
  }
}

The tchavi object is added to every non-streaming response: credits_used is what this call cost, credits_remaining your balance after it, and model_credits_per_1k the model's rates. OpenAI SDKs ignore the extra field.

What the response guarantees

Tchavi serves many providers behind one API, and the model you name may be served by a different one. These hold whoever answers, so you never need a branch per provider.

model is the id you asked for — never the provider's own name for it. Ask for gpt-5-nano and you get gpt-5-nano, not gpt-5-nano-2025-08-07, so the response can always be compared to your request.

id is this request's id. It is chatcmpl- followed by the value of the X-Request-Id header (resp_ on /v1/responses, msg_ on /v1/messages). Every chunk of a stream carries the same one. Quote it to support and the request can be found.

The shape does not vary. system_fingerprint and service_tier are always present and always null: they describe an upstream backend and an OpenAI product tier, neither of which this API sells — your own tier is in tchavi. refusal and both usage detail blocks are always present too, so reading them never gives undefined.

Reasoning text follows the model you named. Models that publish their thinking return message.reasoning, and delta.reasoning while streaming. Models that do not — the OpenAI reasoning family among them — return no text while still reporting completion_tokens_details.reasoning_tokens, which is billed as output. That matches how each model behaves natively.

Streaming

Set stream: true to receive the response token-by-token as Server-Sent Events (SSE). This lets you display text as it arrives rather than waiting for the full response.

import Tchavi from '@tchavi/sdk';

const client = new Tchavi({ apiKey: process.env.TCHAVI_API_KEY });

const stream = await client.chat.completions.create({
  model: 'gpt-4o-mini',
  messages: [{ role: 'user', content: 'Tell me a short story.' }],
  stream: true,
});

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? '');
}