POST /responses accetta richieste nel formato Responses API di OpenAI e restituisce elementi di output tipizzati come reasoning, message e function_call. Funziona con tutti i modelli di testo Venice e accetta una API key oppure l’autenticazione wallet x402.
I modelli OpenAI sono serviti in modo nativo, quindi si comportano come la Responses API di OpenAI. Tutti gli altri modelli passano attraverso un livello di traduzione con alcune lacune. Leggi Come vengono servite le richieste e Limitazioni prima di costruirci sopra.
Quando usarlo
Usa/responses quando il tuo client parla già il formato Responses, ad esempio coding agent e SDK basati su responses.create di OpenAI. È il modo migliore per eseguire agent in stile Codex sui modelli OpenAI tramite Venice.
Per i modelli non OpenAI, /chat/completions resta l’opzione più completa: supporta input di file, modelli E2EE e ogni opzione di venice_parameters su ogni modello.
Guida rapida
output di elementi tipizzati e un oggetto usage:
Come vengono servite le richieste
Venice serve ogni richiesta in una di due modalità.- Nativa. Le richieste per i modelli OpenAI vengono inoltrate alla Responses API di OpenAI senza traduzione. Questo vale per tutti i modelli
openai-*tranneopenai-gpt-oss-120b. Elementi della risposta, ID, ragionamento ed eventi dello stream vengono restituiti esattamente come li restituisce OpenAI. - Tradotta. Tutti gli altri modelli, più
openai-gpt-oss-120b, passano attraverso un livello di traduzione: Venice converte la richiesta in una richiesta Chat Completions, la esegue e riconverte il risultato. Tutto ciò che il formato Chat Completions non può esprimere viene ignorato o rifiutato. Vedi Limitazioni.
web_search, web_search: true o venice_parameters.enable_web_search), x_search, venice_parameters.character_slug e venice_parameters.enable_web_scraping. Le richieste con campi che la modalità nativa non può servire, elencati in Modalità nativa, ricadono allo stesso modo sulla modalità tradotta.
Un tool web_search di primo livello con external_web_access: false non forza la modalità tradotta. Venice lo omette e non attiva la ricerca web di Venice. I tool web_search attivi e i tool di ricerca caricati tramite la cronologia usano comunque la modalità tradotta.
Puoi controllare e ispezionare la modalità tramite header:
Le conversazioni sono stateless
Venice non memorizza le risposte, in nessuna delle due modalità. Invia l’intera conversazione ininput a ogni richiesta, aggiungendo gli elementi output precedenti ed eventuali risultati dei tool.
store viene sempre trattato come false. previous_response_id e conversation non possono essere risolti perché nulla viene memorizzato. Con la modalità auto predefinita, tali richieste vengono servite in modalità tradotta, dove quei campi vengono ignorati. Con x-venice-responses-mode: native restituiscono 400.
Modalità nativa
La modalità nativa supporta le funzionalità Responses supportate dall’endpoint di OpenAI, tra cui:instructions, applicate così come sono scritte.- Structured output con
text.format. OpenAI valida gli schemi in modo rigoroso, quindi uno schema non valido restituisce 400. Ad esempio,strict: truerichiedeadditionalProperties: false, ejson_objectrichiede la parola “json” da qualche parte nell’input. - Function tool e
tool_choicenella forma Responses di OpenAI{"type": "function", "name": "..."}, oltre alle chiamate parallele ai tool. - Tool eseguiti dal client:
custom(input in formato libero),namespace,tool_search,apply_patch,shellelocal_shellcon un ambiente locale, e computer use. - Riepiloghi del ragionamento, attivi per impostazione predefinita. I modelli di ragionamento restituiscono sempre
encrypted_contentsugli elementi di ragionamento. Rimanda quegli elementi ininputal turno successivo per mantenere il contesto di ragionamento del modello. - Prompt caching con
prompt_cache_key. Venice limita la chiave al tuo account, quindi non condivide mai una cache con altri utenti, e restituisce la tua chiave originale nella risposta. - Input di immagini, incluso
detail: "original", einput_fileconfile_datainline. - Modelli Pro (
*-pro), che eseguono automaticamente la modalità di ragionamento Pro di OpenAI.
instructions vengono applicate senza modifiche. Imposta venice_parameters.include_venice_system_prompt: true per aggiungerlo.
Le seguenti funzionalità richiedono memorizzazione lato server o risorse ospitate dal provider, quindi non sono disponibili in modo nativo:
Queste restrizioni si applicano anche ai tool caricati più avanti nella conversazione tramite elementi
additional_tools o tool_search_output. Anche un tool di ricerca Venice dichiarato lì instrada la richiesta verso la modalità tradotta.
I campi della richiesta non riconosciuti vengono trattati allo stesso modo: con auto la richiesta viene servita in modalità tradotta, e con native restituisce 400.
Streaming
Impostastream: true per ricevere server-sent event. Entrambe le modalità terminano lo stream con data: [DONE].
In modalità nativa, gli eventi sono esattamente quelli di OpenAI, incluso response.reasoning_summary_text.delta per i riepiloghi del ragionamento e response.function_call_arguments.delta per gli argomenti dei tool.
In modalità tradotta, gli eventi sono response.created, response.output_item.added, response.content_part.added, response.output_text.delta, response.function_call_arguments.delta, response.content_part.done, response.output_item.done e infine response.completed, response.incomplete o response.failed. Due eventi differiscono da quelli di OpenAI:
- Il testo del ragionamento viene trasmesso come
response.reasoning.delta, non tramite gli eventi di riepilogo del ragionamento di OpenAI. - Quando viene eseguita la ricerca web, un evento
response.web_search.donetrasporta i risultati della ricerca prima che venga trasmessa la risposta.
Parametri della modalità tradotta
La ricerca web viene fatturata come search augmentation, come su
/chat/completions.
Alcuni comportamenti della modalità tradotta da tenere in considerazione:
- Le
instructionsvengono applicate come messaggio di sistema. - Gli elementi
web_search_calldei turni precedenti sono accettati ininputcome cronologia della conversazione. - I tool custom restituiscono elementi
custom_tool_callcon l’inputgrezzo. Se un modello restituisce argomenti malformati per un tool custom, o chiama un tool non dichiarato nella richiesta, la chiamata viene restituita come un normalefunction_callcon gli argomenti originali, così il tuo client può segnalare un errore del tool e proseguire. - Mentre l’input di un tool custom viene trasmesso in streaming, il relativo elemento di chiamata e gli elementi successivi possono arrivare solo dopo che l’input è completo. Durante l’attesa, lo stream invia commenti SSE keep-alive.
- L’immagine con
detail: "original"viene inviata comehighai provider che non lo supportano.
Limitazioni
Queste lacune si applicano alla modalità tradotta: tutti i modelli non OpenAI,openai-gpt-oss-120b e le richieste ai modelli OpenAI che usano funzionalità esclusive di Venice. Salvo diversa indicazione, la richiesta va comunque a buon fine e il campo viene ignorato.