Grimoire

Ghid operator pentru Venice Chat Completions

4 min read

Ghid operator pentru Venice Chat Completions

Ce face

venice-chat acoperă endpoint-ul principal de text din Venice: POST /api/v1/chat/completions. Este o interfață compatibilă cu API-ul OpenAI pentru răspunsuri de tip chat, cu extensii Venice în obiectul separat venice_parameters.

Schema de bază: trimiți model, messages și, opțional, parametri de sampling, streaming, tool calling, reasoning, prompt caching sau format de răspuns. Extensiile Venice includ web search, scraping pentru URL-urile din ultimul mesaj user, characters publice, E2EE pe modele compatibile, control pentru thinking, X/Twitter search pe modele compatibile și citări web.

Ghidul acesta este parte din All guides.

Când îmi folosește

Folosește venice-chat când ai nevoie de generare text prin LLM cu control API direct:

  • conversații cu roluri system, developer, user, assistant și tool;
  • streaming prin SSE;
  • output structurat cu response_format, preferabil json_schema;
  • input multimodal: imagini, audio sau video, dacă modelul ales suportă asta;
  • tool calling prin tools, tool_choice și parallel_tool_calls;
  • prompt caching pentru prompturi sau documente mari;
  • reasoning controls, de la none până la max;
  • web search, web scraping sau X search server-side, unde modelul și contul permit.

Pentru API-ul Alpha mai nou, folosește capabilitatea separată venice-responses. Nu presupune că toate funcțiile din chat/completions există identic acolo; E2EE, de exemplu, ține de /chat/completions.

Cum îl invoc / declanșez

Sursa nu definește o comandă universală de runtime pentru skill. Declanșarea depinde de mediul care expune capabilitatea. Contractul stabil este apelul HTTP:

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": "Why is the sky blue?"}]
  }'

model și messages sunt obligatorii. Nu pune cheia API în ghiduri, loguri, screenshoturi sau exemple publice. Folosește placeholder și gestionează cheia prin mecanismul local de secrete.

Exemplu practic

Cerere minimală cu web search și citări activate:

{
  "model": "zai-org-glm-5-1",
  "messages": [
    {
      "role": "user",
      "content": "Rezuma cele mai importante puncte despre subiectul acesta."
    }
  ],
  "venice_parameters": {
    "enable_web_search": "auto",
    "enable_web_citations": true
  }
}

Dacă biblioteca folosită nu permite venice_parameters, unele opțiuni pot fi puse ca suffix pe model:

zai-org-glm-5-1:enable_web_search=on
kimi-k2-6:strip_thinking_response=true&enable_web_search=auto
zai-org-glm-5-1:character_slug=alan-watts

Suffix-urile acceptate includ web search, citări, scraping, character slug, include/return search results, include_venice_system_prompt, strip_thinking_response și disable_thinking. Cheile necunoscute sunt ignorate silențios, deci verifică exact numele parametrului.

Output / unde aterizează

Răspunsul standard este un obiect OpenAI-style chat.completion, cu id, object, choices[].message și usage.

Cu stream: true, output-ul vine ca text/event-stream: linii data: cu obiecte chat.completion.chunk, terminate prin data: [DONE]. Dacă setezi stream_options.include_usage: true, usage-ul apare în chunk-ul final.

Pentru web search, citările apar în venice_parameters.web_search_citations[], cu url, title, content și date. Dacă activezi enable_web_citations, modelul poate insera superscripturi inline de tip ^1^. Cu return_search_results_as_documents, rezultatele pot apărea și ca tool call sintetic venice_web_search_documents.

Limite / gotchas

max_tokens este deprecated; preferă max_completion_tokens. Ține n: 1 dacă vrei costuri controlate.

Audio input acceptă doar base64 inline, nu URL-uri. Formatele includ wav, mp3, aiff, aac, ogg, flac, m4a, pcm16, pcm24.

Imaginile pot fi URL public sau data:image/...;base64,.... URL-urile trebuie să fie accesibile public din rețeaua Venice; localhost și linkurile semnate fără acces public pot eșua. Modelele vision cu o singură imagine păstrează doar imaginile din ultimul mesaj user.

Video acceptă URL public, uneori inclusiv YouTube în funcție de provider, sau data:video/mp4;base64,.... Formatele includ mp4, mpeg, mov, webm.

enable_e2ee și enable_x_search se setează doar prin venice_parameters, nu prin suffix. enable_x_search cere model cu suport X search și poate avea cost suplimentar.

include_venice_system_prompt este implicit true. character_slug înlocuiește promptul Venice implicit; combină cu include_venice_system_prompt: false doar când vrei control complet.

Pentru reasoning multi-turn pe modele care returnează reasoning_details, trimite reasoning_details înapoi neschimbat la următorul turn.

Erori comune: 402 sold insuficient, 413 payload prea mare, 422 conținut respins de policy, 429 rate limit.

Graph View