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.

Autorizare

bearerAuth

AutorizareBearer <token>

O cheie API codai (prefix codai_). Tokenurile efemere de la POST /v1/tokens sunt acceptate doar de /v1/realtime.

În: header

Parametri header

x-request-id?string

Id de corelare ales de client; e returnat ca x-codai-trace-id și persistat pe rândul de usage.

Lungimelength <= 128

x-codai-session-id?string

Grupează cererile unei conversații pentru chitanțe, stickiness și prompt caching.

Lungimelength <= 128

x-codai-effort?string

Nivelul de efort test-time-compute. Are prioritate față de câmpul reasoning_effort din body. max este o extensie codai peste high din OpenAI; none este acceptat ca alias pentru minimal.

Valoare în

"minimal"
"low"
"medium"
"high"
"max"

x-codai-thinking?string

1/true activează extended thinking pe modelele care îl suportă (bugetul din x-codai-thinking-budget, implicit 16384 tokeni).

x-codai-thinking-budget?string

Buget de tokeni de thinking (întreg pozitiv) folosit când x-codai-thinking este activ. Marchează cererea ca reglată de client, așa că planificatorul de efort nu o suprascrie.

x-codai-thinking-pin?string

1 păstrează bugetul complet de thinking pe turele de continuare cu tool-uri, în loc de bugetul redus aplicat implicit de gateway.

x-codai-cache?string

0/false dezactivează prompt caching pentru un id de model DIRECT. Ignorat (caching forțat activ) pentru alias-urile router codai / codai-*.

x-codai-no-task?string

1/true scoate cererea din contorizarea task-urilor. Valid doar pe alias-urile utilitare; pe codai cererea este respinsă cu 400.

x-codai-task-id?string

Id de corelare a task-ului ales de client. Cererile care îl împart sunt atribuite aceluiași task; este returnat ca header de răspuns x-codai-task-id când este cunoscut în 150 ms.

x-codai-task-outcome?string

pass sau fail — rezultat auto-raportat care închide task-ul atașat. Respectat doar pentru suprafețele desktop/CLI (x-codai-client) și doar împreună cu un x-codai-task-evidence de tip mașină.

Valoare în

"pass"
"fail"

x-codai-task-evidence?string

Tipul de dovadă care susține x-codai-task-outcome; doar exec_verdict și reexec închid un task.

Valoare în

"exec_verdict"
"reexec"

x-codai-client?string

Etichetă explicită a suprafeței client, folosită la atribuirea task-urilor (desktop/<ver>, phone-android/<ver>, codai-cli/<ver>, hub/<ver>). Orice altceva este clasificat drept proxy.

x-codai-incognito?string

1 face tura complet stateless: nu se citește memoria, nu se persistă nimic, fără sticky routing.

x-codai-no-recall?string

1 sare peste citirea memoriei anterioare, dar persistă totuși această tură.

x-codai-proven-only?string

1 restrânge recall-ul de memorie la intrările promovate la proven.

x-codai-new-session?string

1 rotește către un namespace de sesiune nou, generat de server, pentru această cerere, ignorând x-codai-session-id.

x-codai-repo?string

Indiciu de scope pe repository (ex. owner/name) folosit la alegerea playbook-ului de sesiune; majoritatea proxy-urilor IDE nu îl pot trimite, așa că gateway-ul deduce scope-ul și din transcript.

x-codai-agent-id?string

Identificator de agent furnizat de client, persistat împreună cu evenimentul de consum pentru analize per agent.

x-codai-disable-subagents?string

1 interzice fan-out-ul de sub-agenți delegate_to_model și forțează calea nativă de streaming.

x-codai-mode?"agent"

agent cere agent mode (prompt de agent pe server + tool-uri server). 403 când cheia/planul nu are dreptul.

Valoare în

"agent"

x-codai-server-tools?string

1/true activează tool-urile din gateway fără agent mode complet (agent mode îl implică).

x-codai-orchestrate?string

1/true activează orchestrarea multi-model (fan-out pe sub-task-uri). Necesită cel puțin două modele în allowlist-ul cheii.

x-codai-cascade?string

verify activează cascada FrugalGPT (draft ieftin, verificare pe frontier). Rezultatul apare în x-codai-cascade-status.

x-codai-best-of?string

Numărul de eșantioane best-of-N (ex. 3); 0/off dezactivează explicit best-of-ul automat. Rezultatul în x-codai-best-of-status.

x-codai-best-of-depth?string

Adâncimea judecătorului pentru best-of-N.

x-codai-reflect?string

Activează/dezactivează pasul de auto-verificare reflect (1/0). Rezultatul în x-codai-reflect-status.

x-codai-step-verify?string

Activează/dezactivează verificarea procesului la nivel de pas (1/0). Rezultatul în x-codai-step-verify-status.

x-codai-plan?string

Activează/dezactivează verificarea planului pe orizont lung (1/0). Rezultatul în x-codai-plan-status.

x-codai-consensus?string

1 rulează consens iterativ pe toate nivelurile (non-stream, doar pe alias-ul router). Rezultatul în x-codai-consensus-status.

x-codai-compact?string

Compactare opt-in a transcriptului pe server (1). Economiile apar în x-codai-compacted / x-codai-compact-saved-chars.

x-codai-retrieval?string

1/on activează retrieval-ul de relevanță peste transcript înainte de dispatch (x-codai-retrieval-reduced).

x-codai-heuristics?string

Activează/dezactivează injecția de euristici învățate în prompt (1/0).

x-codai-identity?string

Suprascrie modul preambulului de identitate (on / off / shadow).

x-codai-playbook?string

Suprascrie per cerere modul playbook; x-codai-no-playbook: 1 este kill-switch-ul dur.

x-codai-no-playbook?string

1 dezactivează injecția playbook-ului de sesiune pentru această cerere.

x-codai-debug?string

1 adaugă trace-ul complet al deciziei router-ului ca header-e de răspuns x-codai-router-* suplimentare.

Corpul cererii

application/json

Definiții TypeScript

Folosește tipul request body în TypeScript.

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).

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 în

"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

`application/json`

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

{  "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  }}

Autorizare

bearerAuth

AutorizareBearer <token>

O cheie API codai (prefix codai_). Tokenurile efemere de la POST /v1/tokens sunt acceptate doar de /v1/realtime.

În: header

Parametri header

x-request-id?string

Id de corelare ales de client; e returnat ca x-codai-trace-id și persistat pe rândul de usage.

Lungimelength <= 128

x-codai-session-id?string

Grupează cererile unei conversații pentru chitanțe, stickiness și prompt caching.

Lungimelength <= 128

x-api-key?string

Header de cheie API în stil Anthropic. Alternativă la Authorization: Bearer; ignorat când există un header Bearer.

x-codai-effort?string

Tier-ul de efort de calcul la inferență. Are prioritate față de reasoning_effort din body. none este normalizat la minimal; valorile necunoscute sunt ignorate.

Valoare în

"minimal"
"low"
"medium"
"high"
"max"

x-codai-thinking?string

Activezi extended thinking în upstream (1 sau true). Buget implicit 16384 tokeni.

Valoare în

"1"
"true"
"0"
"false"

x-codai-thinking-budget?string

Bugetul de thinking în tokeni (întreg pozitiv). Pe modelele cu adaptive thinking este mapat la un nivel de efort. Setarea lui spune și alocatorului de calcul să nu-și injecteze propriul buget.

x-codai-cache?string

Dezactivarea prompt caching-ului (0 / false). Respectată doar pe apelurile directe de model — caching-ul este forțat PORNIT pentru alias-ul router codai.

Valoare în

"0"
"false"
"1"
"true"

x-codai-compact?string

Forțezi (1) sau suprimi (0) compactarea conversației pe server pentru această cerere.

Valoare în

x-codai-disable-subagents?"1"

1 dezactivează delegarea către sub-agenți pentru această cerere. Combinat cu stream: true și fără tools, deblochează calea nativă de streaming pass-through pe tier-urile cu sub-agenți.

Valoare în

x-codai-no-task?"1"

1 renunță la contorizarea task-urilor. Respectat doar pentru alias-urile utilitare eligibile; pe un model complet cererea este respinsă cu 400.

Valoare în

x-codai-best-of?string

Eșantionare best-of-N pe calea buffered (condiționată de tier; ignorată fără drept).

x-codai-best-of-depth?string

Adâncimea de sub-agent la care se aplică best-of pe calea buffered.

x-codai-client?string

Identificator liber al clientului, înregistrat pe task-ul deschis pentru această tură.

Corpul cererii

application/json

Definiții TypeScript

Folosește tipul request body în TypeScript.

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 în

"minimal"
"low"
"medium"
"high"
"max"

Corpul răspunsului

`application/json`

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

{  "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  }}

Autorizare

bearerAuth

AutorizareBearer <token>

O cheie API codai (prefix codai_). Tokenurile efemere de la POST /v1/tokens sunt acceptate doar de /v1/realtime.

În: header

Parametri header

x-request-id?string

Id de corelare ales de client; e returnat ca x-codai-trace-id și persistat pe rândul de usage.

Lungimelength <= 128

x-codai-session-id?string

Grupează cererile unei conversații pentru chitanțe, stickiness și prompt caching.

Lungimelength <= 128

x-codai-effort?string

Nivelul de efort; când este prezent are prioritate și reasoning.effort din body nu mai este mapat.

Valoare în

"minimal"
"low"
"medium"
"high"
"max"

x-codai-cache?string

0/false dezactivează prompt caching pentru un id de model direct (ignorat pentru alias-ul codai). Forwardat către apelul interior chat-completions.

x-codai-no-task?string

Forwardat către apelul interior; valid doar pe alias-urile utilitare (400 pe codai).

x-codai-incognito?string

Forwardat către apelul interior — tură stateless, nimic persistat.

x-codai-client?string

Forwardat către apelul interior — eticheta suprafeței client pentru atribuirea task-urilor.

Corpul cererii

application/json

Definiții TypeScript

Folosește tipul request body în TypeScript.

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

`application/json`

curl -X POST "https://example.com/v1/responses" \  -H "Content-Type: application/json" \  -d '{}'

{  "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  }}

200application/json

400application/json

401application/json

402application/json

403application/json

413application/json

429application/json

502application/json

200application/json

400application/json

401application/json

402application/json

403application/json

413application/json

429application/json

502application/json

200application/json

400application/json

401application/json

402application/json

403application/json

413application/json

429application/json

502application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`