Sarcini și cheltuieli

codai facturează per sarcină, nu per cerere. O sarcină 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 unelte, pași de follow-up) aparțin sarcinii care le-a pornit și nu facturează nimic în plus.

Când începe o sarcinăCopiază linkul secțiunii

O cerere pornește o sarcină 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 unealtă și nu o continuare a asistentului. Follow-up-urile rapide într-o fereastră de 10 minute după o sarcină plătită sunt gratuite: contează ca aceeași sarcină. Un follow-up după fereastră deschide una 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 o sarcină.

X-Codai-No-TaskCopiază linkul secțiunii

Apelurile utilitare — un titlu, o clasificare, o reformulare pe un rând — nu ar trebui să consume o sarcină. 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ă 429Copiază linkul secțiunii

Înainte să ruleze o sarcină 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, alimentări) → rulează, taxat după fapt.
3. Sarcini incluse în planul tău luna aceasta (sau azi, pe planurile zilnice) → rulează.
4. Credite de sarcini 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 Starter for 33 verified tasks every month on the same codai model: https://codai.ro/pricing",
    "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ă — o sarcină care a început deja se termină întotdeauna.

Celălalt 429, rate_limit_exceeded, este despre rata de cereri și bugetele în euro, nu despre sarcini: 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 confirmareCopiază linkul secțiunii

Dincolo de plafon, o sarcină 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 sarcina 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

• O sarcină 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 o sarcină din IDE sau CLI devine inactivă, apare aici ca să ne spui dacă codai a rezolvat-o.” Răspunzi Da, a funcționat sau Nu, opțional cu o notă (păstrată cu sarcina, niciodată trimisă modelului).
• Da închide sarcina ca confirmed cu dovada user_confirmed și aplică taxa de succes (1,20 €; consumul de peste 1,20 € al sarcinii se facturează pentru diferență la tarifele standard pe tokeni); pe planurile cu portofel, costul de tokeni deja taxat este rambursat în contul ei. Nu o închide ca fail — nu se taxează nimic.

Hub-ul arată și surface-ul fiecărei sarcini (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 sarcinile precis, trimiți X-Codai-Client: <surface>/<version> (vezi header-ele cererii) și, dacă ai propriile id-uri de sarcină, 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 sarciniiCopiază linkul secțiunii

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

Endpoint-uriCopiază linkul secțiunii

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 sarcinile 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/confirmCopiază linkul secțiunii

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

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

Doar sarcinile 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.