Observação
O acesso a essa página exige autorização. Você pode tentar entrar ou alterar diretórios.
O acesso a essa página exige autorização. Você pode tentar alterar os diretórios.
Este artigo mostra como usar a API do OpenAI Azure v1. A API v1 simplifica a autenticação, remove a necessidade de parâmetros datados api-version e dá suporte a chamadas de modelo entre provedores.
Nota
Novos objetos de resposta de API podem ser adicionados à resposta da API a qualquer momento. Recomendamos que você analise apenas os objetos de resposta necessários.
Pré-requisitos
- Uma assinatura Azure – Criar uma gratuitamente
- Um recurso Foundry ou recurso Azure OpenAI implantado em uma região suportada
- Pelo menos uma implantação de modelo
- Para a autenticação do Microsoft Entra ID: a função
Cognitive Services OpenAI Useratribuída à sua identidade. Para obter mais informações, consulte o controle de acesso baseado em funções para Azure OpenAI
Evolução da API
Anteriormente, Azure OpenAI recebia atualizações mensais de novas versões de API. Aproveitar os novos recursos exigia atualizar constantemente o código e as variáveis de ambiente a cada nova versão da API. Azure OpenAI também exigiu a etapa extra de usar Azure clientes específicos que criaram sobrecarga ao migrar código entre OpenAI e Azure OpenAI.
A partir de agosto de 2025, você pode optar pela próxima geração v1 Azure APIs OpenAI que adicionam suporte para:
- Acesso contínuo aos recursos mais novos sem a necessidade de especificar novos
api-versiontodos os meses. - Ciclo de lançamento de API mais rápido com novos recursos sendo iniciados com mais frequência.
- Suporte de cliente OpenAI com mínimas alterações de código para alternar entre OpenAI e Azure OpenAI ao usar autenticação baseada em chave.
- Suporte ao cliente OpenAI para autenticação baseada em token e atualização automática de token sem a necessidade de assumir uma dependência em um cliente OpenAI Azure separado.
- Faça chamadas de conclusão de chat com modelos de outros provedores, como DeepSeek e Grok, que dão suporte à sintaxe de conclusões de chat v1.
O acesso a novas chamadas à API que ainda estão em versão prévia será controlado passando cabeçalhos de visualização específicos do recurso, permitindo que você aceite os recursos desejados, sem precisar trocar as versões da API. Como alternativa, alguns recursos indicarão o status de visualização por meio de seu caminho de API e não exigirão um cabeçalho adicional.
Exemplos:
- Quando
/openai/v1/evalsestava em versão prévia, era necessário enviar o cabeçalho"aoai-evals":"preview". /evals não está mais em versão prévia. -
/openai/v1/fine_tuning/alpha/graders/está em versão prévia e não requer nenhum cabeçalho personalizado devido à presença no caminho daalphaAPI.
Para o lançamento inicial da API GA (Disponibilidade Geral) v1, apenas um subconjunto das funcionalidades de inferência e criação da API é suportado. Todos os recursos de GA têm suporte para uso em produção. O suporte para mais recursos está sendo adicionado rapidamente.
Alterações de código
API v1
Python v1 exemplos
Chave de API:
import os
from openai import OpenAI
client = OpenAI(
api_key=os.getenv("AZURE_OPENAI_API_KEY"),
base_url="https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/"
)
response = client.responses.create(
model="gpt-4.1-nano", # Replace with your model deployment name
input="This is a test.",
)
print(response.model_dump_json(indent=2))
Principais diferenças da API anterior:
-
OpenAI()o cliente é usado em vez deAzureOpenAI(). -
base_urlpassa pelo endpoint do Azure OpenAI e/openai/v1é acrescentado ao endereço do endpoint. -
api-versionnão é mais um parâmetro necessário com a API ga v1.
Chave de API com variáveis de ambiente:
Defina as seguintes variáveis de ambiente antes de executar o código:
| Variável | Valor |
|---|---|
OPENAI_BASE_URL |
https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/ |
OPENAI_API_KEY |
Sua chave de API openai do Azure |
Em seguida, crie o cliente sem parâmetros:
client = OpenAI()
Microsoft Entra ID:
Importante
O gerenciamento da atualização automática de token era anteriormente feito por meio do uso do cliente AzureOpenAI(). A API v1 remove essa dependência adicionando suporte automático de atualização de token ao OpenAI() cliente.
from openai import OpenAI
from azure.identity import DefaultAzureCredential, get_bearer_token_provider
token_provider = get_bearer_token_provider(
DefaultAzureCredential(), "https://ai.azure.com/.default"
)
client = OpenAI(
base_url = "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
api_key = token_provider
)
response = client.responses.create(
model="gpt-4.1-nano",
input= "This is a test"
)
print(response.model_dump_json(indent=2))
-
base_urlpassa pelo endpoint do Azure OpenAI e/openai/v1é acrescentado ao endereço do endpoint. -
api_keyo parâmetro é definido como , habilitando atoken_providerrecuperação automática e a atualização de um token de autenticação em vez de usar uma chave de API estática.
Suporte ao modelo
Para Azure modelos OpenAI, recomendamos usar a API Responses, no entanto, a API v1 também permite que você faça chamadas de conclusão de chat com modelos de outros provedores, como DeepSeek e Grok, que dão suporte à sintaxe de conclusões de chat do OpenAI v1.
base_url aceitará ambos https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/ e https://YOUR-RESOURCE-NAME.services.ai.azure.com/openai/v1/ formatos.
Nota
A API de respostas também funciona com modelos de Foundry vendidos diretamente por Azure, como modelos de IA Microsoft, DeepSeek e Grok. Para saber como usar a API de Respostas com esses modelos, consulte Como gerar respostas de texto com modelos Microsoft foundry.
from openai import OpenAI
from azure.identity import DefaultAzureCredential, get_bearer_token_provider
token_provider = get_bearer_token_provider(
DefaultAzureCredential(), "https://ai.azure.com/.default"
)
client = OpenAI(
base_url = "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
api_key=token_provider,
)
completion = client.chat.completions.create(
model="MAI-DS-R1", # Replace with your model deployment name.
messages=[
{"role": "system", "content": "You are a helpful assistant."},
{"role": "user", "content": "Tell me about the attention is all you need paper"}
]
)
#print(completion.choices[0].message)
print(completion.model_dump_json(indent=2))
Suporte à API v1
- especificação v1 OpenAPI 3.0
Registro de alterações da versão da API
As seções a seguir resumem as alterações entre as versões da API.
Alterações entre a versão prévia da v1 e a versão 2025-04-01-preview
- API de visualização v1
- Suporte à geração de vídeo
-
NOVIDADES Recursos da API de respostas:
- Integração da ferramenta do servidor do Protocolo de Contexto de Modelo Remoto (MCP)
- Suporte para tarefas em segundo plano assíncronas
- Itens de raciocínio criptografados
- Geração de imagem
Alterações entre 2025-04-01-preview e 2025-03-01-preview
Alterações entre 2025-03-01-preview e 2025-02-01-preview
- API de respostas
- Uso do computador
Alterações entre 2025-02-01-preview e 2025-01-01-preview
- Conclusões armazenadas (suporte à API de destilação).
Alterações entre 2025-01-01-preview e 2024-12-01-preview
-
predictionparâmetro adicionado para suporte a saídas previstas . -
gpt-4o-audio-previewsuporte ao modelo.
Alterações entre 2024-12-01-preview e 2024-10-01-preview
-
storeemetadataparâmetros adicionados para suporte a conclusões armazenadas. -
reasoning_effortadicionado para os modelos de raciocínio mais recentes. -
user_security_contextadicionado para Microsoft Defender para Nuvem integration.
Alterações entre 2024-09-01-preview e 2024-08-01-preview
-
max_completion_tokensadicionado para dar suporte aos modeloso1-previeweo1-mini.max_tokensnão funciona com os modelos da série o1 . -
parallel_tool_callsAdicionado. -
completion_tokens_details&reasoning_tokensacrescentou. -
stream_options&include_usageacrescentou.
Alterações entre a especificação da API 2024-07-01-preview e 2024-08-01-preview
- Suporte a saídas estruturadas.
- API de upload para arquivos grandes adicionada.
- Em suas alterações de dados:
- Integração do Mongo DB.
-
role_informationparâmetro removido. -
rerank_scoreadicionado ao objeto de citação. - Fonte de dados AML removida.
- Melhorias de integração na vetorização de Pesquisa de IA.
Alterações entre a especificação da API 2024-05-01-preview e 2024-07-01-preview
- Suporte à API de Lote adicionado
- Parâmetros de estratégia de agrupamento do repositório vetor
-
max_num_resultsque a ferramenta de pesquisa de arquivos deve gerar.
Alterações entre a especificação da API 2024-04-01-preview e 2024-05-01-preview
- Suporte a Assistentes versão 2 – Ferramenta de pesquisa de arquivos e armazenamento vetorial
- Ajuste pontos de verificação, seed, eventos
- Em suas atualizações de dados
- DALL-E 2 agora dá suporte à implantação de modelo e pode ser usado com a API de versão prévia mais recente.
- Atualizações de filtragem de conteúdo
Alterações entre a especificação da API 2024-03-01-preview e 2024-04-01-preview
-
Alteração significativa: parâmetros de aprimoramentos removidos. Isso afeta a
gpt-4versão:vision-previewmodelo. - timestamp_granularities parâmetro adicionado.
-
audioWordobjeto adicionado. - TTS
response_formats: wav & pcmadicionais.
Problemas conhecidos
- A especificação
2025-04-01-previewAzure OpenAI usa OpenAPI 3.1. É um problema conhecido que essa versão não é totalmente compatível com Gerenciamento de API do Azure.