Grimoire

Ghid pentru descoperirea modelelor Venice

4 min read

Ghid pentru descoperirea modelelor Venice

Ce face

venice-models este capabilitatea folosită pentru a descoperi modelele disponibile în Venice, ce pot face, ce constrângeri au și cum sunt taxate. În loc să trimiți cereri către un model ales din memorie sau hard-codat, citești catalogul curent și alegi pe baza datelor expuse de API.

Capabilitatea acoperă trei endpoint-uri read-only, toate prin GET:

  • /models — catalogul complet de modele, cu model_spec: capabilități, constrângeri, pricing și stare.
  • /models/traits — mapare trait → model ID, de exemplu default, fastest, default_reasoning, highest_quality.
  • /models/compatibility_mapping — aliasuri legacy, OpenAI-style sau vendor-style → model ID Venice concret.

Toate acceptă opțional filtrul ?type=, cu valori precum text, image, video, music, tts, asr, embedding, upscale, inpaint, all, code.

Când îmi folosește

Îți folosește când vrei să alegi modelul corect programatic, nu după ghicit. Ghicitu-i cum se fosilizează sistemele.

Cazuri tipice:

  • alegi la runtime un model după capabilități: vision, reasoning, function calling, E2EE, web search, X search, multi-image;
  • validezi request-ul înainte de execuție, folosind constraints: lungime prompt, aspect ratio, rezoluție, steps;
  • estimezi costul din pricing: per milion de tokens, per imagine, per secundă audio, per job sau per caractere;
  • transformi un trait, precum default_reasoning sau highest_quality, într-un model ID concret;
  • convertești aliasuri OpenAI-style, vendor-style sau legacy către modelul Venice compatibil;
  • eviți hard-coding-ul: catalogul se schimbă, deci cache-ul trebuie să fie scurt, de ordinul minutelor, nu zilelor.

Ghidul acesta aparține colecției All guides și este pentru operatori care vor să înțeleagă mecanica înainte să conecteze codul la ea.

Cum îl invoc / declanșez

Invocarea locală depinde de runtime-ul în care este instalată capabilitatea. La nivel API, endpoint-urile sunt directe:

curl "https://api.venice.ai/api/v1/models?type=text"
curl "https://api.venice.ai/api/v1/models/traits?type=text"
curl "https://api.venice.ai/api/v1/models/compatibility_mapping?type=text"

Toate trei sunt autentificate ca rutele /api/v1: Bearer API key sau x402 SIWE. Nu pune cheia în guide-uri publice, loguri, exemple, stack traces sau output trimis către utilizator. Dacă lipsește autentificarea, nu inventa rezultate: oprește fluxul și cere configurarea credențialelor prin mecanismul runtime-ului.

Exemplu practic

Să zicem că ai nevoie de un model text care suportă reasoning și function calling.

Fluxul sănătos este:

  1. Chemi /models?type=text.
  2. Parcurgi data[].
  3. Ignori modelele cu model_spec.offline: true.
  4. Eviți modelele beta dacă nu ai acces beta; beta: true poate cere cheie sau plan eligibil.
  5. Verifici model_spec.capabilities.supportsReasoning.
  6. Verifici model_spec.capabilities.supportsFunctionCalling.
  7. Compari availableContextTokens, maxCompletionTokens și pricing.
  8. Tratezi pricing ca opțional: poate lipsi la modele free sau interne.
  9. Alegi modelul cu raportul potrivit între cost, context, disponibilitate și capabilități.

Dacă nu vrei să alegi explicit, poți chema /models/traits?type=text, rezolvi un trait precum default_reasoning sau function_calling_default, apoi cache-uiești rezultatul pentru sesiune. Pentru aliasuri OpenAI-style sau vendor-style, folosește /models/compatibility_mapping, apoi verifică separat capabilitățile modelului rezultat. Mapping-ul rezolvă ID-uri, nu garantează că modelul suportă vision, tools sau altă funcție.

Output / unde aterizează

Endpoint-urile întorc obiecte de tip listă.

/models întoarce data[], fiecare element având un id și un model_spec. În model_spec pot apărea câmpuri precum:

  • name, description;
  • availableContextTokens, maxCompletionTokens;
  • privacy;
  • beta, betaModel, offline;
  • capabilities;
  • constraints;
  • pricing;
  • regionRestrictions;
  • deprecation.

/models/traits întoarce o mapare de trait-uri către model IDs. Pentru type=text, pot apărea chei precum default, fastest, most_uncensored, default_reasoning, default_code, default_vision, function_calling_default, most_intelligent. Pentru type=image, pot apărea chei precum default, fastest, highest_quality.

/models/compatibility_mapping întoarce aliasuri către modele Venice concrete. Este util când portezi cod existent sau accepți model IDs în stil OpenAI/vendor de la un client.

Limite / gotchas

traits diferă pe type; nu există un „default” global sigur. Pasează mereu ?type=....

type=code este un filtru convenabil peste modele text optimizate pentru cod, cu același shape de răspuns ca type=text.

pricing nu este uniform. LLM-urile și embeddings folosesc de obicei preț per milion de tokens. TTS folosește milionul de caractere input. ASR folosește secunde audio. Image poate fi flat per imagine sau pe rezoluții. Music / long audio poate fi per job, per secundă, per caractere sau pe bucket-uri de durată.

Video pricing nu este returnat momentan pe /models; folosește POST /video/quote pentru prețul autoritativ per request.

Pentru image, blocul global upscale.{2x,4x} din pricing nu înseamnă că modelul respectiv poate face upscale. Verifică separat modelul potrivit de upscale/inpaint.

Câmpurile TTS interne precum supportsPromptParam, supportsTemperatureParam și supportsTopPParam nu sunt garantat expuse în /models; schema endpoint-ului speech rămâne matricea reală de suport.

Valoarea private a câmpului privacy indică zero data retention. regionRestrictions[] poate produce 403 în afara regiunilor permise. deprecation.date este termen de migrare, nu ornament.

Graph View