Header-e de cerere
Fiecare header pe care gateway-ul îl citește și fiecare header pe care îl trimite înapoi — autentificare, identitate de client, caching, effort, thinking, sesiuni, sarcini, cost.
Toate header-ele codai sunt opționale și insensibile la majuscule. Le trimiți pe POST /v1/chat/completions, POST /v1/messages și POST /v1/responses (ruta Responses trimite mai departe fiecare header X-Codai-* către ruta de chat în care reintră). Tot ce trimiți și gateway-ul nu înțelege este ignorat.
Autentificare
| Header | Valoare |
|---|---|
Authorization | Bearer codai_… — cheia ta API, sau un token efemer codai_eph_v1.… pe suprafețele media. Obligatoriu peste tot, cu excepția endpoint-urilor publice /vscode/*, /copilot/*, /health și /status. |
x-api-key | Acceptat doar pe POST /v1/messages, pentru SDK-urile Anthropic. Authorization câștigă dacă sunt prezente ambele. |
anthropic-version, anthropic-beta, openai-beta | Acceptate și ignorate. Gateway-ul construiește singur header-ele către upstream și își setează propriile beta Anthropic; valoarea anthropic-beta a clientului nu e trimisă mai departe. |
O cheie lipsă sau necunoscută dă 401 invalid_api_key. O cheie dintr-un abonament inactiv dă 402 subscription_inactive.
Identitatea clientului
| Header | Efect |
|---|---|
X-Codai-Client | Cine apelează, ca <suprafață>/<versiune> — desktop/1.4.0, phone-android/0.9.2, codai-cli/0.3.0, hub/…. Determină atribuirea sarcinilor: desktop și cli pot raporta singure rezultatul sarcinii; tot restul (IDE-uri, SDK-uri brute, curl) este proxy și sarcinile lui se închid doar prin confirmare explicită a utilizatorului în hub. Cade pe User-Agent când lipsește. |
X-Request-Id | Id-ul tău de corelare. Reflectat înapoi ca x-codai-trace-id, trimis către upstream și utilizabil ca client_request_id în POST /v1/feedback. |
X-Codai-Repo | Identificator de repository pentru scoparea memoriei. Când lipsește, gateway-ul deduce scopul din transcript. |
X-Codai-Agent-Id | Id de atribuire înregistrat pe apelurile de tool în flote de agenți. [A-Za-z0-9._:-], maximum 128 caractere. |
Versiuni minime de client
Pe fiecare rută /v1/*, gateway-ul compară versiunea din X-Codai-Client (<aplicație>/<semver>, aplicațiile desktop, phone-android — phone e acceptat ca alias — web și cli) cu două minime configurate pe server, per aplicație: CODAI_MIN_CLIENT (obligatoriu) și CODAI_RECOMMENDED_CLIENT (recomandat), de ex. desktop=0.9.0,phone-android=3.0.0. Ridicarea unui minim e o schimbare de configurație, nu un deploy de cod.
- Sub minimul obligatoriu, cererea e respinsă cu
426 client_outdated;error.detailsconțineapp,min_versionșidownload_url. - Sub minimul recomandat, cererea e servită normal, iar răspunsul poartă
x-codai-upgrade: recommended; min=<versiune>. - Un
X-Codai-Clientlipsă, necunoscut sau imposibil de interpretat (SDK-uri terțe, curl, build-uri de dezvoltare) nu e blocat niciodată.
{ "error": { "type": "invalid_request_error", "code": "client_outdated", "message": "This codai app is too old (minimum 0.9.0). Update it to continue.", "details": { "app": "desktop", "min_version": "0.9.0", "download_url": "https://codai.ro/download" } } }x-codai-upgrade e destinat aplicațiilor codai și nu apare în lista CORS de header-e expuse de mai jos.
Caching
| Header | Efect |
|---|---|
X-Codai-Cache | Prompt caching este pornit implicit pentru fiecare model. 0 sau false îl oprește — cu excepția alias-urilor codai*, unde opt-out-ul este ignorat. Citirile din cache costă aproximativ a zecea parte din input-ul proaspăt, iar o buclă de agent necache-uită cu 170 k tokeni a costat odată un utilizator mii de dolari pe zi, așa că alias-ul router nu te lasă să-l dezactivezi. |
Pe răspuns: x-codai-cache-read și x-codai-cache-write poartă numărul de tokeni din cache când e cunoscut înaintea primului byte; usage.prompt_tokens_details.cached_tokens poartă numărul final de citiri în body.
Effort și thinking
| Header | Efect |
|---|---|
X-Codai-Effort | minimal · low · medium (implicit) · high · max. Câștigă peste reasoning_effort din body. Vezi modele. |
X-Codai-Thinking | 1 sau true activează explicit extended thinking. |
X-Codai-Thinking-Budget | Buget de thinking în tokeni (întreg pozitiv, implicit 16 384). |
X-Codai-Thinking-Pin | 1 păstrează bugetul complet de thinking pe turele de continuare cu tool. Fără el, gateway-ul limitează bugetele injectate la 4 096 tokeni pe turele al căror ultim mesaj e un rezultat de tool, ca buclele de agent să nu plătească max la fiecare pas. |
Pe răspuns: x-codai-effort, x-codai-effort-applied, x-codai-effort-continuation-dampened.
Sesiuni și memorie
| Header | Efect |
|---|---|
X-Codai-Session-Id | Id stabil pentru o conversație logică. Activează sticky routing (ține prompt cache-urile calde), totaluri de cost per sesiune în GET /v1/receipt și memorie de sesiune. Header-ul bate body.user. Clienții IDE îl omit de obicei; gateway-ul derivă atunci o cheie din transcript. |
X-Codai-New-Session | 1 pornește o sesiune persistentă nouă cu id proaspăt, ignorând orice X-Codai-Session-Id. |
X-Codai-No-Recall | 1 sare citirea memoriei anterioare pentru această tură, dar o persistă totuși. |
X-Codai-Incognito | 1 face tura complet stateless — nimic citit, nimic scris, fără sticky routing. |
X-Codai-Compact | auto activează compactarea deterministă server-side a contextului (trunchiază rezultatele vechi de tool din afara cozii protejate, fără apel de model). off o dezactivează. Răspuns: `x-codai-compacted: true |
Comportament de agent
| Header | Efect |
|---|---|
X-Codai-Mode | agent comută pe modul agent plan-and-execute (limită de adâncime ridicată, mesaj de sistem de planificare). Necesită un tier cu unelte și sub-agenți; altfel 403 forbidden. Reflectat ca x-codai-mode: agent. |
X-Codai-Disable-Subagents | 1 sare injectarea uneltei delegate_to_model. Configurația VS Code îl setează — Copilot își deține propria orchestrare. |
X-Codai-Best-Of | 3 forțează best-of-N pe această cerere; 0 dezactivează auto-gate-ul. Răspuns: x-codai-best-of-status. |
X-Codai-Cascade | verify forțează draft-and-verify pe această cerere. Răspuns: x-codai-cascade-status. |
Sarcini și facturare
codai facturează per sarcină verificată, nu per token. Aceste header-e leagă o cerere de sarcina ei.
| Header | Efect |
|---|---|
X-Codai-Task-Id | Id-ul tău de sarcină ([A-Za-z0-9._:-], maximum 128). Corelează toate turele unei sarcini; fără el gateway-ul derivă o cheie din transcript. |
X-Codai-Task-Outcome | pass sau fail. Respectat doar de pe suprafețele desktop și cli și doar cu dovadă automată — altfel ignorat și logat. |
X-Codai-Task-Evidence | exec_verdict sau reexec — ce dovedește rezultatul. Obligatoriu ca X-Codai-Task-Outcome să aibă efect. |
X-Codai-No-Task | 1 scoate un apel utilitar din numărătoarea de sarcini. Respectat doar pe alias-uri utilitare precum codai-fast; pe o cerere codai completă este respins cu 400, ca plafonul de sarcini să nu poată fi ocolit. |
X-Codai-Device, X-Codai-Device-Platform, X-Codai-Device-Name | Înregistrarea dispozitivului pentru protocolul de sesiuni partajate (desktop, telefon). Nu e nevoie pentru apeluri API simple. |
Pe răspuns: x-codai-task-id (sarcina la care s-a atașat tura), x-codai-event-id (rândul de usage — îl trimiți la POST /v1/feedback).
Header-e de răspuns
| Header | Semnificație |
|---|---|
x-codai-routed-to | Modelul upstream concret care a servit. |
x-codai-provider | Tipul adaptorului de provider, de ex. vertex-anthropic. |
x-codai-upstream | La fel ca routed-to, setat împreună cu chitanța de cost. |
x-codai-trace-id | X-Request-Id al tău sau un UUID generat. |
x-codai-event-id | Id-ul rândului usage_events pentru această cerere. |
x-codai-task-id | Sarcina la care s-a atașat cererea. |
x-codai-cost-micro-usd | Micro-USD întregi pentru această cerere, când e cunoscut la momentul header-elor. |
x-codai-cost-estimate | pending pe stream-urile native — vezi GET /v1/receipt. |
x-codai-ai-generated | true pe fiecare răspuns care conține output de model — chat, messages, responses, imagini, audio (vorbire și transcriere), muzică, video, randări, rulări de agent. Marcaj de conținut generat de AI, citibil automat (AI Act UE, art. 50 alin. (2)). Nu e setat niciodată pe erori. |
x-codai-generator | codai/<model upstream> care a produs output-ul, de ex. codai/claude-sonnet-5; codai/codai când modelul nu e cunoscut la momentul header-elor. Trimis împreună cu x-codai-ai-generated. |
x-codai-cache-read, x-codai-cache-write | Numărul de tokeni de cache când e cunoscut dinainte. |
x-codai-spend-day-usd, x-codai-spend-day-cap-usd, x-codai-spend-month-usd, x-codai-spend-month-cap-usd | Cheltuiala ta curentă față de plafon, când plafoanele de cheltuieli sunt active pe contul tău. |
x-codai-exec-verify | passed · refined · refine_failed · skipped · error pe răspunsurile codai-labs verificate prin execuție. |
x-codai-embed-fallback | <cerut>-><servit> când un model de embedding a fost înlocuit. |
x-ratelimit-limit-minute, x-ratelimit-remaining-minute, x-ratelimit-reset-minute, x-ratelimit-limit-hour, x-ratelimit-remaining-hour, x-ratelimit-reset-hour | Limite de cereri cu fereastră glisantă. reset este un timestamp Unix în secunde. |
Retry-After | Pe 429: secunde până când cea mai veche intrare iese din fereastră. Respectă-l — este exact, nu un 60 fix. |
Toate acestea sunt în lista CORS Access-Control-Expose-Headers, așa că codul din browser le poate citi.
Idempotență
Cererile de chat nu au Idempotency-Key. Reîncercarea unei cereri de chat creează o cerere nouă și un rând de usage nou; prompt caching face reîncercarea ieftină. Pentru o identitate stabilă peste reîncercări, trimiți același X-Request-Id — devine client_request_id pe rândul de usage și lasă POST /v1/feedback să țintească tura.
POST-urile Studio facturate (/v1/videos, /v1/audio/music, /v1/studio/renders, /v1/studio/timelines, /v1/studio/documents/*, randările și exporturile din /v1/studio/creatives/*, /v1/studio/batches) și rulările din sandbox acceptă Idempotency-Key (1-255 caractere ASCII tipăribile, păstrat 24 h):
- aceeași cheie + același corp: primești din nou primul răspuns, cu
idempotent-replayed: true, și nu se mai taxează nimic; - aceeași cheie + alt corp:
422 idempotency_key_mismatch; - prima cerere încă rulează:
409 idempotency_in_progress— reîncearcă mai târziu.
O cerere eșuată eliberează cheia, deci o reîncercare cu aceeași cheie rulează din nou. În SDK-uri: ext: { headers: { 'Idempotency-Key': key } } (TypeScript), ext={"headers": {"Idempotency-Key": key}} (Python).
Rezervarea din portofel pentru Studio
Fiecare acțiune Studio plătită rezervă întâi prețul ei în portofel. Când soldul disponibil (portofel minus rezerva de compute minus rezervările deschise) nu ajunge, primești 402 insufficient_funds cu quote_micro_eur și balance_micro_eur, iar nimic nu pornește și nu se taxează. Rezervarea se închide cu suma facturată când jobul se termină și se eliberează când eșuează. GET /v1/studio/quote?action=video&seconds=8 îți arată prețul și sufficient înainte să rulezi ceva; e gratuit.
Ultima actualizare: