Grimoire

Ghid Venice API Overview

4 min read

Ghid Venice API Overview

Ce face

venice-api-overview este ghidul de orientare pentru integrarea cu Venice.ai API. Îți arată suprafața generală a API-ului: URL-ul de bază, modurile de autentificare, familiile de endpoint-uri, headerele importante, modelul de pricing, forma standard a erorilor și regula de versioning.

Venice.ai este o platformă de inference compatibilă cu OpenAI pentru text, imagini, audio, video și embeddings. Toate endpoint-urile publice documentate pornesc de la aceeași bază:

https://api.venice.ai/api/v1

Acest skill nu execută apeluri API și nu înlocuiește skill-urile specializate. Îl folosești ca index inițial, apoi treci la skill-ul potrivit: venice-auth, venice-models, venice-chat, venice-responses, venice-errors, venice-billing, venice-x402 sau cele pentru imagini, audio și video.

Vezi și All guides pentru restul capabilităților documentate.

Când îmi folosește

Îți folosește când începi o integrare Venice și ai nevoie de o hartă înainte să scrii cod sau să alegi un endpoint.

Cazuri tipice:

  • lucrezi pentru prima dată cu api.venice.ai;
  • trebuie să alegi între API key și x402 wallet;
  • cauți endpoint-ul corect pentru chat, embeddings, imagini, audio, video, billing, modele sau wallet;
  • vrei să înțelegi headere precum X-Balance-Remaining, X-RateLimit-*, PAYMENT-REQUIRED sau Content-Encoding;
  • ai primit o eroare 402, 422 sau 429 și vrei să știi ce skill tratează retry-ul și interpretarea;
  • trebuie să verifici pricing, capabilități de model sau limite înainte de implementare.

Nu este un skill de autonomie. Nu creează chei, nu face top-up, nu modifică billing, nu trimite request-uri și nu gestionează secrete. Pentru acțiuni cu cost, credentials sau efecte externe, operatorul trebuie să aleagă explicit pașii.

Cum îl invoc / declanșez

Într-un runtime cu skills, încarci venice-api-overview înainte de orice integrare Venice nouă. Regula practică este: folosește-l primul pentru orientare, apoi încarcă skill-ul specializat.

Rutare uzuală:

  • venice-auth pentru Bearer API key vs siwx / x402;
  • venice-models pentru GET /models, traits și compatibility mapping;
  • venice-chat pentru POST /chat/completions;
  • venice-responses pentru POST /responses Alpha;
  • venice-embeddings pentru POST /embeddings;
  • venice-image-generate și venice-image-edit pentru imagini;
  • venice-audio-speech, venice-audio-transcription, venice-audio-music pentru audio;
  • venice-video pentru video async;
  • venice-errors pentru forma erorilor și strategia de retry;
  • venice-billing, venice-api-keys și venice-x402 pentru cont, usage, chei și wallet.

Exemplu practic

Vrei să construiești o integrare minimă pentru chat.

Pașii corecți:

  1. Încarci venice-api-overview.
  2. Alegi autentificarea: BearerAuth cu Authorization: Bearer <VENICE_API_KEY> pentru aplicații server-side, sau siwx cu X-Sign-In-With-X: <base64 SIWE JSON> pentru x402 wallet.
  3. Încarci venice-auth ca să verifici detaliile schemei alese.
  4. Chemi GET /models ca să vezi modelele disponibile, constraints, pricing și capabilități.
  5. Verifici model_spec.capabilities; nu presupui capabilități după numele modelului.
  6. Pentru chat, încarci venice-chat și folosești POST /chat/completions.
  7. Adaugi handling de erori cu venice-errors.

Exemplu Bearer, fără a expune secrete:

curl https://api.venice.ai/api/v1/models \
  -H "Authorization: Bearer $VENICE_API_KEY"

Pentru x402, folosește clientul sau fluxul documentat în skill-ul venice-auth / venice-x402; nu inventa formatul payload-ului și nu loga cheia wallet-ului.

Output / unde aterizează

Output-ul skill-ului este ghidaj tehnic: ce categorie de endpoint se potrivește, ce skill urmează, ce headere urmărești și ce verificări faci înainte de request.

La nivel API, răspunsurile pot include:

  • X-Balance-Remaining pentru creditul x402 rămas după inference;
  • X-RateLimit-Limit-* și X-RateLimit-Remaining-* pentru limite;
  • PAYMENT-REQUIRED la 402, cu informații de top-up și challenge pentru x402;
  • Content-Encoding când răspunsul este comprimat.

Erorile au formă standard:

{ "error": "Human-readable message" }

Pentru unele validări 400, corpul include și details.

Limite / gotchas

Nu presupune că există /v2. Versioning-ul se face pe aceeași suprafață /api/v1; versiunea OpenAPI este un timestamp, iar funcțiile noi pot fi marcate Alpha/Beta.

Nu trimite venice_parameters la /responses; acolo este respins. Pentru chat completions, extensiile Venice folosesc venice_parameters, iar unele opțiuni se pot activa prin sufixe în model ID.

Pricing-ul este dinamic per request. Pentru modele, verifică GET /models și model_spec.pricing când există. Pentru video, folosește endpoint-ul de quote relevant.

Nu presupune capabilități după numele modelului. Verifică model_spec.capabilities pentru web search, reasoning, E2EE, X search, multiple images, function calling, audio input sau video input.

Nu expune API keys, wallet keys, bearer tokens, SIWE payloads sau răspunsuri care conțin date sensibile. Nu efectua top-up, creare/ștergere de chei sau apeluri plătite fără acord explicit.

Graph View