- o que um parâmetro faz
- qual tipo ele espera
- o intervalo típico ou os valores aceitos
- se afeta a qualidade, o custo, a latência ou o roteamento
Consulta rápida
Notas sobre endpoints
service_tier é compatível nas principais interfaces de solicitação de texto:
Use ultrafast, fast (ou priority onde houver suporte) e flex somente se a combinação de modelo e provedor os aceitar. Ultrafast seleciona o nível compatível mais rápido; fast e priority usam o mesmo roteamento e preço Fast. standard é o padrão quando service_tier é omitido.
Batch não é um valor de service_tier. Solicitações em lote usam a API Batch separada.
Em solicitações Messages compatíveis com Anthropic, os valores nativos upstream da Anthropic são auto e standard_only. O Phaseo pode normalizar ou mapear esses valores entre provedores, preservando o comportamento compatível com Anthropic em /v1/messages.
Se você usa um SDK oficial da Anthropic com uma URL base personalizada apontada para o Phaseo, prefira os valores nativos da Anthropic em /v1/messages. Para controles de nível normalizados entre provedores, como ultrafast, priority e flex, ou o alias fast da OpenAI, prefira solicitações HTTP diretas ou as APIs de texto nativas do gateway ou no estilo OpenAI.
Referência de parâmetros
model
Seleciona o ID do modelo do gateway para a solicitação.
Aceite um alias compatível somente se essa for sua intenção; nos demais casos, use o ID canônico exibido no início rápido de cada página de modelo. IDs canônicos são a opção mais segura para exemplos, automações e integrações duradouras.
stream
Em vez de aguardar o corpo de uma resposta final, retorna a saída gradualmente por Server-Sent Events.
Ative para interfaces de chat, exibição token a token ou respostas longas em que receber o conteúdo antes melhora a experiência. Deixe desativado quando quiser uma resposta JSON completa, novas tentativas mais simples ou análise estruturada mais fácil.
Observações:
O suporte a streaming varia conforme o endpoint.
Streaming costuma ser uma opção de transporte, não um controle de qualidade.
Fluxos com chamadas de ferramentas ou saídas estruturadas também podem ser transmitidos de forma diferente conforme o provedor.
temperature
Controla o grau de aleatoriedade na seleção de tokens.
Valores menores geram saídas mais conservadoras e repetíveis. Valores maiores aumentam a variedade, o que pode ajudar em brainstorms ou escrita criativa, mas também reduzir a consistência e a aderência ao esquema.
Boas aplicações:
- extração
- classificação
- saída JSON ou conforme a esquema
- geração criativa
temperature ou top_p, não os dois.
Temperatura alta combinada com quantização agressiva pode ampliar a instabilidade.
top_p
Aplica nucleus sampling, limitando os candidatos ao menor conjunto de tokens cuja probabilidade acumulada atinge top_p.
Valores menores restringem a massa de probabilidade da escolha do modelo e costumam gerar saídas mais seguras e focadas. Valores maiores permitem considerar mais tokens.
Observações:
Ajuste
top_p quando quiser ampliar ou reduzir o espaço de busca sem alterar a temperatura diretamente.
Para a maioria das aplicações, uma temperature moderada e um top_p próximo de 1,0 são um ponto de partida razoável.
top_k
Nos provedores compatíveis, restringe a amostragem aos k principais tokens candidatos em cada etapa.
Valores menores de
top_k restringem as escolhas do modelo e podem tornar a saída mais previsível. Valores maiores ampliam o conjunto de candidatos.
Observações:
top_k não está disponível em todos os provedores.
Considere-o um limitador mais explícito do conjunto de tokens do que top_p.
max_tokens
Limita o tamanho da saída em endpoints e provedores que ainda usam o campo max_tokens.
Use-o para controlar custos, latência e risco de truncamento. Se o valor for baixo demais, a saída poderá parecer incompleta mesmo que o modelo tenha funcionado corretamente.
max_output_tokens
Limita o tamanho da saída em rotas que usam max_output_tokens em vez de max_tokens.
Esse controle tem o mesmo significado que
max_tokens, mas você deve enviar o nome de campo esperado pelo endpoint ou pela interface do SDK escolhido.
max_completion_tokens
Limita o tamanho da saída em APIs de texto mais novas no estilo OpenAI que usam max_completion_tokens.
Este é outro campo de limite de tokens de saída. Use o nome esperado pelo endpoint em vez de misturar aliases de tamanho de saída em uma solicitação.
frequency_penalty
Desencoraja tokens repetidos proporcionalmente à frequência com que já apareceram.
Aumente o valor se o modelo entrar em loop, repetir frases ou usar demais as mesmas palavras.
presence_penalty
Desencoraja reutilizar tokens assim que eles aparecem, o que pode ajudar o modelo a explorar novos temas ou formas de expressão.
Em comparação com
frequency_penalty, este costuma ser um controle de novidade mais amplo, não de contagem de repetições.
repetition_penalty
Aplica um comportamento antirrepetição específico do provedor, fora dos campos clássicos de penalidade no estilo OpenAI.
A finalidade é semelhante à de
frequency_penalty e presence_penalty, mas o significado varia mais entre provedores. Trate-o como um comportamento nativo do provedor, não como um controle universalmente idêntico.
seed
Solicita amostragem determinística quando o provedor upstream oferece suporte à geração com seed.
Use-o para depuração, testes de regressão e reprodução do comportamento dentro do que a plataforma upstream permite. A geração com seed melhora a reprodutibilidade, mas não garante determinismo exato em todos os provedores ou após mudanças na infraestrutura.
stop
Define uma ou mais sequências que encerram a geração antecipadamente.
É útil quando você precisa de limites rígidos para a saída, como parar antes de um rodapé, delimitador de ferramenta ou próxima seção sintética.
logprobs
Solicita metadados de probabilidade por token quando disponíveis.
É mais útil para análise, avaliação, classificação, depuração e fluxos relacionados à confiança. Normalmente não é necessário em respostas padrão de produto.
top_logprobs
Solicita os principais tokens candidatos alternativos para cada posição da saída, junto com suas probabilidades logarítmicas.
Use-o quando quiser inspecionar alternativas de tokens, em vez de apenas o token escolhido para a saída.
tools
Declara ferramentas ou funções chamáveis para fluxos de trabalho com modelos que usam ferramentas.
A menos que a documentação do endpoint indique o contrário, use o esquema de ferramentas no estilo OpenAI. As declarações descrevem o que o modelo pode chamar, não se ele deve chamar uma ferramenta.
tool_choice
Controla se o modelo pode chamar ferramentas automaticamente, não deve chamá-las ou precisa usar uma ferramenta específica.
Use
none quando quiser somente conteúdo, auto quando o modelo puder decidir e valores mais restritivos quando a orquestração downstream exigir uma chamada de ferramenta.
parallel_tool_calls
Permite ou impede chamadas simultâneas de ferramentas em APIs compatíveis.
Desative quando sistemas downstream exigirem execução estritamente sequencial, efeitos colaterais ordenados ou rastros de agente mais simples.
response_format
Solicita um formato de saída específico, como texto simples, JSON ou respostas limitadas por esquema.
Os formatos aceitos dependem do endpoint e do adaptador do provedor. Use-o quando precisar de mais do que texto livre, especialmente para respostas JSON e fluxos de extração estruturada.
structured_outputs
Sinaliza suporte a respostas estruturadas confiáveis ou limitadas por esquema na rota e no conjunto de provedores selecionados.
Nas tabelas de início rápido, isso indica se o endpoint selecionado e os provedores ativos oferecem suporte confiável a fluxos de saída estruturada. Interprete-o como metadado de suporte.
json_schema
Fornece o esquema JSON usado para exigir saída estruturada em modelos e endpoints compatíveis.
Use-o quando a aplicação precisar de campos garantidos, extração tipada ou um contrato de resposta estrito. Mantenha os esquemas restritos e específicos da tarefa para melhorar a aderência.
reasoning
Contém configurações de raciocínio específicas do provedor para APIs compatíveis com raciocínio.
Conforme a rota, pode incluir ativação, esforço, orçamento de tokens, nível de detalhe ou se o conteúdo do raciocínio será retornado.
reasoning_effort
Solicita um orçamento de raciocínio menor ou maior quando o endpoint e o modelo oferecem esse controle.
Um nível maior pode melhorar tarefas de raciocínio difíceis, mas aumenta a latência e o uso de tokens. Um nível menor costuma ser mais adequado para solicitações rápidas e baratas.
reasoning_tokens
Representa um campo de tokens específico de raciocínio quando houver suporte.
Conforme a rota, pode ser um ajuste da solicitação, um limite ou um campo de contabilização da resposta, e não um parâmetro aceito universalmente.
include_reasoning
Solicita conteúdo ou resumos do raciocínio nas respostas quando houver suporte.
Use com cuidado. Payloads de raciocínio podem ser maiores, não estar disponíveis em todos os modelos e ser inadequados para respostas de produção que não precisam de detalhes de diagnóstico extras.
service_tier
Seleciona um nível de roteamento ou preço aceito em APIs de texto compatíveis.
Use
ultrafast, fast (ou priority onde houver suporte) e flex somente se a combinação de modelo e provedor os aceitar. Ultrafast seleciona o nível compatível mais rápido; fast e priority usam o mesmo roteamento e preço Fast. Omita o campo para manter o nível padrão.
O Phaseo mapeia internamente esses níveis normalizados do gateway para controles nativos dos provedores, permitindo que os clientes usem os mesmos valores de service_tier nas interfaces de texto compatíveis.
Observações:
Batch é um fluxo de API separado, não um valor de nível de serviço.
O suporte varia conforme o endpoint e o provedor.
prompt_cache_key
Fornece uma chave estável de afinidade de cache para roteamento que considera o cache de prompts.
Use quando uma série de solicitações compartilhar prefixos de prompt estáveis e precisar priorizar o mesmo provedor ou região upstream. O Phaseo também pode derivar a afinidade de cache do contexto da solicitação, mas uma chave explícita é melhor para conversas longas, sessões de agente e fluxos repetidos.
prompt_cache_options
Transmite os controles de cache de prompts da OpenAI pelas rotas OpenAI compatíveis.
Para GPT-6 Astra, use
{"mode":"explicit","ttl":"30m"} para cache explícito de prompts. O Phaseo preserva o objeto durante a normalização da solicitação e o envia à OpenAI sem alterações.
cache_control
Aplica uma política de cache de prompts independente do provedor nas interfaces de solicitação de texto compatíveis.
Use
cache_control no nível superior de solicitações Chat Completions, Responses e Anthropic Messages para que a mesma dica de cache percorra o esquema comum do gateway. Também é possível colocá-lo em blocos de conteúdo compatíveis para definir pontos de separação explícitos.
Os valores comuns de TTL são 5m e 1h, conforme o suporte do provedor e do modelo. Aliases específicos de provedores, como provider_options.anthropic.cache_control e provider_options.google.cache_control, continuam aceitos em integrações nativas.
prompt_cache_retention
Define a política de retenção do cache de prompts compatível com OpenAI em solicitações compatíveis roteadas para a OpenAI.
Use para enviar opções de retenção de cache da OpenAI sem aninhá-las nas opções específicas do provedor. O alias
provider_options.openai.prompt_cache_retention continua aceito. Se ambos estiverem presentes, o valor de nível superior prompt_cache_retention terá precedência.
provider
Contém restrições de roteamento e preferências de provedores.
Use-o para definir quais provedores upstream podem executar a solicitação, como devem ser classificados e quais requisitos de conformidade precisam atender.
Campos comuns incluem:
quantizations segue o vocabulário de roteamento de provedores compatível com OpenRouter e é aceito tanto em provider quanto em routing. A correspondência não diferencia maiúsculas de minúsculas e ignora espaços, hífens e sublinhados; nomes inequívocos como float8/FP8 e bfloat16/BF16 são aliases. Ofertas sem metadados de quantização são excluídas quando esse filtro está presente. Se nenhuma oferta elegível corresponder, o Gateway retorna um erro com as quantizações solicitadas e disponíveis, em vez de encaminhar silenciosamente para outra variante.
provider_options
Contém configurações de passthrough específicas do provedor que não devem ser normalizadas na estrutura de solicitação comum do gateway.
Exemplos:
openai.context_managementopenai.prompt_cache_retentionanthropic.cache_controlgoogle.cache_controlgoogle.cached_content
cache_control no nível superior para dicas comuns de cache e prompt_cache_retention no nível superior para retenção compatível com OpenAI.
Para ver exemplos de cache de prompts por provedor em Chat Completions, Responses e Anthropic Messages, consulte Cache de prompts.
meta
Solicita metadados extras na resposta quando houver suporte.
Use-o quando quiser metadados extras não essenciais na resposta para depuração, análise ou inspeção downstream.
usage
Solicita detalhes de contabilização do uso quando houver suporte.
É útil quando você quer contabilização explícita de tokens ou uso no corpo da resposta, em vez de depender apenas de cabeçalhos ou painéis.
debug
Ativa diagnósticos controlados de solicitação e roteamento.
Os campos de depuração aceitos incluem:
Payloads de depuração podem conter contexto sensível da solicitação. Use-os somente em desenvolvimento ou em ambientes rigorosamente controlados.
Exemplo de solicitação
Explicações detalhadas
Se quiser orientações mais aprofundadas sobre como ajustar os parâmetros, em vez de uma referência simples dos campos, consulte estas páginas:- Parâmetros de inferência para orientações práticas sobre temperature, top_p, top_k, limites de tokens, sequências de parada e fluxo de ajuste
- Amostragem e decodificação para entender como aleatoriedade, penalidades e controles de decodificação mudam o comportamento do modelo