Pular para o conteúdo principal
Use o recurso Responses quando quiser que a API MKA1 retorne texto. Comece com uma string simples para prompts simples. Use itens de mensagem quando precisar de funções explícitas ou estado da conversa. As seções seguintes tratam dos limites de amostragem e comprimento, do esforço de raciocínio e dos campos da solicitação que o gateway descarta. Pausar uma resposta em segundo plano tem uma seção própria em respostas em segundo plano.

Enviar um prompt simples

Passe uma string em input para uma solicitação de uma única interação. A resposta inclui o texto gerado em output_text. Se um guardrail bloquear a solicitação, output_text fica ausente e a saída traz uma recusa; consulte Guardrails.
Se você não estiver agindo em nome de um usuário final, omita X-On-Behalf-Of.

Adicionar instruções

Use instructions para definir o comportamento antes de o modelo ver a entrada do usuário. Mantenha as instruções curtas e específicas.

Enviar mensagens estruturadas

Use uma matriz de itens de mensagem em input quando quiser funções explícitas. Cada item de mensagem usa type, role e content.
Esse padrão é útil quando você quer que o corpo da solicitação transporte diretamente o histórico de mensagens.

Continuar uma troca de várias interações

Use previous_response_id para continuar a partir de uma resposta anterior sem reenviar todo o histórico.
Se precisar de um contêiner de conversa reutilizável, crie um com o recurso Conversations e passe o ID da conversa em conversation.
Observação: excluir uma conversa não exclui os itens dela. Consulte as páginas Conversations e Responses na Referência da API para conhecer o fluxo de trabalho completo do recurso.

Transmitir texto à medida que é gerado

Defina stream como true para receber eventos enviados pelo servidor em vez de esperar pela resposta completa.
Use streaming quando quiser renderizar a saída parcial à medida que ela chega.

Ajustar amostragem e comprimento

Os campos de amostragem mudam como o modelo escolhe cada token. Os campos de comprimento limitam quanto ele escreve. Todos são opcionais e ficam no nível superior da solicitação, ao lado de model e input.
O gateway valida cada valor antes de chamar o modelo. Um valor fora do intervalo retorna 400. No exemplo, verifique status: se o modelo atingiu o limite de 400 tokens, a resposta fica incomplete em vez de completed, e usage.output_tokens fica no limite ou abaixo dele. Alguns campos da tabela são extensões do gateway. Eles não fazem parte da API Responses da OpenAI, e chegar ou não ao modelo depende do upstream dele, a API do provedor para a qual o gateway encaminha sua solicitação, que usa o formato Responses ou o formato Completions. Os campos marcados como extensões do gateway não fazem parte da API Responses da OpenAI, então os tipos do SDK da OpenAI não os conhecem. Envie-os com o SDK da MKA1, a CLI ou HTTP direto. Outras quatro extensões do gateway repassam opções do provedor sem alterações: chat_template_kwargs (por exemplo {"enable_thinking": false}), prefill_think (um booleano ou um texto de preenchimento), use_cache e extra_body, um objeto mesclado à solicitação upstream depois que o gateway remove dele quaisquer chaves de autenticação, de URL base e de cabeçalhos. Nem todo campo chega a todo modelo. Campos que o gateway descarta lista os casos.

Verificar o que um modelo suporta

Nem todo modelo aceita todos os campos. GET /api/v1/llm/models/{model_id} retorna um objeto capabilities com quatro booleanos: Modelos que não são LLMs (embeddings, imagens, fala) informam false nos quatro. O objeto do modelo também lista input_modalities e output_modalities, os tipos de conteúdo que o modelo aceita e produz, como ["text", "image"].
Se você enviar um campo a um modelo que informa false para ele, o gateway não rejeita a solicitação. Ele descarta esse campo antes de chamar o modelo, encaminha todo o resto, e o modelo usa o próprio padrão para essa configuração. Nada na resposta indica que o campo foi descartado: ela devolve temperature, top_p e reasoning exatamente como você os enviou. Verifique primeiro as capacidades do modelo quando a configuração for importante.

Controlar o raciocínio

Modelos de raciocínio pensam antes de responder. O objeto reasoning define quanto raciocínio você quer e se você o vê:
  • effort: none, minimal, low, medium, high ou xhigh.
  • summary: auto, concise ou detailed. Pede ao modelo que retorne um resumo legível do raciocínio.
As duas chaves devem estar presentes sempre que você enviar o objeto. Defina como null a que você não usar. {"effort": "low"} sozinho falha na validação. Cada chave só chega ao modelo quando ele pode usá-la:
  • effort vai apenas para modelos que informam supports_reasoning_effort: true. Um upstream no formato Completions o recebe como reasoning_effort.
  • summary vai apenas para modelos que informam supports_reasoning: true e cujo upstream usa o formato Responses.
O gateway descarta uma chave que o modelo não pode usar, e a solicitação é concluída mesmo assim.
O tipo ReasoningEffort do SDK da OpenAI não inclui none nem xhigh; envie esses valores com o SDK da MKA1, a CLI ou HTTP direto. O raciocínio aparece em três lugares:
  • output pode conter um item com type: "reasoning". O array summary dele contém partes summary_text, e content (quando presente) contém as partes reasoning_text brutas. Adicione "reasoning.encrypted_content" a include para receber também encrypted_content.
  • usage.output_tokens_details.reasoning_tokens é a parte de output_tokens que o modelo gastou raciocinando. Tokens de raciocínio são tokens de saída, então contam para max_output_tokens.
  • Em um stream, os eventos response.reasoning_text.delta e response.reasoning_summary_text.delta costumam chegar antes dos eventos response.output_text.delta. O benchmark de latência de saída em streaming mostra essa ordem em um modelo real.
Para saber antes da chamada se um modelo raciocina e se aceita effort, leia supports_reasoning e supports_reasoning_effort como mostrado em Verificar o que um modelo suporta. Depois da chamada, usage.output_tokens_details.reasoning_tokens mostra quanto raciocínio houve. Quando você envia model: "auto", o gateway aplica a política auto da organização para Responses. O padrão é um alias direto do registro de modelos. Um administrador da organização pode configurar uma política equilibrada que pede a um LLM juiz para escolher entre os modelos elegíveis com base em capacidade, preço, latência do gateway, avaliações comparáveis, requisitos da solicitação e continuidade da conversa. O roteamento não altera o reasoning.effort que você envia, mas o gateway ainda o descarta quando o modelo escolhido informa supports_reasoning_effort: false. Roteamento automático explica a política e seu comportamento em falhas e em privacidade.

Campos que o gateway descarta

Cada campo abaixo passa na validação, mas o gateway o descarta antes de chamar o modelo no caso indicado. Um campo descartado nunca faz a solicitação falhar, e nada na resposta indica que ele foi descartado. Alguns casos dependem do upstream do modelo, a API do provedor para a qual o gateway encaminha sua solicitação. Como campos desconhecidos são removidos em silêncio, um nome de campo digitado errado parece aceito, mas não tem efeito. Se uma configuração parecer não fazer nada, compare sua solicitação com a referência da API.

Pausar uma resposta em segundo plano

Uma resposta em segundo plano pode chamar a ferramenta sleep para esperar até 20 minutos por um webhook ou por um trabalho externo, e você pode acordá-la antes com uma entrada de acompanhamento. Consulte respostas em segundo plano.

Próximas etapas