Pular para o conteúdo principal
POST
Criar uma conclusão de chat

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/chat/completions aceita todas as ferramentas de servidor, exceto phaseo:apply_patch; o guia Ferramentas de servidor lista todas elas.
Cada chamada de ferramenta de servidor é contabilizada em usage.server_tool_use:
phaseo:web_search adiciona web_search_requests, web_search_results e web_search_extra_results; phaseo:web_fetch adiciona web_fetch_requests. 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

Modelos de raciocínio retornam o raciocínio na mensagem do assistente em dois campos:
  • reasoning_content: o texto do raciocínio, quando o provedor retorna algum.
  • reasoning_details: uma matriz de blocos de raciocínio. Cada entrada tem um type igual a reasoning.text, reasoning.summary ou reasoning.encrypted, um index e um format que indica a família do provedor, por exemplo anthropic-claude-v1 ou google-gemini-v1.
As entradas podem carregar o estado do provedor de que o modelo precisa no passo seguinte de um loop de ferramentas: Durante o streaming, um delta de reasoning_details chega assim que cada bloco de raciocínio termina.
Envie de volta cada mensagem do assistente com o reasoning_details inalterado, em todas as solicitações, não só em loops de ferramentas. Nunca descarte, edite nem reordene entradas, criptografadas ou não, incluindo entradas sem texto.
Os valores de signature e data são opacos e registram o provedor e o modelo que os produziram. O Phaseo os envia somente para essa família de provedor e esse modelo, de modo que um fallback para outro provedor os descarta em vez de falhar. Sem eles, modelos Claude no modo de pensamento manual executam o passo seguinte do loop de ferramentas sem pensamento, 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
messages
object[]
obrigatório
Minimum array length: 1
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.

reasoning
object
reasoning_effort
enum<string>

Alias compatível com OpenAI para reasoning.effort.

Opções disponíveis:
none,
instant,
minimal,
low,
medium,
high,
xhigh,
max
frequency_penalty
number
Intervalo obrigatório: -2 <= x <= 2
logit_bias
object
max_completion_tokens
integer
Intervalo obrigatório: x >= 1
max_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
presence_penalty
number
Intervalo obrigatório: -2 <= x <= 2
seed
integer
Intervalo obrigatório: -9223372036854776000 <= x <= 9223372036854776000
store
boolean
stream
boolean
padrão:false
stream_options
object
temperature
number
padrão:1
Intervalo obrigatório: 0 <= x <= 2
tools
object[]

Definições de ferramentas para chamadas de função do modelo e ferramentas de servidor do gateway. As ferramentas integradas incluem data e hora, busca na web, busca de páginas, Advisor, Subagent, Fusion, busca de modelos, geração de imagens e criação de patches.

max_tool_calls
integer
Intervalo obrigatório: x >= 1
parallel_tool_calls
boolean
padrão:true
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
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.

logprobs
boolean
padrão:false
top_logprobs
integer
Intervalo obrigatório: 0 <= x <= 20
top_p
number
Intervalo obrigatório: 0 <= x <= 1
stop
response_format
modalities
enum<string>[]
Opções disponíveis:
text,
image,
audio
image_config
object
usage
boolean
provider

Seletor de provedor. Use uma string para um único provedor ou opções de roteamento como { "only": ["groq"] }.

Opções disponíveis:
openai,
anthropic,
google-ai-studio,
gemini,
mistral,
x-ai,
xai,
groq,
together
provider_options
object

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

user_id
string
user
string
include_reasoning
boolean

Aceito por compatibilidade. O raciocínio é retornado sempre que o modelo o produz (reasoning_content e reasoning_details), qualquer que seja o valor deste campo.

prediction
object

Saída prevista, para respostas mais rápidas quando a maior parte da resposta já é conhecida de antemão. Encaminhada aos modelos da OpenAI, Mistral e Moonshot; os demais provedores a ignoram.

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
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
meta
boolean
padrão:false
echo_upstream_request
boolean
debug
object

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

Resposta

Resposta de conclusão de chat

id
string
nativeResponseId
string | null
object
string
created
integer
model
string
provider
string
choices
object[]
usage
object
Última modificação em 12 de novembro de 2026