View a markdown version of this page

API de respostas no endpoint básico - Amazon Bedrock
Regiões e endpoints compatíveisPré-requisitosAPI de modelosAPI de respostas

As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

API de respostas no endpoint básico

O Amazon Bedrock fornece a API de OpenAI respostas nos bedrock-mantle endpoints bedrock-runtime e endpoints. A API permite que você use OpenAI SDKs e ferramentas familiares com os modelos do Amazon Bedrock, para que você possa migrar aplicativos existentes com o mínimo de alterações de código. Basta atualizar sua URL base e sua chave de API. Para novos aplicativos, recomendamos o bedrock-runtime endpoint.

Os dois endpoints não têm suporte a recursos idênticos. As solicitações bedrock-runtime ativadas são sempre síncronas, as ferramentas do lado do servidor não estão disponíveis e somente o projeto padrão é suportado. Para ver a comparação completaEndpoints compatíveis com o Amazon Bedrock, consulte e para obter os detalhes de cada diferença, consulteUsando a API Responses no endpoint básico de tempo de execução.

Importante

Ao usar o OpenAI SDK com o Amazon Bedrock, você deve apontá-lo para o endpoint Amazon Bedrock, não para o endpoint. OpenAI Defina as seguintes variáveis de ambiente, escolhendo a URL base para o endpoint que você deseja:

# bedrock-runtime (recommended)
OPENAI_BASE_URL="https://bedrock-runtime.<your-region>.amazonaws.com/openai/v1"

# bedrock-mantle
OPENAI_BASE_URL="https://bedrock-mantle.<your-region>.api.aws/v1"

OPENAI_API_KEY="<your Bedrock API key>"

Não use sua chave de OpenAI API ou o URL OpenAI base (https://api.openai.com/v1). Esses se conectam OpenAI diretamente, não ao Amazon Bedrock. Para criar uma chave de API do Amazon Bedrock, consulteChaves de API.

Os benefícios importantes incluem:

  • Inferência assíncrona — Suporte para cargas de trabalho de inferência de longa duração por meio da API Responses. Disponível bedrock-mantle somente em.

  • Gerenciamento contínuo de conversas — reconstrua automaticamente o contexto sem passar manualmente o histórico da conversa com cada solicitação

  • Uso simplificado de ferramentas — Integração simplificada para fluxos de trabalho agentes

  • Modos de resposta flexíveis — Suporte para respostas em streaming e sem streaming

  • Fácil migração — Compatível com as bases de código OpenAI SDK existentes

Cada endpoint é governado por seu próprio conjunto de cotas. Para o tráfego de respostas ativadobedrock-runtime, as cotas de tokens por minuto e tokens por dia do modelo se aplicam, e elas são compartilhadas com as outras APIs de inferência nesse endpoint — consulte. Cotas para o endpoint básico de tempo de execução Em bedrock-mantle, consulte Cotas para o endpoint rocho-mantle.

Regiões e endpoints compatíveis

No bedrock-runtime endpoint, a API Responses está disponível em todos os Região da AWS lugares em que esse endpoint está disponível, incluindo as regiões AWS GovCloud (EUA). Para ver a lista, consulte Disponibilidade regional por endpoints. Os modelos compatíveis com a API em cada endpoint estão listados emDisponibilidade de endpoints por modelos.

O bedrock-mantle endpoint está disponível nas seguintes AWS regiões:

Nome da região Região Endpoint
Leste dos EUA (Ohio) us-east-2 bedrock-mantle.us-east-2.api.aws
Leste dos EUA (Norte da Virgínia) us-east-1 bedrock-mantle.us-east-1.api.aws
Oeste dos EUA (Oregon) us-west-2 bedrock-mantle.us-west-2.api.aws
Ásia-Pacífico (Jacarta) ap-southeast-3 bedrock-mantle.ap-southeast-3.api.aws
Ásia-Pacífico (Mumbai) ap-south-1 bedrock-mantle.ap-south-1.api.aws
Ásia-Pacífico (Sydney) ap-southeast-2 bedrock-mantle.ap-southeast-2.api.aws
Ásia-Pacífico (Tóquio) ap-northeast-1 bedrock-mantle.ap-northeast-1.api.aws
Europa (Frankfurt) eu-central-1 bedrock-mantle.eu-central-1.api.aws
Europa (Irlanda) eu-west-1 bedrock-mantle.eu-west-1.api.aws
Europa (Londres) eu-west-2 bedrock-mantle.eu-west-2.api.aws
Europa (Milão) eu-south-1 bedrock-mantle.eu-south-1.api.aws
Europa (Estocolmo) eu-north-1 bedrock-mantle.eu-north-1.api.aws
América do Sul (São Paulo) sa-east-1 bedrock-mantle.sa-east-1.api.aws
AWS GovCloud (US-West) us-gov-west-1 bedrock-mantle.us-gov-west-1.api.aws

Pré-requisitos

Antes de usar as OpenAI APIs, verifique se você tem o seguinte:

  • Autenticação — Você pode autenticar usando:

    • Chave de API Amazon Bedrock (necessária para o OpenAI SDK)

    • AWS credenciais (compatíveis com solicitações HTTP)

  • OpenAISDK (opcional) — Instale o SDK do OpenAI Python se estiver usando solicitações. SDK-based

  • Variáveis de ambiente — Defina as seguintes variáveis de ambiente:

    • OPENAI_API_KEY— Defina sua chave de API Amazon Bedrock

    • OPENAI_BASE_URL— Defina como o endpoint Amazon Bedrock da sua região (por exemplo, https://bedrock-runtime.us-east-1.amazonaws.com/openai/v1 ou) https://bedrock-mantle.us-east-1.api.aws/v1

  • Permissões — As ações de que você precisa dependem do endpoint. Ativadobedrock-mantle, a inferência autorizabedrock-mantle:CreateInference. Ativadobedrock-runtime, ele autoriza tanto bedrock:InvokeModel no alvo de inferência quanto no projeto padrão da sua conta, e o gerenciamento das respostas armazenadas autoriza bedrock:GetInvokebedrock:CancelInvoke, e bedrock:DeleteInvoke nesse projeto. Para obter exemplos de políticas, consulte Pré-requisitos para executar a inferência do modelo.

API de modelos

A API de modelos permite que você descubra os modelos disponíveis no Amazon Bedrock com tecnologia Mantle. Use essa API para recuperar uma lista de modelos que você pode usar com a API de respostas. Para obter detalhes completos da API, consulte a documentação de OpenAI modelos.

Listar modelos disponíveis

Para listar os modelos disponíveis, escolha a guia do seu método preferido e siga as etapas:

OpenAI SDK (Python)
# List all available models using the OpenAI SDK
# Requires OPENAI_API_KEY and OPENAI_BASE_URL environment variables

from openai import OpenAI

client = OpenAI()

models = client.models.list()

for model in models.data:
    print(model.id)
HTTP request

Faça uma solicitação GET para/v1/models:

# List all available models
# Requires OPENAI_API_KEY and OPENAI_BASE_URL environment variables

curl -X GET $OPENAI_BASE_URL/models \
   -H "Authorization: Bearer $OPENAI_API_KEY"

API de respostas

A API de respostas fornece gerenciamento de conversas com status, com suporte para streaming, processamento em segundo plano e interações em vários turnos. Para obter detalhes completos da API, consulte a documentação de OpenAI respostas.

nota

Nem todos os modelos oferecem suporte à API de respostas. Para ver quais modelos são compatíveis com a API Responses, consulteCompatibilidade de API por modelos.

Como a API de respostas armazena o estado da conversa

A API de respostas pode usar o estado armazenado para permitir conversas em vários turnos e permitir que você faça referência a turnos anteriores por meio do previous_response_id parâmetro. O armazenamento é ativado por padrão, mas pode ser desativado por solicitação por meio do store parâmetro. As respostas armazenadas têm o escopo definido pelo Project. Uma resposta de um projeto não pode ser usada como resposta anterior ou lida em um segundo projeto. Para obter mais informações sobre projetos, consulteProjetos (OpenAI-compatible).

  • Quando store é true (o padrão), o Amazon Bedrock retém a resposta, incluindo a entrada e a saída, por 30 dias. Durante essa janela, você pode encadear solicitações de acompanhamento transmitindo previous_response_id e recuperando a resposta GET /v1/responses/{id} ativando ou bedrock-mantle GET /openai/v1/responses/{id} ativandobedrock-runtime. Após 30 dias, a resposta é excluída automaticamente e não pode mais ser recuperada.

  • Quando store éfalse, o Amazon Bedrock não retém nenhum dado da solicitação ou resposta. O previous_response_id parâmetro não pode ser usado para continuar a conversa.

O valor padrão é corresponder true à especificação da API de OpenAI respostas. Clientes que não desejam que o Amazon Bedrock retenha dados de conversação devem store definir explicitamente como false em cada solicitação ou definir o modo de retenção de dados da conta paranone, que rejeita uma declaração explícita. store=true Para obter mais informações, consulte Retenção de dados.

Os dados armazenados são criptografados em repouso e têm como escopo o recurso Projeto da AWS conta chamadora. Os dados são armazenados exclusivamente para atender às suas solicitações e não são usados ou retidos para qualquer outra finalidade. bedrock-mantleAtivado, ele é mantido no local para Região da AWS o qual a solicitação foi enviada. Em bedrock-runtime seguida, uma solicitação que usa inferência entre regiões pode ser processada em outra Região da AWS, e a resposta é armazenada na região que a processou. Portanto, uma solicitação que usa um perfil de inferência global pode armazenar dados em qualquer região comercial para a qual o perfil é direcionado. Se você tiver requisitos de residência de dados, use um perfil de inferência geográfica em vez de um perfil global.

Solicitação básica

Para criar uma resposta, escolha a guia do seu método preferido e siga as etapas:

OpenAI SDK (Python)
# Create a basic response using the OpenAI SDK
# Requires OPENAI_API_KEY and OPENAI_BASE_URL environment variables

from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="openai.gpt-oss-120b",
    input=[
        {"role": "user", "content": "Hello! How can you help me today?"}
    ]
)

print(response)
HTTP request

Faça uma solicitação POST para/v1/responses:

# Create a basic response
# Requires OPENAI_API_KEY and OPENAI_BASE_URL environment variables

curl -X POST $OPENAI_BASE_URL/responses \
   -H "Content-Type: application/json" \
   -H "Authorization: Bearer $OPENAI_API_KEY" \
   -d '{
    "model": "openai.gpt-oss-120b",
    "input": [
        {"role": "user", "content": "Hello! How can you help me today?"}
    ]
}'

Transmita respostas

Para receber eventos de resposta de forma incremental, escolha a guia do seu método preferido e siga as etapas:

OpenAI SDK (Python)
# Stream response events incrementally using the OpenAI SDK
# Requires OPENAI_API_KEY and OPENAI_BASE_URL environment variables

from openai import OpenAI

client = OpenAI()

stream = client.responses.create(
    model="openai.gpt-oss-120b",
    input=[{"role": "user", "content": "Tell me a story"}],
    stream=True
)

for event in stream:
    print(event)
HTTP request

Faça uma solicitação POST para /v1/responses com stream definido comotrue:

# Stream response events incrementally
# Requires OPENAI_API_KEY and OPENAI_BASE_URL environment variables

curl -X POST $OPENAI_BASE_URL/responses \
   -H "Content-Type: application/json" \
   -H "Authorization: Bearer $OPENAI_API_KEY" \
   -d '{
    "model": "openai.gpt-oss-120b",
    "input": [
        {"role": "user", "content": "Tell me a story"}
    ],
    "stream": true
}'

Usando a API Responses no endpoint básico de tempo de execução

A API de respostas ativada bedrock-runtime usa o mesmo formato de solicitação e respostabedrock-mantle, então o OpenAI SDK funciona com qualquer uma delas. O que muda é o URL base, os IDs do modelo, as permissões e um pequeno número de comportamentos descritos nesta seção.

URL e caminhos básicos

Defina seu URL base comohttps://bedrock-runtime.region.amazonaws.com/openai/v1. A API é veiculada nos seguintes caminhos:

  • POST /openai/v1/responses— criar uma resposta.

  • GET /openai/v1/responses/{id}— recuperar uma resposta armazenada.

  • POST /openai/v1/responses/{id}/cancel— cancelar uma resposta que ainda está em andamento.

  • DELETE /openai/v1/responses/{id}— excluir uma resposta armazenada.

IDs de modelo

Nomeie um perfil de inferência entre regiões como modelo, não como ID de modelo básico. Os modelos OpenAI GPT usam os global. perfis us. e nas regiões comerciais e os us-gov. perfis nas regiões AWS GovCloud (EUA) — por exemplo,us.openai.gpt-5.6-sol. In-Region a inferência não está disponível para esses modelos nesse endpoint. Para obter a ID do perfil de cada modelo, consulte sua placa de modelo eModelos em resumo, para saber como o roteamento funciona, consulteEncaminhe as solicitações de inferência do modelo entre Regiões da AWS com inferência entre regiões.

Permissões

A criação de uma resposta autoriza dois recursos: bedrock:InvokeModel (oubedrock:InvokeModelWithResponseStream) no alvo de inferência, como acontece com qualquer solicitação de inferência, e bedrock:InvokeModel no projeto padrão da sua conta. Recuperar, cancelar e excluir uma resposta armazenada autorizabedrock:GetInvoke, e bedrock:DeleteInvoke respectivamentebedrock:CancelInvoke, cada uma no projeto. IDs de resposta individuais não são recursos do IAM.

Duas chaves de condição permitem que uma política sobre um recurso restrinja o outro. A autorização do alvo de inferência carregabedrock:ProjectArn, e a autorização do projetobedrock:ModelArn, o valor do perfil de inferência ou do modelo de base que sua solicitação nomeou — nunca os modelos de destino para os quais um perfil entre regiões é direcionado. Para obter exemplos de políticas, consulte Pré-requisitos para executar a inferência do modelo.

Diferenças de comportamento

  • As solicitações são sempre síncronas. background=trueé rejeitado com um erro 400. O store parâmetro não é afetado e mantém o padrão detrue, portanto, as conversas armazenadas em vários turnos funcionam normalmente.

  • modelé exigido em todas as solicitações, incluindo uma que forneçaprevious_response_id. Isso difere da especificação da API de OpenAI respostas e debedrock-mantle, em que o modelo pode ser omitido e herdado da resposta anterior. O modelo é parte daquilo contra o qual a solicitação é autorizada, portanto, ele deve ser nomeado na própria solicitação.

  • Server-side o uso de ferramentas e as ferramentas pré-configuradas não estão disponíveis, incluindo pesquisa Pesquisa na Web na web. Client-side o uso da ferramenta funciona em ambos os terminais.

  • Somente o projeto padrão é suportado. O OpenAI-Project cabeçalho é aceito somente como default ou como seu próprio ARN padrão do projeto; qualquer outro valor é rejeitado. Consulte Projetos (OpenAI-compatible).

  • Não há suporte para perfis de inferência de aplicativos. Uma solicitação que nomeia um como seu alvo de inferência é rejeitada com um erro 400. Os perfis de inferência do sistema, geográficos e globais funcionam normalmente.

  • Os guardrails não se aplicam à API de respostas. Para aplicar uma barreira de proteção a um modelo GPT nesse endpoint, chame a API Converse em vez disso. Inferência usando a API Converse

  • Uma resposta armazenada pertence à pessoa Região da AWS que a forneceu. Recuperá-lo, cancelá-lo ou excluí-lo e continuar a conversa com previous_response_id ele são todos feitos por essa região. Uma ID de resposta que não pode ser encontrada, porque nunca existiu, pertence a outra conta ou nunca foi armazenada, retorna o mesmo erro 404 em todos os casos.

Monitoramento e custo

Como cada solicitação é síncrona, CloudWatch as métricas e o registro de invocação de modelos funcionam para a API de respostas da mesma forma que funcionam para as outras APIs de inferência nesse endpoint, inclusive para solicitações de streaming. O uso é atribuído à meta de inferência, exatamente como no Converse e InvokeModel — o projeto padrão nunca é a âncora de cobrança. Consulte Acompanhe o uso e os custos no Amazon Bedrock.