Grimoire

Gestionarea cheilor API Venice

4 min read

Gestionarea cheilor API Venice

Ce face

venice-api-keys descrie administrarea cheilor API Venice pentru rutele /api_keys: listare, creare, actualizare, revocare, inspectare, verificare de rate limits și logul recent de încălcări de rate limit. Este control de acces, nu inferență.

Endpoint-uri acoperite:

  • GET /api_keys — listează cheile, cu secretul mascat.
  • POST /api_keys — creează o cheie nouă; răspunsul conține singura copie a secretului.
  • PATCH /api_keys — modifică description, expiresAt sau consumptionLimit.
  • DELETE /api_keys?id=... — revocă o cheie.
  • GET /api_keys/{id} — detalii pentru o cheie.
  • GET /api_keys/rate_limits — balanțe și limite pentru cheia curentă.
  • GET /api_keys/rate_limits/log — ultimele 50 de încălcări de rate limit.
  • GET /api_keys/generate_web3_key și POST /api_keys/generate_web3_key — flux Web3 în doi pași pentru mintarea unei chei Bearer prin wallet.

Există două tipuri principale: INFERENCE și ADMIN. INFERENCE poate folosi rutele normale autentificate: chat, image, audio, video, embeddings, augment, crypto RPC, characters, support bot și rate-limit checks pentru cheia curentă. ADMIN poate face toate acestea plus operații administrative: creare, listare, modificare, ștergere de chei și rutele administrative de billing.

Când îmi folosește

Îți folosește când vrei să separi accesul pe aplicații, medii, clienți sau utilizatori. O aplicație leaf ar trebui aproape mereu să primească o cheie INFERENCE, cu descriere recognoscibilă și limită de consum. Cheia ADMIN e instrument chirurgical. Nu o lași într-un worker care mestecă request-uri nesupravegheat.

Cazuri normale:

  • cheie separată per aplicație sau client;
  • limită de consum per cheie;
  • expirare controlată;
  • rotație și revocare;
  • dashboard administrativ cu usage, expirare, ultimele caractere și limite;
  • monitorizare pentru burst-uri de concurență prin rate_limits/log.

Vezi și All guides pentru celelalte ghiduri.

Cum îl invoc / declanșez

Sursa nu definește o comandă universală de runtime. Invocarea depinde de mediul în care skill-ul Venice este expus.

Conceptual, îl folosești când ceri:

  • listarea cheilor Venice;
  • crearea unei chei INFERENCE sau ADMIN;
  • setarea unei limite de consum;
  • eliminarea unei expirări;
  • revocarea unei chei;
  • verificarea rate limits pentru cheia curentă;
  • generarea unei chei prin flux Web3.

Pentru rutele administrative ai nevoie de o cheie ADMIN sau de o sesiune părinte autorizată. O cheie INFERENCE va primi 401 pe rutele administrative. Pentru wallet-only auth, folosește capabilitățile Venice dedicate pentru auth sau x402; acest skill nu substituie autentificarea.

Exemplu practic

Scenariu: vrei o cheie separată pentru un backend, cu descriere clară, limită de consum și opțional expirare.

Creezi cheia cu POST /api_keys și body de forma:

{
  "apiKeyType": "INFERENCE",
  "description": "backend production",
  "expiresAt": "ISO-8601 sau omis",
  "consumptionLimit": { "usd": "limită", "diem": "limită" }
}

Câmpuri obligatorii: apiKeyType și description.

Câmpuri opționale: expiresAt și consumptionLimit.usd / consumptionLimit.diem. vcu este legacy; folosește diem. La creare, expiresAt gol sau omis înseamnă fără expirare.

Răspunsul conține apiKey, secretul complet. Îl salvezi imediat într-un secret store. Nu îl pui în logs, chat, capturi, tabele publice sau ticket-uri. Dacă îl pierzi, Venice nu îl mai afișează; revoci cheia și creezi alta. Curat, rece, fără milă pentru neglijență.

După creare, verifici cheia cu GET /api_keys/rate_limits, folosind cheia respectivă ca Bearer token.

Output / unde aterizează

Output-ul este răspuns API Venice, de obicei JSON.

La GET /api_keys, primești o listă cu metadate: id, tip, descriere, date de creare/expirare, usage recent, limite și last6Chars. Secretul complet nu este returnat.

La POST /api_keys, primești success, metadate și apiKey, singura copie completă a secretului.

La PATCH /api_keys, doar description, expiresAt și consumptionLimit sunt mutabile. Pe update, expiresAt: "" sau null elimină expirarea.

La DELETE /api_keys?id=..., răspunsul așteptat este {"success": true}, iar revocarea este imediată.

La GET /api_keys/rate_limits, primești accessPermitted, tier, balanțe, expirare, următorul epoch și limite per model. La rate_limits/log, primești { object: "list", data: [...] }, cu maximum 50 de încălcări recente.

Limite / gotchas

Crearea de chei este limitată la 20 requests/minut și 500 de chei active per user.

Secretul este returnat exact o dată. Nu există recuperare prin listare sau detalii.

consumptionLimit este per epoch, nu per request. null înseamnă fără cap pentru moneda respectivă.

INFERENCE nu poate apela rutele administrative: POST/PATCH/DELETE /api_keys, GET /api_keys, GET /api_keys/{id}, GET /billing/balance, GET /billing/usage. Poate apela GET /api_keys/rate_limits și GET /api_keys/rate_limits/log pentru cheia curentă.

Fluxul Web3 cere un wallet care deține sVVV. Fără asta, semnarea nu duce la o cheie validă.

Erori tipice: 400 body greșit sau prea multe chei active; 401 cheie lipsă, invalidă sau non-admin pe rută admin; 429 prea multe creări pe minut; 500 problemă tranzitorie, retry rezonabil.

Graph View