Cómo trabajar con la API de Cohere

Cohere proporciona a los desarrolladores acceso a sofisticados Modelos de Lenguaje Grande (LLMs) capaces de entender y generar texto similar al humano. Para interactuar con estos modelos de manera programática, necesitas una clave API. Esta clave actúa como tu identificador único y contraseña, permitiendo que los sistemas de Cohere autentiquen tus solicitudes y rastreen tu uso.

Esta guía te llevará a través de los pasos esenciales: obtener tu clave API, entender las diferencias críticas entre los tipos de claves (especialmente respecto a costos y límites de uso), y realizar una prueba inicial simple utilizando la herramienta Apidog para asegurarte de que tu clave está funcionando correctamente.

Paso 1: Obtener Tu Clave API de Cohere

Obtener tu clave es el primer y más crucial paso. Cohere hace que este proceso sea relativamente simple a través de su panel en línea.

Navegar al Panel de Cohere: Abre tu navegador web y ve al punto de acceso principal de la plataforma Cohere. Normalmente encontrarás una página de inicio de sesión o registro.
Accede a Tu Cuenta:

Si ya tienes una cuenta de Cohere, inicia sesión utilizando tus credenciales.
Si eres nuevo en Cohere, necesitarás registrarte para obtener una cuenta. Sigue el proceso de registro, que generalmente implica proporcionar una dirección de correo electrónico y establecer una contraseña.

Localiza la Sección de Claves API: Una vez que hayas iniciado sesión con éxito en el panel de Cohere, busca una sección dedicada específicamente a gestionar las Claves API. Esto puede estar bajo la configuración de la cuenta, una sección para desarrolladores, o accesible directamente a través de un elemento de menú etiquetado como "Claves API". La interfaz está diseñada para ser fácil de usar, por lo que debería ser relativamente prominente.

Iniciar la Generación de Claves: Dentro de la sección de Claves API, encontrarás una opción para crear una nueva clave. Es probable que veas opciones que diferencian entre tipos de claves, especialmente "Clave de Prueba" y potencialmente "Clave de Producción". Para pruebas iniciales y aprendizaje, selecciona la opción para generar una Clave de Prueba.

Asignar un Nombre: Se te pedirá que nombres tu clave. Elige un nombre descriptivo que te ayude a recordar su propósito más tarde, especialmente si generas múltiples claves para diferentes proyectos. Ejemplos incluyen "MiPrimeraClaveDePrueba", "ClaveDeProyectoDeAprendizaje" o "ClaveDePruebaDeApidog".

Generar y Asegurar Tu Clave: Haz clic en el botón para confirmar y generar la clave (por ejemplo, "Generar Clave de Prueba"). Cohere luego mostrará tu clave API recién generada. Esta es la única vez que se mostrará la clave completa. Es absolutamente esencial que copies esta clave inmediatamente y la guardes en un lugar muy seguro, como un administrador de contraseñas o una nota segura. Trátala con el mismo nivel de seguridad que una contraseña. No la compartas públicamente, no la incrustes directamente en código del lado del cliente, ni la comprometas en sistemas de control de versiones como Git. Una vez que cierres la ventana emergente o navegues a otra parte, no podrás recuperar la clave completa nuevamente por razones de seguridad (aunque puedes ver el nombre de la clave y potencialmente sus primeros/últimos caracteres en el panel). Si la pierdes, necesitarás generar una nueva.

Con tu clave API copiada y asegurada, estás listo para entender qué puedes hacer con ella y las reglas asociadas.

Paso 2: Entender los Tipos de Claves, Costos y Límites de Uso

No todas las claves API de Cohere son iguales. El tipo de clave que tienes dicta cuánto puedes usar la API, qué tan rápido, y si incurre en costos. Entender estas diferencias es vital para evitar interrupciones o cargos inesperados.

A. Claves API de Prueba: Gratis para Evaluación

Cuando te registras por primera vez o generas una clave sin configurar la facturación, normalmente recibes una Clave de Prueba. Estas están diseñadas para exploración, aprendizaje y pruebas a pequeña escala.

Costo: Las claves de prueba son gratuitas para usar. No se te cobrará por el uso asociado con una clave de prueba.
Límite de Uso General: La restricción más significativa es un límite mensual de 1,000 llamadas API totales en todos los puntos finales de Cohere combinados. Esto significa que cada solicitud que realices (ya sea a Chat, Embed, Rerank, etc.) cuenta para este total mensual. Una vez que alcanzas 1,000 llamadas en un mes calendario, tu clave dejará de funcionar hasta que comience el siguiente mes.
Límites de Tasa (Solicitudes Por Minuto - RPM): Para asegurar un uso justo y la estabilidad del sistema, las claves de prueba también tienen límites de tasa estrictos, restringiendo cuántas solicitudes puedes enviar dentro de un intervalo de un minuto a puntos finales específicos. Estos son cruciales de conocer, ya que excederlos resultará en errores 429 Too Many Requests. Los límites de tasa de claves de prueba incluyen:
Punto Final de Chat (/v2/chat): 20 solicitudes por minuto. Este es el punto final utilizado para IA conversacional, generación de texto, resumido, etc.
Punto Final de Embed (/v2/embed) - Texto: 100 solicitudes por minuto. Utilizado para generar embeddings vectoriales para datos de texto (búsqueda semántica, agrupamiento).
Punto Final de Embed (/v2/embed) - Imágenes: 5 solicitudes por minuto. Utilizado para generar embeddings vectoriales para datos de imagen (búsqueda multimodal).
Punto Final de Rerank (/v2/rerank): 10 solicitudes por minuto. Utilizado para mejorar la clasificación de relevancia de los resultados de búsqueda.
Punto Final de Tokenize (/v2/tokenize): 100 solicitudes por minuto. Utilizado para ver cómo el texto se descompone en tokens por los modelos de Cohere.
Punto Final de Classify (/v1/classify): 100 solicitudes por minuto. Utilizado para tareas de clasificación de texto (legado, preferido para ajuste fino ahora).
Puntos Finales Legado (Resumir, Generar): 5 solicitudes por minuto.
Otros/Por Defecto: Pueden aplicarse límites a otros puntos finales menos comunes o de gestión.

Las claves de prueba son ideales para:

Aprender cómo funciona la API de Cohere.
Experimentar con diferentes modelos y parámetros en el Playground o mediante llamadas directas.
Construir pequeños proyectos personales o prototipos con uso esperado limitado.
Evaluar las capacidades de Cohere antes de comprometerse a un uso pago.

Si constantemente alcanzas el límite mensual o los límites de tasa por minuto, es un fuerte indicador de que necesitas actualizar a una clave de Producción.

B. Claves API de Producción: Para Construir y Escalar

Cuando estés listo para construir aplicaciones con usuarios reales, manejar cargas de trabajo más significativas, o ir más allá de las limitaciones de prueba, necesitarás una Clave de Producción. Esto requiere configurar la información de facturación en tu cuenta de Cohere.

Costo: Las claves de producción operan bajo un modelo de pago por uso basado principalmente en uso de tokens. Los tokens son unidades de texto (que corresponden aproximadamente a palabras o partes de palabras) que los modelos procesan. Se te cobra tanto por los tokens que envías al modelo (tokens de entrada) como por los tokens que el modelo genera en su respuesta (tokens de salida).
Los Precios Varían Según el Modelo: Los modelos más potentes generalmente cuestan más por token que los modelos más ligeros y rápidos.
Ejemplo de Precios (Ilustrativo - consulta la página de precios oficial de Cohere para conocer las tarifas actuales):
Modelo Command R: Podría costar alrededor de $0.50 por millón de tokens de entrada y $1.50 por millón de tokens de salida. (Nota: El resultado de búsqueda anterior indicó $2.50 de entrada / $10.00 de salida para Command R - usando esos valores: $2.50 / 1M tokens de entrada, $10.00 / 1M tokens de salida.)
Modelo Command R+: Siendo más capaz, probablemente tendría un precio más alto, tal vez $3.00 por millón de tokens de entrada y $15.00 por millón de tokens de salida.
Modelos de Embed (por ejemplo, embed-english-v3.0): Los modelos de embedding generalmente solo se fijan en los tokens de entrada, ya que no generan salidas de texto extensas. El precio podría ser alrededor de $0.10 por millón de tokens de entrada.
Cálculo de Tokens: Cohere proporciona un punto final de Tokenizer y documentación para ayudarte a entender cómo el texto se traduce en tokens para una estimación de costos precisa. Las entradas y salidas más largas naturalmente costarán más.
Límite de Uso General: No hay límite mensual total de llamadas para las claves de producción. Puedes hacer tantas llamadas como necesites, siempre que te mantengas dentro de los límites de tasa y gestiones tus costos.
Límites de Tasa (Solicitudes Por Minuto - RPM): Las claves de producción se benefician de límites de tasa significativamente más altos, permitiendo que las aplicaciones manejen mucho más tráfico:
Punto Final de Chat (/v2/chat): 500 solicitudes por minuto (comparado con 20/min para Prueba).
Punto Final de Embed (/v2/embed) - Texto: 2,000 solicitudes por minuto (comparado con 100/min).
Punto Final de Embed (/v2/embed) - Imágenes: 400 solicitudes por minuto (comparado con 5/min).
Punto Final de Rerank (/v2/rerank): 1,000 solicitudes por minuto (comparado con 10/min).
Punto Final de Tokenize (/v2/tokenize): 2,000 solicitudes por minuto.
Punto Final de Classify (/v1/classify): 1,000 solicitudes por minuto.
Aumentos de Límite de Tasa: Para aplicaciones de muy alto volumen, puede ser posible solicitar aumentos adicionales de límite de tasa contactando al soporte de Cohere.

Las claves de producción son necesarias para:

Desarrollar y desplegar aplicaciones destinadas a usuarios finales.
Manejar volúmenes constantes o altos de solicitudes API.
Cualquier caso de uso comercial.
Desbloquear todo el potencial de rendimiento sin estar limitado por los límites de prueba.

C. Elegir la Clave Correcta:

Comienza con Prueba: Siempre comienza con una clave de prueba para aprender y desarrollo inicial.
Monitorea el Uso: Mantén un ojo en tu volumen de llamadas y frecuencia.
Actualiza Cuando Sea Necesario: Si tu aplicación constantemente alcanza los límites de tasa, excede el límite de 1,000 llamadas mensuales, o si te estás preparando para lanzar públicamente o comercialmente, actualiza a una clave de producción agregando detalles de facturación en el panel de Cohere.

Bien, aquí está la sección revisada del Paso 3 centrada en probar la solicitud de chat en streaming proporcionada en el comando curl usando Apidog, presentada en Markdown:

Paso 3: Realizar una Llamada de Prueba Básica de API para Chat en Streaming con Apidog

Antes de integrar la API en código complejo, especialmente para respuestas en streaming, es útil realizar una prueba directa. Apidog te permite replicar la estructura del comando curl para verificar tu clave y entender el flujo básico de solicitud/respuesta para streaming.

Lanza Apidog: Abre la aplicación Apidog en tu computadora.
Crea una Nueva Solicitud: Haz clic en el botón '+' o equivalente para crear una nueva solicitud de API. Nómbrala algo descriptivo, como "Prueba de Chat en Streaming de Cohere".
Configura el Punto Final:

Método HTTP: Selecciona POST.
URL: Ingresa la URL del punto final de Chat v2 de Cohere: https://api.cohere.ai/v2/chat

4. Configura los Encabezados:

Navega a la pestaña "Encabezados". Necesitarás agregar varios encabezados basados en el comando curl:
Aceptar: Clave: Accept, Valor: application/json
Tipo de Contenido: Clave: Content-Type, Valor: application/json
Autorización: Clave: Authorization, Valor: Bearer TU_CLAVE_API (Reemplaza TU_CLAVE_API con tu clave API de Cohere real. Asegúrate de que hay un espacio después de Bearer).

5. Construye el Cuerpo de la Solicitud (con Streaming Habilitado):

Ve a la pestaña "Cuerpo".
Selecciona la opción de entrada "raw".
Elige JSON como formato.
Pega el siguiente payload JSON, reflejando los datos del comando curl, incluyendo la crucial bandera "stream": true:

{
  "stream": true,
  "model": "command-r",
  "messages": [
    {
      "role": "user",
      "content": "¡Hola mundo!"
    }
  ]
}

(Nota: El ejemplo de curl utilizó "role": "user" (minúscula) y modelo "command-a-03-2025". He mantenido "role": "USER" y modelo "command-r" para consistencia con ejemplos anteriores, pero debes ajustar el modelo y la capitalización del rol en el JSON anterior para que coincida exactamente con la solicitud específica que planeas probar si es diferente.)

6. Ejecuta la Solicitud: Haz clic en el botón "Enviar" en Apidog.

7. Analiza la Respuesta (Especificaciones de Streaming):

Código de Estado: Deberías seguir recibiendo un código de estado 200 OK si la solicitud inicial es aceptada por el servidor.
Encabezados de Respuesta: Revisa los encabezados de respuesta en busca de signos de streaming, como Transfer-Encoding: chunked.
Cuerpo de Respuesta: Cómo Apidog muestra la respuesta en streaming puede variar. Puede:
Esperar hasta que la transmisión se complete y mostrar el texto completamente concatenado o la carga útil del evento final.
Mostrar los fragmentos crudos o Eventos Enviados por el Servidor (SSE) a medida que llegan, potencialmente pareciendo múltiples objetos JSON uno tras otro.
Probablemente no renderizará el texto de manera suave token por token como una aplicación diseñada para ello.
Contenido: Revisa el contenido del cuerpo de respuesta. Deberías ver eventos relacionados con la transmisión, como eventos de text-generation que contienen partes de la respuesta "¡Hola mundo!", y eventualmente un evento stream-end que indica que el proceso ha terminado.
Errores: Si obtienes errores (401, 403, 400, 429), diagósticalos como se describió anteriormente (verifica la clave API, la validez del JSON, los límites de tasa). Un 400 Bad Request puede ocurrir si el modelo especificado no admite streaming o si otros parámetros son incompatibles.

Esta prueba ayuda a confirmar que la API acepta tu solicitud de streaming y que tu clave es válida para este tipo de interacción, incluso si Apidog en sí no es la herramienta ideal para visualizar la naturaleza en tiempo real de la transmisión. Verifica que la configuración fundamental de la solicitud sea correcta.

Conclusión

Ahora tienes tu clave API de Cohere y entiendes las diferencias cruciales entre las claves de Prueba y Producción, particularmente respecto al límite de 1,000 llamadas mensuales y los límites de tasa por minuto en las claves de prueba frente a la facturación por uso, basada en tokens y límites más altos de las claves de producción. También has realizado una prueba básica pero vital usando Apidog para confirmar que tu clave funciona y que puedes estructurar una llamada API simple.

Esta base es esencial para interactuar de manera efectiva con la API de Cohere. Recuerda mantener tu clave segura, monitorear tu uso frente a los límites (especialmente en una clave de prueba), y consultar la documentación de Cohere para obtener información detallada sobre modelos específicos, parámetros avanzados y uso de SDK a medida que comiences a construir aplicaciones más sofisticadas.