Task-uri și cheltuieli

codai facturează per task, nu per cerere. Un task este o unitate de muncă — o instrucțiune nouă de la un utilizator și tot ce face agentul ca să o termine. Turele de continuare (rezultate de tool, pași de follow-up) aparțin task-ului care le-a pornit și nu facturează nimic în plus.

Când începe un task

O cerere pornește un task când este o tură de nivel superior al cărei ultim mesaj este un mesaj real de utilizator — text tastat de o persoană, nu un rezultat de tool și nu o continuare a asistentului. Follow-up-urile rapide într-o fereastră de 10 minute după un task plătit sunt gratuite: contează ca același task. Un follow-up după fereastră deschide unul nou.

Sub-agenții porniți și pașii run-urilor de agent sunt întotdeauna continuări (is_task_start = 0). Un run de agent sincron este exact un task.

X-Codai-No-Task

Apelurile utilitare — un titlu, o clasificare, o reformulare pe un rând — nu ar trebui să consume un task. Trimiți X-Codai-No-Task: 1 pe POST /v1/chat/completions sau POST /v1/messages cu codai-fast sau codai-explorer și cererea se facturează ca o continuare. Pe orice alt alias, header-ul este 400 bad_request:

x-codai-no-task is only valid for utility aliases (codai-fast, codai-explorer); got "codai"

Plafoane și cele două 429

Înainte să ruleze un task nou, gateway-ul îți parcurge drepturile în această ordine și se oprește la primul care plătește:

1. Plan nelimitat → rulează.
2. Sold în portofel în EUR (credit de bun venit, referral-uri, reîncărcări) → rulează, taxat după fapt.
3. Task-uri incluse în planul tău luna aceasta (sau azi, pe planurile zilnice) → rulează.
4. Credite de task-uri preplătite → rulează.
5. Depășire contorizată (metered overage), dacă facturarea ta o permite → rulează.
6. Altfel 429 quota_exceeded.

{ "error": { "message": "You've used all 5 agent tasks included in the Free plan this month. Your free tasks reset in 7d 3h. Upgrade to Student for 25 tasks every day with the same Claude Opus 4 quality.", "type": "rate_limit_error", "code": "quota_exceeded" } }

Retry-After pe acel răspuns este onest: numărul de secunde până la resetarea plafonului (următoarea lună UTC, sau miezul nopții UTC la un plafon zilnic). Continuările nu sunt blocate niciodată — un task care a început deja se termină întotdeauna.

Celălalt 429, rate_limit_exceeded, este despre rata de cereri și bugetele în euro, nu despre task-uri: limitele de cereri per minut și per oră (X-RateLimit-Limit-Minute, -Remaining-Minute, -Reset-Minute și trio-ul -Hour pe fiecare răspuns) și plafonul zilnic / lunar de cheltuieli în EUR setat pe o cheie în hub. Citești Retry-After și faci back off. Vezi limite și prețuri pentru tier-uri.

Facturare pe rezultat și confirmare

Dincolo de plafon, un task poartă un rezultat (outcome) — a rezolvat codai problema efectiv? Pe suprafețele care pot dovedi asta (desktop, CLI), clientul raportează pass sau fail cu dovezi de execuție și task-ul se decontează singur. Tot restul — IDE-uri, SDK-uri brute, curl, orice clasifică gateway-ul ca proxy — nu poate dovedi un rezultat, așa că gateway-ul te întreabă pe tine.

open ──(inactiv 30 min)──▶ unconfirmed ──(răspunzi în 24 h)──▶ confirmed | fail
                                       └──(fără răspuns)────────▶ fereastră închisă, nefacturat

• Un task proxy, cli sau mobile fără activitate timp de 30 de minute este închis ca unconfirmed și primește o fereastră de confirmare de 24 de ore.
• Apare sub În așteptare la hub.codai.ro/tasks — „Când un task din IDE-ul sau CLI-ul tău devine inactiv, apare aici ca să ne poți spune dacă codai l-a rezolvat.” Răspunzi Da, a funcționat sau Nu, opțional cu o notă (păstrată cu task-ul, niciodată trimisă modelului).
• Da închide task-ul ca confirmed cu dovada user_confirmed și aplică taxa fixă de succes; pe planurile cu portofel, costul de tokeni deja taxat este rambursat în contul ei. Nu îl închide ca fail — nu se taxează nimic.

Hub-ul arată și surface-ul fiecărui task (IDE / API, Desktop, CLI, Resolve, Sandbox, Mobile, Hub), numărul de cereri, costul upstream și ce s-a taxat, ca să poți reconcilia o factură rând cu rând.

Pentru a atribui task-urile precis, trimiți X-Codai-Client: <surface>/<version> (vezi header-ele cererii) și, dacă ai propriile id-uri de task, X-Codai-Task-Id ([A-Za-z0-9._:-], ≤ 128 caractere) — gateway-ul grupează cererile după el în loc de sesiunea derivată și îl returnează ca ecou.

Obiectul task

Fiecare răspuns /v1/tasks folosește această formă. Banii sunt în micro-unități întregi; datele sunt ISO-8601 sau null.

Endpoint-uri

Toate rutele /v1/tasks au nevoie de o cheie legată de un cont de utilizator (altfel 401 invalid_api_key — Tasks require a user-scoped API key) și returnează doar task-urile tale. Sunt rate-limitate ca orice altă cerere.

# Ce mă așteaptă?
curl https://ai.codai.ro/v1/tasks/pending \
  -H "Authorization: Bearer $CODAI_API_KEY"

# Confirmi unul
curl https://ai.codai.ro/v1/tasks/5c1d…/confirm \
  -H "Authorization: Bearer $CODAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "outcome": "confirmed", "note": "Testele sunt verzi după patch." }'

POST /v1/tasks/:id/confirm

Corp: { "outcome": "confirmed" | "fail", "note"?: string ≤ 500 }. Răspuns:

{ "taskId": "5c1d…", "outcome": "confirmed", "billed": true, "refundedMicroEur": 118000 }

Doar task-urile open și unconfirmed acceptă o confirmare. Hub-ul folosește aceleași reguli; cine răspunde primul câștigă, iar celălalt primește 409.