Compatibilidade com o SDK da OpenAI

Primeiros passos com o SDK da OpenAI

Para usar o recurso de compatibilidade com o SDK da OpenAI, você precisa:

1. Usar um SDK oficial da OpenAI.
2. Alterar o seguinte:
   • Atualize sua URL base para apontar para a Claude API.
   • Substitua sua chave de API por uma chave de API do Claude do Claude Console.
   • Se sua chave for uma chave pessoal ou de conta de serviço que não esteja vinculada a um workspace, envie também o cabeçalho anthropic-workspace-id em cada requisição (por exemplo, default_headers no SDK Python ou defaultHeaders em TypeScript); consulte Selecionar um workspace.
   • Atualize o nome do seu modelo para usar um modelo Claude.
3. Revise as seções a seguir para saber quais recursos são suportados.

Exemplo de início rápido

import os

from openai import OpenAI

client = OpenAI(
    api_key=os.environ.get("ANTHROPIC_API_KEY"),  # Your Claude API key
    base_url="https://api.anthropic.com/v1/",  # the Claude API endpoint
)

response = client.chat.completions.create(
    model="claude-opus-5-5",  # Claude model name
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Who are you?"},
    ],
)

print(response.choices[0].message.content)

Limitações importantes de compatibilidade com a OpenAI

Comportamento da API

Aqui estão as diferenças mais substanciais em relação ao uso da OpenAI:

• O parâmetro strict para chamada de funções é ignorado, o que significa que não há garantia de que o JSON de uso de ferramentas siga o schema fornecido. Para conformidade garantida com o schema, use a Claude API nativa com saídas estruturadas.
• Entrada de áudio não é suportada; ela é ignorada e removida da entrada.
• O cache de prompt não é suportado, mas é suportado nos SDKs da Anthropic.
• Mensagens de sistema/desenvolvedor são elevadas e concatenadas no campo system de nível superior, onde quer que apareçam na conversa. Para adicionar instruções de sistema no meio de uma conversa, use mensagens de sistema no meio da conversa na Claude API nativa.

A maioria dos campos não suportados é ignorada silenciosamente em vez de produzir erros. Todos eles estão documentados nas seções a seguir.

Considerações sobre a qualidade da saída

Se você ajustou seu prompt extensivamente, é provável que ele esteja bem ajustado especificamente para a OpenAI. Considere reformulá-lo para o Claude usando o guia de melhores práticas de prompting.

Elevação de mensagens de sistema / desenvolvedor

A maioria das entradas do SDK da OpenAI mapeia claramente e diretamente para os parâmetros da Claude API, mas uma diferença distinta é o tratamento dos prompts de sistema / desenvolvedor. Esses dois prompts podem ser colocados ao longo de uma conversa de chat na API da OpenAI. A camada de compatibilidade pega todas as mensagens de sistema/desenvolvedor e as concatena com uma única quebra de linha (\n) entre elas. Essa string completa é então fornecida como o campo system de nível superior, antes de todas as mensagens.

Suporte a pensamento

Você pode habilitar o pensamento adicionando o parâmetro thinking. Nos modelos atuais, o pensamento é adaptativo, com o Claude determinando quando e com que profundidade pensar, e nos modelos Claude 5 ele vem ativado por padrão; o "extended thinking" (pensamento estendido) configurado manualmente é um modo legado. Embora o pensamento melhore o raciocínio do Claude em tarefas complexas, o SDK da OpenAI não retorna o pensamento do Claude. Para recursos completos de pensamento, incluindo o pensamento resumido, use a Claude API nativa.

response = client.chat.completions.create(
    model="claude-sonnet-4-6",
    messages=[{"role": "user", "content": "Who are you?"}],
    extra_body={"thinking": {"type": "enabled", "budget_tokens": 2000}},
)

Limites de taxa

Os "rate limits" (limites de taxa) seguem os limites padrão da Anthropic para o endpoint /v1/messages.

Suporte detalhado à API compatível com a OpenAI

Campos de requisição

Campos simples

Campos tools / functions

Campos do array messages

Campos de resposta

Compatibilidade de mensagens de erro

A camada de compatibilidade mantém formatos de erro consistentes com a API da OpenAI. No entanto, as mensagens de erro detalhadas não são equivalentes. Use as mensagens de erro apenas para logging e depuração.

Compatibilidade de cabeçalhos

Embora o SDK da OpenAI gerencie os cabeçalhos automaticamente, aqui está a lista completa de cabeçalhos suportados pela Claude API para desenvolvedores que precisam trabalhar com eles diretamente.