A API Decisions já está em disponibilidade geral. Confira as novidades desde a versão beta pública.
A API Decisions avalia textos, imagens e dados JSON e retorna respostas tipadas cerca de 10 vezes mais rápido que a API Responses. Obtenha a probabilidade de uma condição ser verdadeira, uma opção de um conjunto predefinido ou uma pontuação com base em critérios de avaliação. Use essas respostas para classificar conteúdo, encaminhar solicitações e priorizar tarefas no seu aplicativo.
Experimente a API Decisions no Playground para testar perguntas e entradas antes de escrever código.
Envie requisições para POST /v1/decisions usando gpt-6-luna, o único modelo compatível no momento.
Novidades
Desde o lançamento da versão beta pública, a API Decisions passou a oferecer os seguintes recursos:
- Cache de prompts. Reutilize a entrada compartilhada entre requisições e obtenha descontos pelo uso do cache.
- Imagens nas instruções das perguntas. Forneça imagens específicas para cada pergunta e compare-as com as evidências compartilhadas.
- Entrada JSON. Envie dados estruturados diretamente em uma parte de conteúdo do tipo
input_json. - Mais perguntas por requisição. Faça até 400 perguntas por requisição. Na versão beta pública, o limite era de 200.
- Imagens hospedadas como entrada. Envie URLs HTTP ou HTTPS de imagens acessíveis publicamente, além de URLs de dados com imagens incorporadas em base64.
- Histórico de conversa. Avalie mensagens junto com chamadas de função, chamadas de ferramentas personalizadas e suas respectivas saídas.
- Relatórios de uso da organização. Acompanhe o uso de tokens e o número de requisições.
- Integração nativa com o GPT-Live. Permita que o Live chame a API Decisions diretamente ou acione decisões à medida que seu aplicativo recebe as transcrições de entrada ou saída.
- Private Link. Envie requisições à API Decisions por uma conexão privada.
Como as decisões funcionam
Uma requisição tem três partes:
| Campo | Finalidade |
|---|---|
model |
O modelo que avalia a requisição. No momento, apenas gpt-6-luna é compatível. |
input |
Evidências compartilhadas entre as perguntas: uma string de texto ou um array ordenado de mensagens, chamadas de ferramentas e saídas de ferramentas. |
questions |
O que avaliar, incluindo o tipo e as instruções de cada pergunta e as opções ou os níveis de pontuação permitidos. |
A resposta contém um array answers. Atribua a cada pergunta um name exclusivo para identificar sua resposta. A API retorna esse nome na resposta.
Escolha o tipo de pergunta
| Tipo | Finalidade | Resultado principal |
|---|---|---|
predicate |
Verificar uma condição, como a presença de danos visíveis ou a relevância de um trecho. | probability: probabilidade estimada, de 0 a 1, de a condição ser verdadeira. |
choice |
Selecionar uma opção, como um departamento ou uma categoria de conteúdo. | choice: um dos valores fornecidos. |
score |
Avaliar uma entrada segundo níveis ordenados, como os de gravidade de um problema. | score: média dos índices dos níveis ponderada pelas probabilidades. |
Tanto choice quanto score retornam probabilidades para opções discretas. Use choice para categorias sem ordem definida, como departamentos. Use score para níveis ordenados, como os de gravidade. A média dos índices numéricos dos níveis, ponderada pelas probabilidades, produz uma pontuação que pode ficar entre dois níveis.
Use a API Decisions quando seu aplicativo precisar de um desses tipos de resposta. Use saídas estruturadas com a API Responses quando precisar gerar um objeto que siga seu próprio schema JSON, por exemplo, com campos extraídos ou uma explicação por escrito. Use a chamada de função quando precisar que um modelo solicite uma chamada de ferramenta com argumentos.
Avalie uma conversa
Envie o histórico da conversa em input para avaliar uma solicitação em seu contexto. Inclua, na ordem em que ocorreram, as mensagens e quaisquer chamadas de função ou de ferramentas personalizadas, com suas respectivas saídas. Use call_id para associar cada saída à chamada correspondente.
O conteúdo aceito depende do papel da mensagem ou do tipo de item:
| Item de entrada | Conteúdo aceito |
|---|---|
| Mensagem do usuário | Texto, imagens e JSON |
| Mensagem do desenvolvedor ou do sistema | Apenas texto de entrada. A API trata as mensagens do sistema como mensagens do desenvolvedor. |
| Mensagem do assistente | Texto de saída ou recusas |
| Saída de função ou de ferramenta personalizada | Texto e imagens associados à chamada de ferramenta correspondente |
As chamadas de ferramentas e suas saídas fornecem evidências para as perguntas. A API Decisions retorna respostas tipadas, e seu aplicativo executa as ações selecionadas com base nessas respostas. A API não aceita arquivos, áudio ou referências a itens. Consulte a referência de criação de decisões para conhecer os campos de entrada aceitos.
Avalie dados JSON
Use uma parte de conteúdo do tipo input_json para enviar evidências estruturadas sem precisar convertê-las em uma string. Em uma mensagem do usuário, coloque o objeto ou array JSON em data. Se houver partes de texto ou imagem, inclua-as ao lado da parte JSON. No conteúdo das mensagens, a API aceita input_json apenas para o papel user.
Por exemplo, envie este corpo de requisição JSON para POST /v1/decisions para avaliar um chamado de suporte com base no registro de um pedido:
{
"model": "gpt-6-luna",
"input": [
{
"role": "user",
"content": [
{
"type": "input_text",
"text": "Evaluate the ticket using the order evidence."
},
{
"type": "input_json",
"data": {
"ticket": { "body": "Please refund the duplicate charge." },
"order": { "charges": [49, 49] }
}
}
]
}
],
"questions": [
{
"type": "predicate",
"name": "duplicate_charge",
"instructions": "Does the ticket describe a duplicate charge supported by the order?"
}
]
}
Chaves JSON como role ou image_url dentro de data são dados comuns. Elas não criam mensagens nem fazem com que a API busque imagens. A resposta continua seguindo o tipo de pergunta selecionado. A entrada JSON não altera o formato da resposta.
Verifique se há danos visíveis em uma imagem
Use uma pergunta do tipo predicate para verificar se há danos visíveis na foto de um produto. Esta requisição combina a imagem com instruções para procurar rachaduras, rasgos ou amassados.
IMAGE_BASE64="$(base64 < product.png | tr -d '\r\n')"
curl https://api.openai.com/v1/decisions \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "Content-Type: application/json" \
--data-binary @- <<JSON
{
"model": "gpt-6-luna",
"input": [{
"role": "user",
"content": [
{"type": "input_text", "text": "Inspect the product in this photo."},
{"type": "input_image", "image_url": "data:image/png;base64,$IMAGE_BASE64"}
]
}],
"questions": [{
"type": "predicate",
"name": "visible_damage",
"instructions": "Does the product have visible damage, such as a crack, tear, or dent? Ignore shadows and damage to the packaging."
}]
}
JSONExemplo de trecho da resposta:
{
"answers": [
{
"type": "predicate",
"name": "visible_damage",
"probability": 0.92
}
]
}
O campo probability indica a probabilidade estimada pelo modelo de que a condição seja verdadeira. Use um limite de sua escolha para sinalizar fotos que precisam de revisão.
Forneça as imagens como URLs de dados com conteúdo incorporado em base64 ou como URLs HTTP ou HTTPS acessíveis publicamente. Esse endpoint não aceita entradas do tipo file_id. Combine partes input_text e input_image em uma mensagem do usuário para avaliar as imagens junto com as instruções ou outras informações de contexto.
Inclua imagens nas instruções das perguntas
Coloque em input as evidências comuns a todas as perguntas. Para fornecer uma imagem diferente a cada pergunta, defina instructions como um array não vazio de partes input_text e input_image. Isso funciona para perguntas de predicado, escolha e pontuação. Instruções que contêm apenas texto podem continuar sendo uma string.
Por exemplo, envie este corpo de requisição JSON para POST /v1/decisions para comparar uma imagem candidata com uma referência compartilhada. Substitua as duas URLs de exemplo por URLs de imagens acessíveis publicamente ou use URLs de dados com imagens em base64:
{
"model": "gpt-6-luna",
"input": [
{
"role": "user",
"content": [
{
"type": "input_text",
"text": "The shared image is reference image A."
},
{
"type": "input_image",
"image_url": "https://example.com/reference.jpg"
}
]
}
],
"questions": [
{
"type": "predicate",
"name": "candidate_matches_reference",
"instructions": [
{
"type": "input_text",
"text": "Is candidate image B a derivative or variant of reference image A, including recompression or resizing?"
},
{
"type": "input_image",
"image_url": "https://example.com/candidate.jpg"
}
]
}
]
}
Ao incluir imagens nas instruções das perguntas:
- Adicione uma pergunta para cada imagem candidata. Cada pergunta compara sua própria imagem candidata com a mesma referência compartilhada.
- Forneça as partes de conteúdo diretamente em
instructions, sem envolvê-las em um objeto de mensagem nem incluirrole. - Os limites de imagens por requisição se aplicam ao conjunto de imagens das perguntas e de
input.
Escolha entre opções predefinidas
Uma pergunta do tipo choice seleciona um valor entre as opções fornecidas. Use valores distintos e descrições que expliquem quando cada opção se aplica.
Esta requisição encaminha a reclamação de um cliente para o departamento responsável:
curl https://api.openai.com/v1/decisions \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-6-luna",
"input": "I was charged twice for my order.",
"questions": [{
"type": "choice",
"name": "department",
"instructions": "Which department should handle this complaint?",
"choices": [
{"value": "billing", "description": "Payments, invoices, and refunds."},
{"value": "technical", "description": "Problems using the product."},
{"value": "shipping", "description": "Delivery and tracking."},
{"value": "other", "description": "Requests outside these categories."}
]
}]
}'Exemplo de trecho da resposta:
{
"answers": [
{
"type": "choice",
"name": "department",
"choice": "billing",
"probabilities": [
{ "value": "billing", "probability": 0.95 },
{ "value": "technical", "probability": 0.02 },
{ "value": "shipping", "probability": 0.01 },
{ "value": "other", "probability": 0.02 }
],
"confidence": 0.93
}
]
}
O campo choice da resposta contém um dos valores fornecidos, neste caso "billing". A resposta também inclui um array probabilities com as probabilidades das opções e um campo confidence. Consulte Interprete as respostas para saber como definir limites.
Inclua uma opção como "other" para os casos em que nenhuma categoria se aplica à entrada. Seu aplicativo pode encaminhar esse resultado para uma fila de revisão geral.
Atribua uma pontuação com base em critérios de avaliação
Uma pergunta do tipo score avalia uma entrada em uma escala de 2 a 10 níveis ordenados (levels). Defina os critérios de cada nível e organize os níveis do mais baixo ao mais alto.
curl https://api.openai.com/v1/decisions \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-6-luna",
"input": "Export fails in Safari but works in Chrome.",
"questions": [{
"type": "score",
"name": "severity",
"instructions": "How severe is this issue?",
"levels": [
{"label": "Cosmetic", "description": "Appearance only; no lost functionality."},
{"label": "Workaround available", "description": "A task fails, but another way works."},
{"label": "Fully blocked", "description": "A task fails with no workaround."}
]
}]
}'Exemplo de trecho da resposta:
{
"answers": [
{
"type": "score",
"name": "severity",
"score": 1.1,
"probabilities": [
{ "value": 0, "label": "Cosmetic", "probability": 0.1 },
{ "value": 1, "label": "Workaround available", "probability": 0.7 },
{ "value": 2, "label": "Fully blocked", "probability": 0.2 }
],
"confidence": 0.55
}
]
}
Os índices dos níveis começam em 0. Aqui, 0 indica um problema apenas visual, 1 indica que há uma solução de contorno e 2 indica um bloqueio total. O valor de score retornado é uma média ponderada pelas probabilidades e pode ficar entre dois níveis. Neste exemplo, as probabilidades de 0,1, 0,7 e 0,2 resultam em uma pontuação de 1,1.
A resposta também inclui confidence e as probabilidades de cada nível em probabilities. A pontuação resume a distribuição entre os níveis. Use choice para selecionar uma única categoria.
Faça várias perguntas
Inclua de 1 a 400 perguntas em uma requisição. Coloque perguntas independentes no mesmo array questions para avaliar a entrada compartilhada. Com uma foto de produto, uma única requisição pode verificar se há danos e identificar a categoria do produto. Cada pergunta pode ter um tipo diferente.
Para decisões que dependam de uma resposta anterior, envie requisições separadas. Por exemplo, primeiro verifique se há danos. Em seguida, use o resultado para decidir se é necessário perguntar qual é a categoria de reparo.
Formule perguntas com base em critérios observáveis. Trate cada aspecto em uma pergunta separada, dê a cada opção um significado distinto e defina critérios que diferenciem níveis de pontuação adjacentes.
Interprete as respostas
Os predicados retornam a probabilidade estimada de uma condição ser verdadeira. As respostas de escolha e de pontuação retornam uma distribuição de probabilidades e um campo confidence separado.
Use exemplos rotulados do seu aplicativo para definir limites de encaminhamento, filtragem ou revisão. Escolha esses limites com base no custo dos falsos positivos e dos falsos negativos.
Reutilize a entrada compartilhada com o cache de prompts
Com o cache de prompts, requisições repetidas podem reutilizar um prefixo idêntico da entrada compartilhada em input e obter desconto pela leitura do cache. Por exemplo, mantenha um documento ou uma imagem de referência em input e altere as perguntas a cada requisição. O conteúdo de questions, incluindo as imagens específicas de cada pergunta, fica fora do prefixo reutilizável.
Por padrão, a API Decisions define implicitamente um ponto de corte do cache no fim da entrada compartilhada em input. As requisições existentes podem usar o cache sem alterações no corpo da requisição. O prefixo reutilizável precisa conter pelo menos 1.024 tokens. O conteúdo das perguntas não conta para esse mínimo. Mantenha o prefixo idêntico entre requisições para permitir sua reutilização.
Use prompt_cache_key para separar a reutilização do cache por uma chave fornecida por quem faz a requisição. Para controlar o ponto de corte, adicione prompt_cache_breakpoint: {"mode": "explicit"} às partes de texto ou imagem da entrada compartilhada em input. Defina prompt_cache_options.mode como "explicit" para usar apenas os pontos de corte marcados. No modo explícito, uma requisição sem pontos de corte marcados não usa o cache de prompts. As instruções das perguntas não aceitam pontos de corte.
Consulte usage.input_tokens_details.cached_tokens para ver a contagem de tokens lidos do cache e usage.input_tokens_details.cache_write_tokens para ver a de tokens gravados no cache. As duas contagens já estão incluídas em usage.input_tokens. Não as some a esse total. Consulte o guia de cache de prompts para entender os conceitos de cache e a referência da API Decisions para conhecer os controles disponíveis nas requisições.
Monitore o uso
Use GET /v1/organization/usage/decisions para consultar o uso de tokens e o número de requisições da sua organização na API Decisions. Para autenticação, use uma chave de API de administrador com a permissão api.usage.read.
Escolha o período e a duração de cada intervalo de agregação. Em seguida, filtre ou agrupe os resultados por projeto, chave de API ou modelo. O campo num_model_requests conta requisições. Uma requisição com várias perguntas conta apenas uma vez. Consulte a referência de uso da API Decisions para saber mais sobre filtros e paginação.
Preços e disponibilidade
Com gpt-6-luna, a entrada sem cache custa US$ 0,10 por milhão de tokens. Quando há uma correspondência no cache de prompts, o preço da entrada tem desconto. As gravações no cache são cobradas. As tarifas de leitura e gravação no cache seguem as tarifas padrão do cache de prompts do gpt-6-luna. Não há cobrança pelos tokens de saída.
Aplicam-se os acréscimos por processamento regional e os multiplicadores de preço de entrada para contextos longos. Essas tarifas valem para /v1/decisions. Outras requisições com gpt-6-luna seguem os preços aplicáveis ao modelo e ao nível de processamento.
A API Decisions oferece zero retenção de dados (ZDR) e permite o uso em conformidade com a HIPAA para clientes elegíveis. A residência de dados está disponível em todas as regiões atendidas pela API. O processamento regional está disponível nos Estados Unidos e na Europa (Espaço Econômico Europeu e Suíça). Consulte os controles de dados para conhecer os critérios de elegibilidade, os acordos necessários e as limitações.
Adicione controle por voz
Integre a voz à API Decisions para escolher uma ação com base em uma solicitação por voz ou reagir enquanto o usuário ou o GPT-Live fala.




