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ê precisará:

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
   • Se sua chave for uma chave pessoal ou de conta de serviço com acesso a vários workspaces, envie também o cabeçalho anthropic-workspace-id em cada requisição (por exemplo, default_headers no SDK Python ou defaultHeaders no TypeScript); consulte Selecionar um workspace
   • Atualize o nome do seu modelo para usar um modelo Claude
3. Revisar 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",  # 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 esquema fornecido. Para conformidade garantida com o esquema, use a Claude API nativa com Structured Outputs.
• Entrada de áudio não é suportada; ela será ignorada e removida da entrada
• O "prompt caching" (cache de prompt) não é suportado, mas é suportado nos SDKs da Anthropic
• Mensagens de sistema/desenvolvedor são elevadas e concatenadas no início da conversa, já que a Anthropic suporta apenas uma única mensagem de sistema inicial.

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ê fez muitos ajustes no seu prompt, é 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 de forma direta para os parâmetros da API da Anthropic, 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 via OpenAI. Como a Anthropic suporta apenas uma mensagem de sistema inicial, a API 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 um único prompt do sistema no início das mensagens.

Suporte a pensamento

Você pode habilitar o pensamento adicionando o parâmetro thinking. Nos modelos atuais, o pensamento é adaptativo, com o Claude decidindo quando e com que profundidade pensar, e nos modelos Claude 5 ele está 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 processo de pensamento detalhado do Claude. Para recursos completos de pensamento, incluindo acesso à saída de raciocínio passo a passo do Claude, 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 serã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.