Compatibilidad con el SDK de OpenAI

Primeros pasos con el SDK de OpenAI

Para usar la función de compatibilidad con el SDK de OpenAI, necesitas:

1. Usar un SDK oficial de OpenAI.
2. Cambiar lo siguiente:
   • Actualiza tu URL base para que apunte a la API de Claude.
   • Reemplaza tu clave de API por una clave de API de Claude de la Claude Console.
   • Si tu clave es una clave personal o de cuenta de servicio que no está limitada a un espacio de trabajo, envía también el encabezado anthropic-workspace-id en cada solicitud (por ejemplo, default_headers en el SDK de Python o defaultHeaders en TypeScript); consulta Seleccionar un espacio de trabajo.
   • Actualiza el nombre de tu modelo para usar un modelo de Claude.
3. Revisa las siguientes secciones para ver qué funciones son compatibles.

Ejemplo de inicio 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)

Limitaciones importantes de compatibilidad con OpenAI

Comportamiento de la API

Estas son las diferencias más sustanciales con respecto al uso de OpenAI:

• El parámetro strict para "function calling" (llamada a funciones) se ignora, lo que significa que no se garantiza que el JSON de uso de herramientas siga el esquema proporcionado. Para garantizar la conformidad con el esquema, usa la API de Claude nativa con salidas estructuradas.
• La entrada de audio no es compatible; se ignora y se elimina de la entrada.
• El almacenamiento en caché de prompts no es compatible, pero sí lo es en los SDK de Anthropic.
• Los mensajes de sistema/desarrollador se elevan y se concatenan en el campo system de nivel superior, sin importar dónde aparezcan en la conversación. Para agregar instrucciones del sistema a mitad de una conversación, usa mensajes del sistema a mitad de la conversación en la Claude API nativa.

La mayoría de los campos no compatibles se ignoran silenciosamente en lugar de producir errores. Todos ellos están documentados en las siguientes secciones.

Consideraciones sobre la calidad de la salida

Si has ajustado tu prompt extensamente, es probable que esté bien adaptado específicamente a OpenAI. Considera reformularlo para Claude usando la guía de mejores prácticas de prompting.

Elevación de mensajes de sistema / desarrollador

La mayoría de las entradas del SDK de OpenAI se corresponden claramente de forma directa con los parámetros de la API de Claude, pero una diferencia distintiva es el manejo de los prompts de sistema / desarrollador. Estos dos prompts pueden colocarse a lo largo de una conversación de chat en la API de OpenAI. La capa de compatibilidad toma todos los mensajes de sistema/desarrollador y los concatena con un único salto de línea (\n) entre ellos. Esta cadena completa se proporciona luego como el campo system de nivel superior, antes de todos los mensajes.

Compatibilidad con el pensamiento

Puedes habilitar el pensamiento agregando el parámetro thinking. En los modelos actuales, el pensamiento es adaptativo: Claude determina cuándo y con qué profundidad pensar, y en los modelos Claude 5 está activado de forma predeterminada; el "extended thinking" (pensamiento extendido) configurado manualmente es un modo heredado. Aunque el pensamiento mejora el razonamiento de Claude en tareas complejas, el SDK de OpenAI no devuelve el pensamiento de Claude. Para obtener todas las funciones de pensamiento, incluido el pensamiento resumido, usa la 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}},
)

Límites de velocidad

Los "rate limits" (límites de velocidad) siguen los límites estándar de Anthropic para el endpoint /v1/messages.

Compatibilidad detallada con la API compatible con OpenAI

Campos de solicitud

Campos simples

Campos tools / functions

Campos del array messages

Campos de respuesta

Compatibilidad de mensajes de error

La capa de compatibilidad mantiene formatos de error coherentes con la API de OpenAI. Sin embargo, los mensajes de error detallados no son equivalentes. Usa los mensajes de error solo para registro y depuración.

Compatibilidad de encabezados

Aunque el SDK de OpenAI gestiona automáticamente los encabezados, esta es la lista completa de encabezados compatibles con la API de Claude para los desarrolladores que necesiten trabajar con ellos directamente.