Clave de API Codex, explicada para desarrolladores

Comprensión del formato de la clave de API

Al registrarte en un servicio que proporciona una codex api key, recibes una cadena alfanumérica única. Esta clave actúa como tu credencial de autenticación para cada petición enviada al backend. El formato suele seguir un patrón estándar, como sk-... o prefijos similares, según la implementación del proveedor. Sin embargo, como usas un proxy independiente, el prefijo exacto puede variar. El factor crítico no es el formato en sí, sino asegurarte de pasar la clave correctamente en el encabezado HTTP Authorization como Bearer <your_key>.

Tu clave de API está vinculada a una cuenta y nivel de uso específicos. A diferencia de algunos servicios que generan múltiples claves para diferentes entornos (dev vs. prod), nuestra configuración es sencilla: una cuenta, una clave. Si pierdes tu clave o sospechas que ha sido comprometida, puedes regenerarla inmediatamente desde tu panel. Esto revoca la clave antigua al instante, asegurando que no persista ningún acceso no autorizado. Recuerda actualizar tus variables de entorno o archivos de configuración cada vez que rotas las claves.

Mejores prácticas de seguridad

• Almacena tu clave en variables de entorno, no en tu código fuente.
• Nunca commitees tu codex api key a repositorios públicos.
• Usa la función de regeneración si sospechas exposición.

Error común: 401 No autorizado

Un error 401 Unauthorized es el problema más común al integrar una nueva clave de API. Indica que el servidor rechazó tus credenciales de autenticación. En el contexto de un claude code proxy o cualquier endpoint compatible con OpenAI, esto casi siempre significa que la clave falta, es incorrecta o está expirada.

Para solucionar problemas, primero verifica que estés copiando la clave exactamente como se proporcionó. Las claves suelen ser sensibles a mayúsculas y minúsculas y pueden contener espacios si se copian incorrectamente. Asegúrate de usar la URL base correcta para tu región o nivel de servicio. Si regeneraste tu clave recientemente, asegúrate de que tu cliente esté usando el nuevo valor. Un error 401 no está relacionado con tu saldo de uso ni con los límites de peticiones; es puramente un fallo de autenticación.

Lista de verificación para la resolución

1. Confirma que la cadena de la clave de API coincide exactamente con la del panel.
2. Verifica el formato del encabezado Authorization: Authorization: Bearer YOUR_KEY.
3. Verifica que la URL base sea correcta para tu tipo de cuenta.
4. Asegúrate de que no se haya añadido espacio en blanco adicional durante el copiado y pegado.

Límite de peticiones excedido: errores 429

Cuando excedes el volumen de peticiones permitido, la API devuelve un error 429 Demasiadas peticiones. Para nuestro servicio, el límite se establece en 300 peticiones por minuto por clave. Este límite se aplica para garantizar un uso justo y mantener una baja latencia para todos los usuarios. Si estás ejecutando sesiones de codificación de alto volumen, podrías alcanzar este límite rápidamente, especialmente si tu código desencadena múltiples peticiones internas.

Cuando se produce un error 429, la respuesta suele incluir un encabezado Retry-After que indica cuántos segundos debes esperar antes de reintentar. Implementar un retardo exponencial en el código de tu cliente es la forma estándar de manejar estos errores de manera adecuada. En lugar de reintentar inmediatamente, espera un breve período y luego duplica el tiempo de espera para los reintentos posteriores. Esto evita que tu aplicación inunde el servidor con peticiones mientras se restablece el límite.

Es importante tener en cuenta que los límites de peticiones son por clave, no por cuenta. Si tienes varios dispositivos o procesos usando la misma clave, comparten el presupuesto de 300 peticiones/minuto. Considera usar claves separadas para diferentes entornos si necesitas un mayor rendimiento agregado.

Configuración correcta de la URL base

La URL base es la base de cualquier integración de API. Para un servicio compatible con OpenAI, la URL base determina dónde se envían tus peticiones. Nuestra URL base es https://api.claudecodeapikey.com/v1. Esta URL debe configurarse en tu biblioteca cliente o SDK antes de hacer cualquier petición. Si usas la URL base incorrecta, recibirás errores de conexión o respuestas inesperadas.

Muchos desarrolladores utilizan el SDK oficial de OpenAI para Python, Node.js u otros lenguajes. Para cambiar a nuestro proxy, simplemente debes modificar la configuración de la URL base. Por ejemplo, en Python, podrías establecer base_url='https://api.claudecodeapikey.com/v1'. Asegúrate de que el protocolo (https) y la ruta (/v1) sean correctos. Omite la ruta /v1 es un error común que provoca errores 404.

Verifica siempre que tu cliente esté enviando peticiones al endpoint correcto. Puedes hacer esto revisando tus registros de red o usando una herramienta como curl para probar la conexión. Una conexión exitosa a la URL base confirma que tu configuración es correcta.

Manejo de respuestas en streaming

Las respuestas en streaming te permiten recibir partes de la respuesta de la API a medida que se generan, en lugar de esperar a que la respuesta completa termine. Esto es crucial para agentes de código que muestran fragmentos de código en tiempo real. Nuestra API admite streaming mediante Eventos Enviados por Servidor (SSE). Cuando habilitas el streaming en tu cliente, recibirás un flujo de fragmentos, cada uno conteniendo una respuesta parcial.

Para habilitar el streaming, establece el parámetro stream en true en tu petición. La biblioteca del cliente gestionará automáticamente el protocolo SSE. Puedes procesar cada fragmento a medida que llega, actualizando tu interfaz de usuario o registrando el progreso. Esto proporciona una mejor experiencia de usuario, especialmente para generaciones de código largas.

El streaming no cambia el modelo subyacente ni sus capacidades. Es puramente un mecanismo de transporte. El modelo sigue procesando todo el prompt y generando la respuesta completa; la diferencia está en cómo se entrega la salida a tu cliente.

Copyfrom openai import OpenAI

client = OpenAI(base_url="https://api.claudecodeapikey.com/v1", api_key="YOUR_KEY")

resp = client.chat.completions.create(
    model="uncensored",
    messages=[{"role": "user", "content": "Summarise this thread without softening it."}],
)
print(resp.choices[0].message.content)

Problemas de configuración de llamadas a herramientas

Las llamadas a herramientas (o llamadas a funciones) permiten al LLM solicitar acciones específicas, como ejecutar un fragmento de código o consultar una base de datos. Nuestra API admite llamadas a herramientas, lo que significa que puedes definir funciones en tu petición y recibir respuestas JSON estructuradas del modelo. Esto es esencial para agentes de código avanzados que necesitan interactuar con sistemas externos.

Para configurar las llamadas a funciones, debes proporcionar una lista de definiciones de funciones en el parámetro tools. Cada herramienta debe tener un nombre, una descripción y un esquema de parámetros. El modelo decidirá entonces cuándo llamar a una herramienta en función del prompt. Si el modelo decide llamar a una herramienta, la respuesta incluirá una matriz tool_calls con el nombre de la función y los argumentos.

Los problemas comunes surgen de definiciones incorrectas del esquema JSON. Asegúrate de que los tipos de parámetros y los campos requeridos estén especificados con precisión. Si el esquema no es válido, el modelo puede fallar al llamar a la herramienta correctamente. Prueba tus definiciones de herramientas con prompts simples para verificar que el modelo entiende el comportamiento esperado.

Límites de la ventana de contexto

La ventana de contexto define la cantidad máxima de texto que el modelo puede procesar en una sola petición, incluyendo tanto el prompt (entrada) como la finalización (salida). Nuestro modelo tiene una ventana de contexto de 100,000 tokens. Esta es una cantidad significativa de texto, pero no es infinita. Si tu prompt más la salida esperada excede este límite, la API devolverá un error.

Para gestionar el contexto de manera eficiente, monitorea el uso de tokens de tus prompts. Los archivos largos o los historiales de conversación extensos pueden consumir rápidamente los tokens disponibles. Si te acercas al límite, considera truncar mensajes antiguos o resumir interacciones anteriores. Algunos clientes manejan esto automáticamente deslizando la ventana, pero es mejor ser consciente del límite para evitar errores inesperados.

Recuerda que la ventana de contexto incluye todos los tokens enviados al modelo, incluidos los mensajes del sistema, del usuario y del asistente. Planifica tu presupuesto de tokens en consecuencia para asegurar un funcionamiento fluido durante sesiones de código largas.

Regeneración de tu clave

Regenerar tu clave de API es un proceso sencillo que garantiza la seguridad. Si sospechas que tu clave ha sido expuesta o deseas rotar las credenciales periódicamente, puedes generar una nueva clave desde tu panel. La clave anterior se invalida de inmediato, por lo que cualquier petición en curso que utilice la clave antigua fallará.

Cuando regeneres una clave, asegúrate de actualizar todos tus clientes y configuraciones con el nuevo valor. Esto incluye variables de entorno, archivos de configuración y cualquier valor codificado en tu código. No actualizar todas las ubicaciones puede provocar errores de autenticación en algunas partes de tu aplicación.

Nuestro servicio permite regeneraciones ilimitadas de claves. No hay penalización por rotar tu clave con frecuencia. Esta es una buena práctica para mantener la seguridad, especialmente en entornos compartidos o al distribuir claves a miembros del equipo.

Copycurl https://api.claudecodeapikey.com/v1/chat/completions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "uncensored",
    "messages": [{"role": "user", "content": "Write a blunt product review of a cheap VPN."}]
  }'