Pular para o conteúdo principal
POST
Criar uma resposta

Usar ferramentas de servidor

Adicione uma ferramenta phaseo: a tools, ao lado das suas próprias ferramentas de função, e o Phaseo a executa quando o modelo a chama. /v1/responses aceita todas as ferramentas de servidor, incluindo phaseo:apply_patch, que só este endpoint suporta; o guia Ferramentas de servidor lista todas elas.
Cada chamada de ferramenta de servidor é contabilizada em usage.server_tool_use: O tipo antigo gateway:datetime continua funcionando. Com stream: true, o Phaseo executa os turnos de ferramenta por conta própria e depois transmite a continuação da resposta para você como um único stream.

Raciocínio em loops de ferramentas

Na OpenAI, no Azure OpenAI e na xAI, o Phaseo envia as solicitações do Responses ao upstream com store: false, então o raciocínio de um modelo continua entre os passos do loop de ferramentas somente por meio dos itens de saída reasoning. Cada item reasoning tem id, summary e content. Quando o provedor retorna estado de raciocínio, o item também tem encrypted_content, que contém um destes:
  • Raciocínio criptografado da OpenAI, do Azure OpenAI e da xAI. O Phaseo o solicita com include: ["reasoning.encrypted_content"] para modelos de raciocínio.
  • Assinaturas de pensamento e pensamento redigido do Claude.
  • Assinaturas de pensamento do Gemini, incluindo um item reasoning separado colocado logo antes da chamada de função a que a assinatura pertence.
  • O nível de esforço em que uma resposta do Claude foi executada, no último item reasoning da saída, que não tem texto.
As respostas em streaming trazem os mesmos itens em response.output_item.done e response.completed.
Envie de volta em input todos os itens de saída sem alterações em todas as solicitações, não só em loops de ferramentas. Nunca descarte, edite nem reordene itens reasoning, com ou sem encrypted_content, incluindo itens sem texto.
encrypted_content é opaco e registra o provedor e o modelo que o produziram. O Phaseo o envia somente para essa família de provedor e esse modelo, de modo que um fallback para outro provedor o descarta em vez de falhar. Sem ele, o Claude perde o raciocínio entre os passos do loop de ferramentas, e uma mudança de reasoning.effort reinicia o cache de prompts do Claude; veja Mudar o esforço de raciocínio no meio da conversa.

Autorizações

Authorization
string
header
obrigatório

Autenticação com token Bearer

Corpo

application/json

Um campo opcional de nível superior enviado como null é tratado como não definido, como se tivesse sido omitido.

model
string
obrigatório
input
obrigatório
models
string[]

Modelos de fallback opcionais e ordenados, tentados depois de model. model é obrigatório e é sempre o modelo principal. Quando uma tentativa falha com 429, 500, 502, 503 ou 504, a próxima entrada é tentada; os demais erros são retornados sem alteração. Aceita até 25 IDs de modelo ou predefinições; duplicatas e entradas iguais a model são ignoradas. Cada tentativa é validada, registrada e cobrada como uma solicitação separada, e o campo model da resposta e o rastreamento de roteamento mostram o modelo que atendeu a solicitação. Solicitações em streaming só recorrem a um fallback antes do primeiro byte, e trabalhos de vídeo e música apenas no envio. Solicitações de batch, realtime e council rejeitam models. Fallbacks definidos em uma rota dinâmica têm precedência, e phaseo/auto não pode ser combinado com models.

Required array length: 1 - 25 elements
Minimum string length: 1
Exemplo:
prompt
object

Preenche o template de prompt salvo em um preset. Omita model ou use a mesma referência, e envie uma conversa vazia ou os turnos a adicionar depois do template.

background
boolean
include
string[]
instructions
string
max_output_tokens
integer
Intervalo obrigatório: x >= 1
metadata
object
session_id
string

Identificador exclusivo para agrupar solicitações relacionadas (por exemplo, uma conversa ou um fluxo de trabalho de agente) para observabilidade.

Maximum string length: 256
parallel_tool_calls
boolean
previous_response_id
string

Não compatível. O Phaseo não armazena respostas, então solicitações que definem previous_response_id ou conversation retornam 400 unsupported_param. Envie a conversa inteira em input.

reasoning
object
service_tier
enum<string> | null

Seleciona um nível de roteamento ou preço suportado. auto (ou null) não pede nenhum nível específico e é roteado e cobrado como se o campo não estivesse definido; scale é tratado como default, o nível padrão.

Opções disponíveis:
standard,
default,
fast,
ultrafast,
priority,
flex,
batch,
auto,
scale
store
boolean
stream
boolean
temperature
number
Intervalo obrigatório: 0 <= x <= 2
text
object
plugins
object[]

Plugins do gateway para esta solicitação. web adiciona busca na web e web-fetch adiciona a leitura de páginas a qualquer modelo; response-healing corrige JSON malformado em respostas estruturadas sem streaming. Os padrões do workspace e do preset são combinados com esta lista. Um id de plugin desconhecido retorna 400 unknown_gateway_plugin.

Adiciona à solicitação a ferramenta de servidor phaseo:web_search, para que qualquer modelo possa pesquisar na web. A solicitação é executada, e as buscas são contadas e cobradas, exatamente como com uma ferramenta phaseo:web_search. Se a solicitação já tiver uma ferramenta de busca na web, o plugin não adiciona nada. As demais opções são ignoradas.

tool_choice

Estratégia de seleção de ferramentas. Os tipos de ferramentas de servidor do Phaseo são aceitos e convertidos em destinos de função ou ferramenta do provedor upstream. Um objeto allowed_tools é enviado como está para a OpenAI, com todas as ferramentas. Os demais provedores recebem apenas as ferramentas permitidas e seu modo (auto ou required), ou uma chamada forçada quando required permite exatamente uma ferramenta. Se allowed_tools listar uma ferramenta que tools não define, só a OpenAI pode atender à solicitação; caso contrário, é retornado um erro 400.

Opções disponíveis:
auto,
none,
required,
phaseo:datetime,
phaseo:web_search,
phaseo:web_fetch,
phaseo:subagent,
phaseo:fusion,
phaseo:search_models,
gateway:datetime,
gateway:web_search,
gateway:web_fetch
tools
object[]

Definições de ferramentas para chamadas de função do modelo e ferramentas de servidor do gateway. As ferramentas de servidor integradas do gateway são gateway:datetime, gateway:web_search e gateway:web_fetch.

top_p
number
Intervalo obrigatório: 0 <= x <= 1
truncation
enum<string>
Opções disponíveis:
auto,
disabled
user
string
prompt_cache_key
string | null

Agrupa solicitações relacionadas para que permaneçam no provedor que tem o cache de prompts delas. O Phaseo envia ao provedor um hash do seu workspace e desta chave, nunca a chave original.

prompt_cache_retention
enum<string>

Retenção do cache de prompts para modelos da OpenAI e da Azure OpenAI anteriores ao GPT-5.6. Prevalece sobre provider_options.openai.prompt_cache_retention.

Opções disponíveis:
in_memory,
24h
prompt_cache_options
object

Modo e TTL do cache de prompts para OpenAI e Azure OpenAI a partir do GPT-5.6 (ttl 30m, ou 12h na OpenAI) e para a DeepInfra (ttl 5m ou 1h). Removido para os demais provedores.

cache_control
object

Controle do cache de prompts. Use type ephemeral com um ttl opcional de 5m ou 1h. scope se aplica apenas a uma política de cache do Claude no nível superior. A Amazon Bedrock e o Google Vertex AI armazenam em cache o Claude 3.7 Sonnet, o 3.5 Sonnet e o 3 Opus por apenas 5 minutos; nessas rotas o ttl é removido, e um 1h removido é informado em X-Phaseo-Dropped-Params como cache_control.ttl.

safety_identifier
string | null
modalities
enum<string>[]
Opções disponíveis:
text,
image,
audio
image_config
object
provider_options
object

Opções específicas do provedor, se necessário.

usage
boolean
meta
boolean
echo_upstream_request
boolean
debug
object

Controles de depuração do gateway. Essas opções nunca são encaminhadas ao provedor.

provider
object

Preferências de roteamento de provedores para seleção pelo gateway.

Resposta

Resposta

id
string
object
string
created
integer
model
string
provider
string
provider_id
string
nativeResponseId
string | null
status
enum<string>
Opções disponíveis:
completed,
failed,
incomplete
finish_reason
string | null
meta
object
cost_nanos
number
cost_cents
integer
currency
string
pricing_lines
object[]
output
object[]
output_items
object[]
content
object[]
role
string
stop_reason
string
type
string
usage
object
Última modificação em 12 de novembro de 2026