Grimoire

Autentificare Venice API

4 min read

Autentificare Venice API

Ce face

venice-auth documentează autentificarea la Venice API prin una dintre cele două scheme acceptate de endpoint-uri: BearerAuth sau siwx.

Bearer înseamnă că folosești o cheie API Venice în header:

Authorization: Bearer <VENICE_API_KEY>

x402 / SIWE înseamnă că semnezi cu un wallet Ethereum și plătești per request în USDC pe Base, chain ID 8453, trimițând headerul:

X-Sign-In-With-X: <base64(json)>

JSON-ul decodat conține adresa walletului, mesajul SIWE, semnătura, timestamp-ul și chainId.

Capabilitatea explică formatul corect, câmpurile SIWE, TTL-ul, regulile de nonce, alegerea între moduri și folosirea SDK-ului venice-x402-client. Nu creează automat conturi, chei, walleturi, fonduri sau aprobări de plată.

All guides

Când îmi folosește

Folosește venice-auth când faci primul request către https://api.venice.ai, construiești o integrare server-side, implementezi un flow fără cont bazat pe wallet, sau depanezi 401 Authentication failed.

Alege Bearer când ai cont Venice, vrei usage analytics, vrei child keys cu limite de consum, folosești solduri DIEM / USD / bundled credits, sau administrezi chei API. Doar cheile ADMIN pot gestiona alte chei; cheile INFERENCE sunt pentru inferență și pot avea acces mai limitat.

Alege x402 când un agent, o funcție serverless sau un utilizator final plătește per request dintr-un wallet. Este potrivit pentru bugete on-chain și flow-uri fără cont, dar implică semnare și costuri reale.

Cum îl invoc / declanșez

Nu există o comandă publică universală garantată pentru această capabilitate. Runtime-ul care are skill-ul instalat ar trebui să-l poată încărca după numele venice-auth.

Declanșatorul practic este nevoia de a implementa sau verifica autentificarea Venice: alegerea schemei, construirea headerelor, validarea SIWE, gestionarea erorilor 401 / 402, sau integrarea SDK-ului.

Prerechizite:

  • pentru Bearer: cont Venice și o cheie API validă;
  • pentru x402: wallet Ethereum, acces la semnare, USDC pe Base pentru top-up sau plată;
  • pentru SDK: mediu JavaScript/TypeScript și pachetul venice-x402-client.

Nu introduce chei private, seed phrases sau API keys în cod public, loguri, prompturi sau documente.

Exemplu practic

Bearer:

curl https://api.venice.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "zai-org-glm-5-1",
    "messages": [{"role":"user","content":"hello"}]
  }'

x402 folosește un mesaj SIWE cu domain din allow-list, de obicei api.venice.ai, uri potrivit, version: "1", adresa checksummed, statement: "Sign in to Venice AI", nonce random de 16 caractere hex, issuedAt, expirationTime și chainId: 8453.

statement poate fi alt string, dar acesta păstrează UX-ul de consimțământ al serverului. chainId poate fi număr, string numeric sau CAIP-2: 8453, "8453" sau "eip155:8453".

Pentru semnare automată:

npm install venice-x402-client

VeniceClient și createAuthFetch gestionează semnarea SIWE, rotația headerului și prompturile pentru 402.

Output / unde aterizează

Nu există un fișier local de output definit. Rezultatul este acceptarea sau respingerea autentificării de către Venice API.

Dacă autentificarea reușește, primești răspunsul endpoint-ului apelat. Dacă folosești x402 și walletul nu are credit suficient, poți primi 402 PAYMENT_REQUIRED cu instrucțiuni de top-up.

Top-up-ul este o acțiune cu bani reali. Flow-ul este: POST /x402/top-up fără X-402-Payment, primești cerințele de plată, semnezi autorizarea USDC cu SDK-ul x402, apoi repeți POST /x402/top-up cu X-402-Payment. Nu automatiza top-up-uri fără limită explicită de buget și aprobare.

Limite / gotchas

Bearer keys sunt parole: ține-le în secret manager, rotește-le dacă sunt compromise și limitează-le cu consumptionLimits.

Nu expune private keys în aplicații browser. Pentru browser folosește provider de wallet, de exemplu MetaMask sau WalletConnect.

Headerul SIWE este valid 5 minute de la issuedAt; rotește-l la aproximativ 4 minute. payload.timestamp trebuie să fie la maximum 30 secunde de issuedAt, iar issuedAt nu trebuie să fie cu peste 30 secunde în viitor față de server.

Nonce-ul este single-use per wallet. Refolosirea lui în aproximativ 5.5 minute este respinsă cu X402_SIGN_IN_NONCE_REUSED.

Domeniul SIWE trebuie să fie allow-listed: venice.ai, api.venice.ai, outerface.venice.ai, preview.venice.ai, staging.venice.ai, plus localhost în dev. Validarea nu se face după Host header.

Erori comune: 401 Authentication failed, 402 x402 când lipsește headerul SIWE pe rute x402, 401 This model is only available to Pro users, 402 PAYMENT_REQUIRED pentru x402 fără sold suficient și 402 INSUFFICIENT_BALANCE când soldurile Bearer sunt epuizate.

Graph View