POST /v1/chat/completions

Endpoint OpenAI-compatible pra chamar LLMs (DeepSeek, Gemini, Claude, GPT-4o mini, Llama). Request e response seguem o schema OpenAI estável.

Autenticação

http

Authorization: Bearer sk-tokia-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Use a key gerada em /dashboard/keys. Cada key tem budget USD ligado ao saldo BRL (ver Preços). Quando saldo zera, todas as keys são suspensas automaticamente.

Request body

Campo	Tipo	Obrigatório	Descrição
`model`	string	sim	ID do modelo (ex: `openrouter/openai/gpt-4o-mini`). Lista em /docs/models.
`messages`	array	sim	Array de `{ role, content }`. Roles: `system`, `user`, `assistant`, `tool`.
`max_tokens`	number	não	Limite de tokens na resposta. Default depende do modelo.
`temperature`	number 0-2	não	Aleatoriedade. 0 = determinístico, 1 = padrão, 2 = muito criativo.
`stream`	boolean	não	Se `true`, response vira SSE (Server-Sent Events) com chunks.
`tools`	array	não	Function calling. Suportado em modelos que aceitam (GPT-4o mini, Claude, etc).
`response_format`	object	não	`{ "type": "json_object" }` força saída JSON válida (modelos compatíveis).

Exemplo cURL

bash

curl https://api.usetokia.com/v1/chat/completions \
  -H "Authorization: Bearer $TOKIA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openrouter/openai/gpt-4o-mini",
    "messages": [
      { "role": "system", "content": "Responda só em português, em 1 frase." },
      { "role": "user", "content": "Qual a capital da França?" }
    ],
    "temperature": 0.3,
    "max_tokens": 50
  }'

Exemplo streaming

python

from openai import OpenAI

client = OpenAI(api_key=os.environ["TOKIA_KEY"], base_url="https://api.usetokia.com/v1")

stream = client.chat.completions.create(
    model="openrouter/openai/gpt-4o-mini",
    messages=[{"role": "user", "content": "Liste 5 frutas"}],
    stream=True,
)

for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)

Response

json

{
  "id": "chatcmpl-8x4kZ...",
  "object": "chat.completion",
  "created": 1778096405,
  "model": "openrouter/openai/gpt-4o-mini",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "Paris é a capital da França." },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 28,
    "completion_tokens": 9,
    "total_tokens": 37
  }
}

Como o custo aparece

A response do endpoint mostra usage.total_tokens. O custo BRL real debitado do seu saldo é calculado no cron de reconcile (até 60s depois) usando:

text

cost_billed_brl = cost_upstream_usd × fx_BCB_PTAX × markup_modelo

Exemplo gpt-4o-mini (markup 2x, fx 4.92):
  upstream: $0.00000330 USD
  billed:   0.00000330 × 4.92 × 2 = R$ 0.0000325 ≈ R$ 0.0001

Acompanhe no dashboard em /dashboard/usage — timeseries + breakdown por modelo.

Códigos de erro

Erros seguem o schema OpenAI { "error": { "type", "message", "code" } }. Tabela completa em /docs/api/errors.

HTTP	code	Causa típica
400	`invalid_request`	Parâmetro inválido (model, messages, max_tokens).
401	`authentication_failed`	Key inválida, revogada ou sem acesso ao modelo solicitado.
404	`model_not_found`	ID do modelo não existe no catálogo Tokia.
429	`rate_limit_exceeded`	Throttling — backoff e retentar.
502	`upstream_error`	Falha temporária. Retentar em alguns segundos.
503	`service_unavailable`	Modelo temporariamente indisponível. Retentar em alguns minutos.