Grimoire

Ghid ELI20 pentru Venice Responses API

4 min read

Ghid ELI20 pentru Venice Responses API

Ce face

venice-responses descrie endpoint-ul Alpha POST /api/v1/responses din Venice: o formă compatibilă cu stilul OpenAI Responses API.

Diferența importantă față de /chat/completions: răspunsul nu vine ca un singur message.content, ci ca output[], un array de blocuri tipate:

  • reasoning — sumar de raționament de la modele thinking, când există
  • message — textul final al asistentului
  • function_call — apel de tool cerut de model
  • web_search_call — semnal că web search-ul built-in a fost folosit

Asta ajută agenții și runtime-urile care trebuie să separe curat textul final, apelurile de tool, evenimentele interne și citările. Nu mai scormonești într-un blob de text după oase. Sunt deja etichetate.

Vezi și All guides pentru restul ghidurilor.

Când îmi folosește

Folosește venice-responses când clientul tău așteaptă forma OpenAI Responses: output[] cu obiecte tipate.

Este potrivit pentru:

  • agenți care trebuie să distingă între mesaj final, reasoning sumarizat și tool calls;
  • clienți care reconstruiesc răspunsul din evenimente SSE;
  • fluxuri unde web search-ul built-in trebuie detectat explicit prin web_search_call și citări în annotations[].

Dacă nu ai nevoie de această formă, folosește venice-chat. Are mai multe funcții, mai multe modele și suport complet pentru Venice parameters.

Cum îl invoc / declanșez

La nivel API, forma minimă este:

curl https://api.venice.ai/api/v1/responses \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "zai-org-glm-5-1",
    "input": "Explain why the sky is blue in one paragraph."
  }'

Autentificarea este aceeași ca în restul API-ului: Authorization: Bearer <key> sau X-Sign-In-With-X: <SIWE>. Nu pune cheia în ghiduri, loguri, issue-uri sau exemple reale.

input poate fi string simplu sau array de input items tipate. Pentru context de sistem sau developer, pune la început un mesaj cu role: "system" sau role: "developer".

Exemplu practic

Un request poate include model, input, tool-uri, alegerea tool-ului, reasoning effort și controale standard de generare:

{
  "model": "zai-org-glm-5-1",
  "input": "Rezumat scurt despre Rayleigh scattering.",
  "reasoning": {
    "effort": "low"
  },
  "tools": [
    {"type": "web_search"}
  ],
  "tool_choice": "auto",
  "stream": true,
  "venice_parameters": {
    "enable_web_search": "on",
    "enable_e2ee": false
  }
}

tools poate conține tool-uri de tip function sau built-in web_search, dacă modelul le suportă. Un function_call nu execută nimic singur: clientul tău decide dacă are voie să ruleze tool-ul, rulează în propriile limite și întoarce rezultatul potrivit după call_id.

Cu stream: true, consumi evenimentele SSE în ordine și reconstruiești output[]. Evenimentul response.completed trebuie să aibă aceeași formă ca răspunsul non-streamed.

Output / unde aterizează

Răspunsul aterizează într-un obiect response, cu câmpuri ca id, object, created_at, model, status, output și usage.

status poate fi completed, failed, in_progress sau cancelled. Dacă e failed, verifică error.code și error.message.

În output[], blocul message conține textul principal în content[], de obicei cu type: "output_text". Dacă web search-ul a produs citări, acestea apar în annotations[] ca url_citation.

Blocul reasoning poate avea summary[] și encrypted_content. summary[] este text lizibil; encrypted_content este opac și trebuie păstrat verbatim pentru continuări multi-turn cu tool calls. Nu îl interpreta, nu îl rescrie, nu îl “repari”. Acolo se nasc bug-urile cu ambiții.

Limite / gotchas

Endpoint-ul este Alpha. Schemele se pot schimba. Accesul prin Bearer API key este gated de responsesApiEnabled; fără flag poți primi 401. x402 poate permite pay-per-request, dar poate întoarce 402 dacă balanța nu ajunge.

Endpoint-ul este stateless: nu păstrează conversația între request-uri. Trimiți istoricul complet de fiecare dată.

Modelele E2EE-capable pot returna 400 dacă nu setezi venice_parameters.enable_e2ee: false. Pentru inferență end-to-end encrypted cu headere E2EE, folosește /chat/completions, nu /responses.

venice_parameters suportă doar subsetul documentat: character_slug, enable_e2ee, enable_web_search, enable_web_scraping, enable_web_citations, include_venice_system_prompt, include_search_results_in_stream. strip_thinking_response, disable_thinking și enable_x_search nu sunt cablate în Alpha.

Câmpuri OpenAI Responses precum instructions, metadata, parallel_tool_calls, response_format, store, previous_response_id și background nu sunt în schema Alpha Venice și pot fi ignorate sau respinse. Pentru JSON-schema structured output, folosește /chat/completions.

Graph View