Pular para o conteúdo principal
Consulte o tipo, os valores aceitos e o padrão de um campo de solicitação no Chat Completions (/v1/chat/completions), no Responses (/v1/responses) e no Anthropic Messages (/v1/messages). O suporte ainda varia por modelo e provedor: a tabela de início rápido de cada página de modelo mostra quais parâmetros os provedores ativos dele suportam em cada endpoint. Para dicas de ajuste, consulte Parâmetros de inferência.

Parâmetros não suportados

Se o provedor que atende uma solicitação não suporta um dos parâmetros de amostragem opcionais dela, o Phaseo descarta esse parâmetro: ele não é enviado ao upstream e a solicitação não é rejeitada, então clientes que sempre enviam os padrões da OpenAI continuam funcionando. O Phaseo decide por provedor, primeiro pelo perfil do provedor e depois pelos parâmetros de catálogo da rota. Se uma rota não declara parâmetros, apenas a verificação de catálogo é ignorada; os parâmetros que o perfil do provedor marca como não suportados continuam sendo descartados, como top_k na Cohere ou stop na Reflection. Um ttl de cache de prompt de 12h também é removido em rotas que não aceitam o cache de 12 horas da OpenAI, e é informado como prompt_cache_options.ttl ou prompt_cache_breakpoint.ttl; consulte Cache de prompt. As respostas bem-sucedidas listam os parâmetros descartados que o corpo da solicitação enviou:
  • no cabeçalho X-Phaseo-Dropped-Params, como X-Phaseo-Dropped-Params: top_k, min_p;
  • em meta.routing.dropped_params quando a solicitação define meta: true, como [{"param": "top_k", "reason": "unsupported_by_provider"}].
Um parâmetro que veio de uma predefinição ou de um padrão, e não do corpo da solicitação, pode ser descartado sem aparecer em nenhum dos dois lugares. Ele ainda fica registrado nos diagnósticos de roteamento armazenados com a solicitação.

Escolher o modelo

model

O ID de modelo do Phaseo a executar, como openai/gpt-6-astra. Obrigatório. Use o ID mostrado no início rápido da página do modelo; ele é a escolha mais segura para automação e integrações de longa duração. O nome de uma predefinição, como @support-triage, também funciona aqui.

models

Modelos de fallback, tentados em ordem depois de model. model continua obrigatório e sempre é executado primeiro. A entrada seguinte só é tentada quando uma tentativa falha com 429, 500, 502, 503 ou 504. Tipo string[] · Entradas de 1 a 25; duplicatas e entradas iguais a model são ignoradas · Exemplo ["anthropic/claude-sonnet-5.5", "google/gemini-4-argon"]
  • Cada tentativa é validada, registrada e cobrada como uma solicitação própria. O campo model da resposta e o rastreamento de roteamento mostram o modelo que respondeu.
  • Solicitações em streaming só fazem fallback antes do primeiro byte; tarefas de vídeo e de música, apenas no envio.
  • Os fallbacks de uma rota dinâmica anexada têm precedência. Predefinições são aceitas como entradas. phaseo/auto não pode ser combinado com models.
  • Solicitações em lote, em tempo real e de conselho rejeitam models com 400.
  • Endpoints multipart aceitam campos models repetidos, campos models[] ou uma única matriz JSON.
Consulte Fallbacks de modelo no nível da solicitação.

stream

Retorna a saída por Server-Sent Events à medida que ela é gerada, em vez de um único corpo de resposta. Tipo boolean · Padrão false Use-o em interfaces de chat e respostas longas. Deixe-o desativado quando quiser uma única resposta JSON, mais simples de repetir e analisar. Chamadas de ferramentas e saída estruturada podem ser transmitidas de forma diferente conforme o provedor. Consulte Streaming.

Amostragem

temperature

O grau de aleatoriedade na seleção de tokens. Valores mais baixos geram uma saída mais conservadora e repetível; valores mais altos geram mais variedade, mas menos consistência e aderência ao esquema. Tipo number · Intervalo 0–2 no Chat Completions e no Responses, 0–1 no Messages · Padrão o do provedor (o Phaseo não envia nada quando não está definido) Comece entre 0.2 e 0.7, e com valores baixos para extração, classificação e JSON. Ajuste temperature ou top_p, não os dois ao mesmo tempo. Uma temperatura alta em um modelo muito quantizado pode tornar a saída instável.

top_p

Amostragem por núcleo: o modelo escolhe entre o menor conjunto de tokens cuja probabilidade somada atinge top_p. Valores mais baixos geram uma saída mais estreita e focada. Tipo number · Intervalo 0–1 · Padrão o do provedor 0.9–1.0 com uma temperature moderada é um bom ponto de partida.

top_k

Limita a amostragem aos k tokens mais prováveis em cada passo. Valores mais baixos tornam a saída mais previsível. Nem todo provedor o suporta. Tipo integer · Intervalo -1 ou mais no Chat Completions, 0 ou mais no Messages · Padrão o do provedor

min_p

Restringe a amostragem descartando tokens abaixo de um limite mínimo de probabilidade. Tipo number · Intervalo 0–1 · Padrão o do provedor

frequency_penalty

Penaliza os tokens na proporção de quantas vezes já apareceram. Aumente-o quando o modelo entrar em loop ou repetir frases. Tipo number · Intervalo -2–2 · Padrão o do provedor, geralmente 0

presence_penalty

Penaliza qualquer token que já tenha aparecido, o que leva o modelo a novos assuntos e palavras. Tipo number · Intervalo -2–2 · Padrão o do provedor, geralmente 0

repetition_penalty

Um controle antirrepetição específico do provedor, separado das duas penalidades acima. O efeito exato varia mais de um provedor para outro. Tipo number · Intervalo maior que 0; os provedores costumam aceitar até 2 · Padrão o do provedor

logit_bias

Torna tokens específicos mais ou menos prováveis. As chaves são IDs de token do tokenizador do modelo; os valores são o viés a adicionar. Tipo object (ID do token para número) · Padrão não definido

seed

Solicita amostragem com semente, para depuração e testes de regressão. Uma saída idêntica não é garantida entre provedores nem após mudanças na infraestrutura do provedor. Tipo integer · Padrão não definido

Tamanho da saída e parada

max_tokens

Limita os tokens de saída no Chat Completions e é obrigatório no Messages. Use-o para controlar custo e latência; um valor pequeno demais corta a saída. Tipo integer · Intervalo 1 ou mais (0 ou mais no Messages) · Padrão o do provedor no Chat Completions

max_output_tokens

Limita os tokens de saída no Responses. Mesma finalidade de max_tokens; envie o nome que o seu endpoint usa. Tipo integer · Intervalo 1 ou mais · Padrão o do provedor

max_completion_tokens

Limita os tokens de saída no Chat Completions; é o nome mais recente da OpenAI para max_tokens. Não misture os dois em uma solicitação. Tipo integer · Intervalo 1 ou mais · Padrão o do provedor

stop

Uma ou mais sequências que encerram a geração, como o fim de um modelo de texto ou um marcador de protocolo. No Messages, o campo é stop_sequences e recebe uma matriz. Tipo string ou string[] · Padrão não definido

Probabilidades dos tokens

logprobs

Retorna a probabilidade logarítmica de cada token de saída, para avaliação, ranqueamento e pontuação de confiança. Tipo boolean · Padrão false

top_logprobs

Retorna os tokens alternativos mais prováveis em cada posição, com suas probabilidades logarítmicas. Exige logprobs: true. Tipo integer · Intervalo 0–20

Ferramentas

tools

As ferramentas que o modelo pode chamar. Use o esquema de ferramentas da OpenAI, a menos que a referência do endpoint diga o contrário; o Messages usa o da Anthropic. Declarar uma ferramenta não obriga o modelo a chamá-la. Tipo array · Padrão não definido

tool_choice

Se o modelo pode chamar ferramentas: none para apenas texto, auto para deixar o modelo decidir, required para forçar uma chamada, ou um objeto que indica uma ferramenta. Tipo string ou object

parallel_tool_calls

Permite várias chamadas de ferramentas em um turno. Defina como false quando suas ferramentas precisarem ser executadas uma de cada vez, por exemplo quando têm efeitos colaterais em ordem. Tipo boolean · Padrão o do provedor (o Phaseo não envia nada quando não está definido)

max_tool_calls

Limita quantas chamadas de ferramentas o modelo faz na solicitação. Tipo integer · Intervalo 1 ou mais · Padrão não definido

Saída estruturada

response_format

Pede texto simples, JSON ou uma saída que corresponda a um esquema JSON. Os formatos aceitos dependem do endpoint e do provedor. Tipo string ou object · Padrão o do endpoint e do provedor

json_schema

O esquema JSON ao qual a saída precisa corresponder, definido dentro de response_format ({"type": "json_schema", "json_schema": {...}}). Mantenha os esquemas estreitos e específicos da tarefa para uma aderência melhor. Tipo object

structured_outputs

Não é um campo de solicitação. Na página de um modelo, ele marca os endpoints cujos provedores ativos suportam saída restrita por esquema. Solicite-a com response_format.

Raciocínio

reasoning

Configura o raciocínio em modelos que o suportam. Campos não definidos mantêm o padrão do modelo. Um esforço maior ajuda em problemas difíceis e custa mais latência e tokens.

reasoning_effort

A forma abreviada de reasoning.effort no Chat Completions. Tipo string · Valores none, instant, minimal, low, medium, high, xhigh, max · Padrão o do modelo

reasoning_tokens

Não é um campo de solicitação. Na página de um modelo, ele marca as rotas que informam tokens de raciocínio ou aceitam um orçamento de raciocínio. Defina o orçamento com reasoning.max_tokens.

include_reasoning

Aceito no Chat Completions por compatibilidade, sem efeito: o conteúdo e os resumos de raciocínio são retornados sempre que o modelo os produz. A saída de raciocínio pode ser grande, e nem todo modelo a retorna. Para reduzi-la, diminua reasoning.effort ou defina reasoning.enabled como false. Tipo boolean

Nível de serviço e cache de prompt

service_tier

Escolhe um nível de velocidade e preço no Chat Completions, no Responses e no Messages, quando o modelo e o provedor o suportam. O Phaseo associa cada valor ao controle próprio do provedor. Tipo string · Padrão standard batch não é um nível e é rejeitado; use a Batch API. Com um SDK oficial da Anthropic apontado para o Phaseo, prefira os valores auto e standard_only da Anthropic em /v1/messages; para ultrafast, priority, flex ou fast, use HTTP direto ou o Chat Completions e o Responses. Consulte Níveis de serviço.

prompt_cache_key

Mantém solicitações que compartilham um prefixo de prompt, como os passos de um loop de agente, no provedor que guarda o cache delas. Tipo string · Padrão não definido · Endpoints Chat Completions, Responses, Messages O Phaseo fixa a chave no provedor e na rota (implantação ou região) que atendeu a primeira solicitação bem-sucedida e mantém ali as solicitações seguintes com a mesma chave até que esse provedor falhe, a cota gerenciada do Phaseo nele se esgote ou sua política de roteamento deixe de permiti-lo. As fixações são por espaço de trabalho e duram o mesmo tempo que a retenção de cache do provedor. Consulte Afinidade de provedor. O Phaseo envia ao upstream um hash do ID do seu espaço de trabalho e da chave, nunca a chave bruta, então dois espaços de trabalho que escolhem a mesma chave não compartilham um cache de provedor. As respostas repetem a chave que você enviou. Provedores cuja API rejeita o campo não o recebem, e enviá-lo nunca exclui um provedor do roteamento. Sem uma chave, o Phaseo deriva a afinidade da solicitação, mas uma chave explícita funciona melhor em conversas longas e sessões de agente.

prompt_cache_options

Modo e duração do cache de prompt na OpenAI e no Azure OpenAI GPT-5.6 e posteriores (incluindo o GPT-6 Astra), na DeepInfra e na Moonshot AI. Tipo object · Campos mode (implicit ou explicit), ttl Use {"mode": "explicit", "ttl": "30m"} para que a OpenAI armazene em cache apenas os pontos de interrupção que você define. Uma duração que a rota não aceita, como 12h no Azure OpenAI ou 1h em um modelo da Moonshot AI sem preço de 1 hora, é removida e listada em X-Phaseo-Dropped-Params. Todos os outros provedores, e os modelos da OpenAI anteriores ao GPT-5.6, não recebem prompt_cache_options; esses modelos da OpenAI usam prompt_cache_retention. provider_options.openai.prompt_cache_options também é aceito; o valor de nível superior prevalece.

cache_control

No nível superior, define uma política de cache de prompt do Claude. Em um bloco de conteúdo, uma definição de ferramenta ou um resultado de ferramenta, marca um ponto de interrupção de cache. Tipo object · Campos type, ttl, scope Nível superior. Aceito no Chat Completions, no Responses e no Messages. Aplica-se ao Claude na Anthropic, ao Claude na AWS, ao Amazon Bedrock e ao Google Vertex AI: o Phaseo coloca até quatro pontos de interrupção de acordo com scope (all_text, last_user_message, agent ou none). Os outros provedores o ignoram. provider_options.anthropic.cache_control é a mesma configuração e prevalece quando os dois são enviados. Em um bloco. O Phaseo envia o ponto de interrupção às rotas do Claude, ao Alibaba Model Studio e à Venice, converte-o em prompt_cache_breakpoint para a OpenAI e o Azure OpenAI GPT-5.6 e posteriores, e o remove para os outros provedores. O próprio prompt_cache_breakpoint: {"mode": "explicit"} da OpenAI é aceito nos mesmos blocos e prevalece quando um bloco tem os dois. Use type: "ephemeral" com um ttl de 5m (padrão) ou 1h. A Anthropic aceita no máximo quatro pontos de interrupção por solicitação; quando você marca mais, o Phaseo mantém o primeiro e os três mais recentes. Consulte Cache de prompt.

prompt_cache_retention

Retenção do cache de prompt em modelos da OpenAI e do Azure OpenAI anteriores ao GPT-5.6. Tipo string · Valores in_memory, 24h O Phaseo o envia apenas a esses modelos, e somente os modelos que a OpenAI lista aceitam 24h. O GPT-5.6 e posteriores usam prompt_cache_options.ttl, e os outros provedores não recebem o campo. provider_options.openai.prompt_cache_retention também é aceito; o valor de nível superior prevalece.

Roteamento e configurações de provedor

provider

Restringe quais provedores podem atender a solicitação e como eles são classificados. routing é aceito como alias. Consulte Roteamento e fallbacks. A correspondência de quantizations ignora maiúsculas e minúsculas, espaços, hifens e sublinhados, e trata nomes sem ambiguidade como aliases, como float8 e FP8, ou bfloat16 e BF16. Ofertas sem dados de quantização são excluídas sempre que o filtro está definido. Se nenhuma oferta corresponder, a solicitação falha com um erro que lista as quantizações solicitadas e as disponíveis, em vez de rotear para uma variante diferente.

provider_options

Configurações nativas do provedor que o Phaseo repassa, indexadas por provedor, enquanto o resto da solicitação segue o esquema comum. Tipo object google.cached_content indica um cache explícito do Gemini e só funciona com a sua própria credencial: uma chave de API do Google no Google AI Studio, ou uma credencial do Vertex AI no Vertex AI. No Vertex AI, o Phaseo envia a solicitação ao projeto e à localização do nome completo do cache (projects/{project}/locations/{location}/cachedContents/{id}); um nome curto usa o project_id e a region do JSON da sua conta de serviço. Com as credenciais do Phaseo, a solicitação retorna 400. google.cache_control e google.cache_ttl são aceitos, mas não são enviados ao Google. Prefira cache_control de nível superior para o Claude, prompt_cache_options para a OpenAI GPT-5.6 e posteriores, e prompt_cache_retention para modelos anteriores da OpenAI. Consulte Cache de prompt.

Extras da resposta e depuração

meta

Adiciona à resposta um objeto meta com detalhes de roteamento, como meta.routing.dropped_params. Tipo boolean · Padrão false

usage

Solicita a contabilização de uso no corpo da resposta, em vez de depender de cabeçalhos ou do painel. Tipo boolean · Padrão não definido

debug

Retorna rastreamentos de roteamento e payloads do upstream. A saída de depuração pode conter o conteúdo da sua solicitação, então use-a apenas em desenvolvimento ou em ambientes rigidamente controlados. Consulte Depurar uma solicitação.

Exemplo de solicitação

Última modificação em 5 de novembro de 2026