Chat și completări

Cele trei formate wire care ajung la `codai`: OpenAI Chat Completions, Anthropic Messages, OpenAI Responses.

Toate cele trei endpoint-uri rutează spre același lanț de modele și împart autentificarea, limitele de rată, prompt caching-ul și înregistrarea usage-ului. Alege-l pe cel pe care SDK-ul tău îl vorbește deja — ghidul formatelor wire explică diferențele, iar ghidul de header-e acoperă fiecare extensie x-codai-* pe care o vezi mai jos.

POST

/v1/chat/completions

Autorizare

bearerAuth

headerAutorizareBearer <codai_…>

O cheie API codai (prefix codai_). Tokenurile efemere de la POST /v1/tokens sunt acceptate doar de suprafețele media potrivite scope-ului lor (/v1/realtime, /v1/audio/*, /v1/embeddings).

Parametri header

Corpul cererii

application/json

body

Body OpenAI Chat Completions. Câmpurile necunoscute sunt acceptate (passthrough) și forwardate către upstream-urile compatibile OpenAI; upstream-urile Anthropic le ignoră.

model?string

Modelul logic. codai este smart-router-ul și singurul model adresabil public; orice nume nerecunoscut este convertit în codai.

Implicit"codai"

messages*array<>

Conversația de până acum. Peste 2 000 de mesaje gateway-ul taie mijlocul (păstrează capul system + coada recentă); peste 20 000 cererea este respinsă cu 400.

Elemente1 <= items <= 20000

stream?boolean

true returnează chunk-uri text/event-stream. Chunk-ul final de usage este emis întotdeauna.

Implicitfalse

stream_options?

Acceptat pentru compatibilitate OpenAI; include_usage este practic mereu activ.

max_tokens?integer

Numărul maxim de tokeni de completare (numele vechi).

Interval1 <= value

max_completion_tokens?integer

Numărul maxim de tokeni de completare (numele OpenAI curent). Oricare dintre nume este respectat.

Interval1 <= value

temperature?number

top_p?number

top_k?integer

Extensie codai forwardată către upstream-urile Anthropic.

stop?|array<string>

Un string de oprire sau un array de string-uri de oprire.

tools?array<|>

Tool-uri de tip function. Prezența lor comută cererea pe calea multi-turn (stream-urile sunt bufferizate și redate). Un element codai_sandbox lasă gateway-ul să ruleze bash și Python pe server, într-un sandbox izolat (vezi eticheta Sandboxes).

tool_choice?|

auto | none | required | {type: function, function: {name}}. required și alegerile cu nume sunt retrogradate la auto pe modelele care refuză folosirea forțată a tool-urilor (Fable 5.x); none suprimă complet tool-urile.

response_format?

Control al ieșirii structurate. json_object / json_schema injectează o instrucțiune system și validează ieșirea la servire; json_schema poartă și schema.

reasoning_effort?string

Nivelul de efort test-time-compute (vocabularul OpenAI plus max din codai; none acceptat ca minimal). Header-ul x-codai-effort are prioritate când sunt prezente ambele.

Valoare din"minimal""low""medium""high""max"

n?integer

Acceptat pentru compatibilitate și forwardat doar către upstream-urile compatibile OpenAI; codai returnează întotdeauna o singură alegere.

user?string

Identificatorul utilizatorului final. Când lipsește header-ul x-codai-session-id, un user nevid sub 256 de caractere este folosit ca id de sesiune.

Lungimelength <= 255

metadata?

Acceptat pentru compatibilitate (passthrough); nu este interpretat de gateway.

[key: string]?any

Corpul răspunsului

Completare. JSON (chat.completion) când stream este false sau lipsește; text/event-stream de obiecte chat.completion.chunk când stream: true, terminat întotdeauna cu un chunk de usage și data: [DONE]. Header-ele de răspuns de mai jos apar pe ambele forme; header-ele de cost sunt x-codai-cost-micro-usd când costul este cunoscut la răspuns și x-codai-cost-estimate: pending pe stream-urile native (rândul de consum se scrie după închiderea stream-ului).

response

id*string

object*"chat.completion"

Valoare din"chat.completion"

created*integer

Secunde Unix.

model*string

Modelul upstream care a servit cererea.

choices*array<>

Întotdeauna exact o alegere.

usage*

Exemplu de cerere

curl -X POST 'https://ai.codai.ro/v1/chat/completions' \
  -H 'Content-Type: application/json' \
  -d '{
  "messages": [
    {
      "role": "system"
    }
  ]
}'

Exemplu de cerere

curl -X POST 'https://ai.codai.ro/v1/chat/completions' \  -H 'Content-Type: application/json' \  -d '{  "messages": [    {      "role": "system"    }  ]}'

Exemplu de răspunsSchemă

{
  "id": "chatcmpl_9f1c2b7e4d",
  "object": "chat.completion",
  "created": 1790108310,
  "model": "claude-sonnet-5",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "system",
        "content": "string",
        "name": "string",
        "tool_call_id": "string",
        "tool_calls": [
          {
            "id": "toolu_01Xy9k3mQ",
            "type": "function",
            "function": {
              "name": "string",
              "arguments": "{\"path\":\"src/index.ts\"}"
            }
          }
        ]
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 0,
    "completion_tokens": 0,
    "total_tokens": 0,
    "prompt_tokens_details": {
      "cached_tokens": 0
    },
    "cache_creation_input_tokens": 0
  }
}

{  "id": "chatcmpl_9f1c2b7e4d",  "object": "chat.completion",  "created": 1790108310,  "model": "claude-sonnet-5",  "choices": [    {      "index": 0,      "message": {        "role": "system",        "content": "string",        "name": "string",        "tool_call_id": "string",        "tool_calls": [          {            "id": "toolu_01Xy9k3mQ",            "type": "function",            "function": {              "name": "string",              "arguments": "{\"path\":\"src/index.ts\"}"            }          }        ]      },      "finish_reason": "stop"    }  ],  "usage": {    "prompt_tokens": 0,    "completion_tokens": 0,    "total_tokens": 0,    "prompt_tokens_details": {      "cached_tokens": 0    },    "cache_creation_input_tokens": 0  }}

POST

/v1/messages

Autorizare

bearerAuth

headerAutorizareBearer <codai_…>

O cheie API codai (prefix codai_). Tokenurile efemere de la POST /v1/tokens sunt acceptate doar de suprafețele media potrivite scope-ului lor (/v1/realtime, /v1/audio/*, /v1/embeddings).

Parametri header

Corpul cererii

application/json

body

Cererea publică Anthropic Messages. Câmpurile necunoscute de la nivelul superior trec validarea și sunt ignorate, dacă nu sunt listate aici ca extensie codai.

model*string

Modelul sau alias-ul. Folosești codai pentru smart-router. Numele care nu sunt alias-uri codai sunt convertite la codai.

messages*array<>

Turele conversației, alternând user / assistant. Conținutul este un string sau un array de blocuri. Transcrierile prea lungi sunt tăiate din mijloc, nu respinse.

Elemente1 <= items

max_tokens*integer

Numărul maxim de tokeni de ieșire. Obligatoriu.

Interval1 <= value

system?|array<>

Promptul de sistem ca string simplu sau ca array de blocuri text (unite cu linii goale).

temperature?number

Temperatura de eșantionare. Eliminată pe modelele upstream care resping parametrii de eșantionare.

top_p?number

Eșantionare nucleus. Eliminată pe modelele upstream care resping parametrii de eșantionare.

top_k?number

Eșantionare top-k. Eliminată pe modelele upstream care resping parametrii de eșantionare.

stop_sequences?array<string>

Secvențe de oprire personalizate.

stream?boolean

true returnează text/event-stream (vezi descrierea operației pentru lista de evenimente).

Implicitfalse

tools?array<>

Definițiile tool-urilor pe care modelul le poate apela. Orice listă nevidă forțează calea de execuție buffered.

tool_choice?|

auto lasă modelul să decidă, any forțează un apel de tool oarecare, tool forțează un tool anume. Pe upstream-urile Fable 5 / 5.1 any și tool sunt coborâte la auto, pentru că acele modele resping apelul forțat de tool.

metadata?

Se folosește doar user_id; este trimis mai departe ca câmpul user din upstream.

thinking?|

Configurarea Anthropic pentru extended thinking. Acceptată pentru compatibilitate cu SDK-ul, dar NU este trimisă mai departe — gateway-ul decide forma de thinking per model upstream (enabled + budget_tokens pe modelele vechi, adaptive pe cele noi). Folosești în schimb header-ele x-codai-thinking / x-codai-thinking-budget.

reasoning_effort?string

Extensie codai (parametru de body standard OpenAI). Tier-ul de efort pentru alocatorul de calcul; header-ul x-codai-effort are prioritate.

Valoare din"minimal""low""medium""high""max"

Corpul răspunsului

Mesajul asistentului. JSON când stream este false sau lipsește; o secvență de evenimente SSE (vezi descrierea operației) când stream este true.

response

Răspuns fără streaming. model reia modelul sau alias-ul cerut, nu upstream-ul care a răspuns (vezi x-codai-routed-to).

id*string

type*"message"

Valoare din"message"

role*"assistant"

Valoare din"assistant"

model*string

content*array<|>

Întotdeauna cel puțin un bloc; un răspuns gol este un singur bloc text cu text: ''.

stop_reason*string

Mapat din motivul de oprire upstream (content_filter devine end_turn).

Valoare din"end_turn""max_tokens""stop_sequence""tool_use"

stop_sequence*string

Întotdeauna null pe calea buffered.

usage*

Exemplu de cerere

curl -X POST 'https://ai.codai.ro/v1/messages' \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "codai",
  "messages": [
    {
      "role": "user",
      "content": "string"
    }
  ],
  "max_tokens": 4096
}'

Exemplu de cerere

curl -X POST 'https://ai.codai.ro/v1/messages' \  -H 'Content-Type: application/json' \  -d '{  "model": "codai",  "messages": [    {      "role": "user",      "content": "string"    }  ],  "max_tokens": 4096}'

Exemplu de răspunsSchemă

{
  "id": "msg_1f0d5b7a-4c2e-4a9b-9c1d-2e3f4a5b6c7d",
  "type": "message",
  "role": "assistant",
  "model": "codai",
  "content": [
    {
      "type": "text",
      "text": "string"
    }
  ],
  "stop_reason": "end_turn",
  "stop_sequence": "string",
  "usage": {
    "input_tokens": 0,
    "output_tokens": 0,
    "cache_read_input_tokens": 0,
    "cache_creation_input_tokens": 0
  }
}

{  "id": "msg_1f0d5b7a-4c2e-4a9b-9c1d-2e3f4a5b6c7d",  "type": "message",  "role": "assistant",  "model": "codai",  "content": [    {      "type": "text",      "text": "string"    }  ],  "stop_reason": "end_turn",  "stop_sequence": "string",  "usage": {    "input_tokens": 0,    "output_tokens": 0,    "cache_read_input_tokens": 0,    "cache_creation_input_tokens": 0  }}

POST

/v1/responses

Autorizare

bearerAuth

headerAutorizareBearer <codai_…>

O cheie API codai (prefix codai_). Tokenurile efemere de la POST /v1/tokens sunt acceptate doar de suprafețele media potrivite scope-ului lor (/v1/realtime, /v1/audio/*, /v1/embeddings).

Parametri header

Corpul cererii

application/json

body

model?string

Implicit"codai"

input?|array<>

Prompt-ul ca un singur string de user sau ca array de item-uri de input.

instructions?string

Devine mesajul system de la început.

stream?boolean

Implicitfalse

max_output_tokens?integer

Mapat la max_tokens.

Interval1 <= value

temperature?number

top_p?number

tools?array<>

tool_choice?|

Trecut neschimbat către chat completions.

reasoning?

Doar effort este mapat (xhigh → max, none → minimal, valorile necunoscute sunt eliminate). Ignorat când trimiți x-codai-effort.

previous_response_id?string

NU este suportat — orice valoare este respinsă cu 400. Trimite în loc întregul context în input.

background?boolean

NU este suportat — true este respins cu 400.

[key: string]?any

Corpul răspunsului

Un obiect response când stream este false; altfel un text/event-stream de evenimente response.* (vezi descrierea). Răspunsurile non-stream poartă aceleași header-e x-codai-* ca /v1/chat/completions (rutare, trace, cost, task).

response

id*string

object*"response"

Valoare din"response"

created_at*integer

Secunde Unix.

status*"completed"

Valoare din"completed"

model*string

Modelul upstream care a servit apelul interior.

output*array<|>

Mai întâi item-urile function-call, apoi cel mult un mesaj assistant.

output_text*string

Copie de conveniență a textului assistant (string gol când nu există).

usage*

Exemplu de cerere

curl -X POST 'https://ai.codai.ro/v1/responses' \
  -H 'Content-Type: application/json' \
  -d '{}'

Exemplu de cerere

curl -X POST 'https://ai.codai.ro/v1/responses' \  -H 'Content-Type: application/json' \  -d '{}'

Exemplu de răspunsSchemă

{
  "id": "resp_chatcmpl_9f1c2b7e4d",
  "object": "response",
  "created_at": 0,
  "status": "completed",
  "model": "string",
  "output": [
    {
      "type": "function_call",
      "id": "fc_toolu_01Xy9k3mQ",
      "call_id": "string",
      "name": "string",
      "arguments": "string",
      "status": "completed"
    }
  ],
  "output_text": "string",
  "usage": {
    "input_tokens": 0,
    "input_tokens_details": {
      "cached_tokens": 0
    },
    "output_tokens": 0,
    "total_tokens": 0
  }
}

{  "id": "resp_chatcmpl_9f1c2b7e4d",  "object": "response",  "created_at": 0,  "status": "completed",  "model": "string",  "output": [    {      "type": "function_call",      "id": "fc_toolu_01Xy9k3mQ",      "call_id": "string",      "name": "string",      "arguments": "string",      "status": "completed"    }  ],  "output_text": "string",  "usage": {    "input_tokens": 0,    "input_tokens_details": {      "cached_tokens": 0    },    "output_tokens": 0,    "total_tokens": 0  }}

Chat și completări

AutorizareCopiază linkul secțiunii

Parametri headerCopiază linkul secțiunii

Corpul cereriiCopiază linkul secțiunii

Corpul răspunsuluiCopiază linkul secțiunii

AutorizareCopiază linkul secțiunii

Parametri headerCopiază linkul secțiunii

Corpul cereriiCopiază linkul secțiunii

Corpul răspunsuluiCopiază linkul secțiunii

AutorizareCopiază linkul secțiunii

Parametri headerCopiază linkul secțiunii

Corpul cereriiCopiază linkul secțiunii

Corpul răspunsuluiCopiază linkul secțiunii

Autorizare

Parametri header

Corpul cererii

Corpul răspunsului

Autorizare

Parametri header

Corpul cererii

Corpul răspunsului

Autorizare

Parametri header

Corpul cererii

Corpul răspunsului