Guía práctica: Conectando Postman con la API de OpenAI

octubre 31, 2024

En AI Convolution, desde hace varias semanas, estamos hablando de las APIs. Hoy vamos a desglosar paso a paso cómo conectarse a la API de OpenAI utilizando Postman, de una forma tan sencilla como seguir una receta de cocina.

Este será el contenido:

¿Qué es Postman?
Conceptos para empezar
- 3.1. APIs como camareros en un restaurante
- 3.2. Claves API como llaves de tu casa
- 3.3. ¿Qué es un Prompt?
- 3.4. Headers, Authorization y Content-Type
Preparando el terreno
- 4.1. Instalando Postman
- 4.2. Creando una cuenta en OpenAI
Obteniendo tu clave API de OpenAI
Entendiendo el método HTTP a utilizar
Configurando tu primera petición en Postman
- 7.1. Seleccionando el tipo de petición
- 7.2. Configurando la URL
- 7.3. Añadiendo las cabeceras (Headers)
- 7.4. Escribiendo el cuerpo de la petición (Prompt)
- 7.5. Alternativa: Usando cURL para importar en Postman
Enviando la petición y revisando la respuesta
- 8.1. Respuesta de la API y su análisis
Reflexiones finales

1. ¿Qué es Postman?

Imagina que quieres enviar una carta y necesitas un buzón especial que haga llegar tu mensaje al destinatario correcto. Postman es ese buzón mágico para las APIs. Es una herramienta que te permite enviar peticiones y recibir respuestas de manera sencilla, sin necesidad de ser un experto en programación. En otras palabras, es como el cartero que lleva tus mensajes a donde deben ir.

***La imagen muestra una captura de pantalla del software Postman.***

La imagen muestra una captura de pantalla de Postman, que utilizas para hacer y gestionar solicitudes API. En la parte superior, ves una barra de navegación con secciones como «Home», «Workspaces» y «Explore», junto con una advertencia que te informa que estás usando la versión ligera del cliente API. A la izquierda, tienes el historial de solicitudes, con dos entradas de solicitudes POST realizadas al endpoint https://api.openai.com/v1/chat/completions.

En el panel central superior, observas la configuración de una solicitud POST al mismo endpoint, con la pestaña de cuerpo (Body) seleccionada y mostrada en formato JSON. El cuerpo contiene un modelo llamado "gpt-4o-mini", un mensaje de sistema que dice «You are a helpful assistant» y un mensaje tuyo en español pidiendo la creación de un artículo basado en un texto dado.

En la parte inferior de la pantalla, se muestra la respuesta de la API en formato JSON, indicándote que la solicitud fue exitosa (200 OK). Puedes ver el identificador de la respuesta, un objeto con el modelo "gpt-4o-mini-2024-07-18", y un campo choices que contiene un mensaje de respuesta generado por la API, que comienza con el título «### Introducción a la Nueva Funcionalidad de Uso de Ordenadores».

En la esquina inferior izquierda, encuentras un botón para crear colecciones en Postman, y en la parte inferior central, ves la pestaña Console que te indica que no estás conectado a una cuenta de Postman.

Aquí te dejo in tutorial completo en español sobre Postman.

2. Conceptos para empezar

2.1. APIs como camareros en un restaurante

Piensa en una API como en un camarero en un restaurante. Tú (el cliente) le haces un pedido (la petición), y el camarero se lo transmite al chef (el servidor). Luego, el camarero te trae tu plato (la respuesta). La API es el intermediario que facilita la comunicación entre tú y el servicio que deseas utilizar.

2.2. Claves API como llaves de tu casa

Tu clave API es como la llave de tu casa. Es única y te permite acceder a lugares (servicios) a los que otros no pueden entrar. Al igual que no compartirías tu llave con desconocidos, debes mantener tu clave API segura y privada.

2.3. ¿Qué es un Prompt?

El prompt es como darle instrucciones específicas al chef sobre cómo quieres que prepare tu plato. En el contexto de OpenAI, es el texto que envías a la IA para que genere una respuesta. Por ejemplo, «Escribe un poema sobre el mar».

2.4. Headers, Authorization y Content-Type

Los Headers (cabeceras) son como las notas que adjuntas a tu pedido para el camarero. Incluyen información adicional que el servidor necesita para procesar tu petición correctamente.

Authorization: Es como mostrar tu identificación en la entrada de un restaurante exclusivo. Indica que tienes permiso para acceder.
Content-Type: Le dice al servidor en qué formato estás enviando los datos. En este caso, usamos application/json para indicar que el contenido está en formato JSON.

3. Preparando el terreno

3.1. Instalando Postman

Primero, necesitas instalar Postman en tu ordenador. Visita la página oficial de Postman y descarga la versión correspondiente a tu sistema operativo. Es tan sencillo como instalar cualquier otra aplicación.

3.2. Creando una cuenta en OpenAI

Si aún no tienes una cuenta en OpenAI, ve a su página de registro y sigue las instrucciones. Es como crear una cuenta en cualquier red social: rellenas tus datos y listo.

4. Obteniendo tu clave API de OpenAI

Una vez que hayas iniciado sesión en OpenAI, dirígete a la sección de API Keys. Aquí es donde obtendrás tu «llave de la casa». Haz clic en «Create new secret key», copia la clave que te proporcionan y guárdala en un lugar seguro. Recuerda, esta es tu llave personal.

La imagen muestra una captura de pantalla de la sección de «API keys» en la plataforma de OpenAI, específicamente en la página de configuración de una organización. En la parte superior, se observa la URL platform.openai.com/settings/organization/api-keys.

En la parte central, hay un cuadro titulado «API keys» que contiene un mensaje explicativo indicando que, como propietario de la organización, puedes ver y gestionar todas las claves API. Se advierte que no debes compartir tu clave con otros ni exponerla en el navegador o en código del lado del cliente, ya que OpenAI podría desactivar cualquier clave que se filtre públicamente.

Debajo de este texto, se encuentra una tabla con detalles de varias claves API. Las columnas de la tabla muestran la siguiente información:

NAME: El nombre de la clave, con ejemplos como «Federico_2», «Federico_Automate_Tw», y «Leo Key».
SECRET KEY: Los identificadores de las claves están parcialmente enmascarados, comenzando con «sk-«.
LAST USED: La última fecha de uso de cada clave, con fechas como «31 oct 2024» y «4 nov 2024».
PROJECT ACCESS: Todas las claves tienen acceso al «Default project».
CREATED BY: El nombre del creador, que en todos los casos es «aiconvolution».
PERMISSIONS: Todas las claves tienen asignados permisos «All».

En la esquina superior derecha, hay un botón verde etiquetado como “+ Create new secret key”, que permite crear una nueva clave API. A la izquierda de la pantalla, se encuentra el menú de navegación con opciones como «General», «API keys», «Members», «Projects», entre otras.

5. Entendiendo el método HTTP a utilizar

En este caso, utilizaremos el método POST. ¿Por qué? Porque estamos enviando datos al servidor (nuestro prompt) y esperamos que nos devuelva una respuesta basada en esos datos. El método POST se utiliza para crear o actualizar recursos en el servidor.

Aquí te dejo un par de artículos que te serán de utilidad:

6. Configurando tu primera petición en Postman

Ahora viene lo divertido. Vamos a configurar y enviar nuestra primera petición.

6.1. Seleccionando el tipo de petición

Abre Postman y crea una Nueva Petición. Selecciona el método POST del menú desplegable. Esto es como decirle al camarero que quieres hacer un pedido específico que requiere atención especial.

La imagen muestra una captura de pantalla de una herramienta de pruebas de API, como Postman, en la que se está realizando una solicitud HTTP de tipo `POST` a la URL `https://api.openai.com/v1/chat/completions`. Se observa un menú desplegable en la parte superior izquierda con diferentes métodos de solicitud (GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS), y el método seleccionado es `POST`.

6.2. Configurando la URL

En el campo de URL, ingresa:

https://api.openai.com/v1/completions

Esta es la dirección del «restaurante» (servidor) al que quieres hacer tu pedido.

La imagen muestra una captura de pantalla de la interfaz de Postman, una herramienta utilizada para realizar pruebas de APIs. Se observa que se ha configurado una solicitud HTTP de tipo POST hacia la URL https://api.openai.com/v1/chat/completions.

6.3. Añadiendo las cabeceras (Headers)

Ve a la pestaña de Headers y añade las siguientes cabeceras:

Authorization: Escribe Bearer TU_CLAVE_API. Esto es como mostrar tu identificación en la entrada del restaurante.
- Clave: Authorization
- Valor: Bearer TU_CLAVE_API
Content-Type: Escribe application/json. Le estás diciendo al camarero en qué idioma hablas.
- Clave: Content-Type
- Valor: application/json

Nota: Reemplaza TU_CLAVE_API con la clave que copiaste anteriormente.

***La imagen es una captura de pantalla de Postman. Muestra una solicitud HTTP de tipo `POST` a la URL `https://api.openai.com/v1/chat/completions`.***

En la imagen de arriba, en la pestaña «Headers», resaltada con un recuadro rojo, puedes ver dos encabezados definidos:

Content-Type: con el valor application/json, que indica que el contenido de tu solicitud es en formato JSON.
Authorization: con el valor que comienza con Bearer seguido de una clave parcialmente difuminada, que representa un token de autorización para autenticar tu solicitud a la API.

En la parte superior de la imagen, puedes observar otras pestañas como Params, Authorization, Headers, Body, y más, que son opciones de configuración para tu solicitud. A la derecha, está visible el botón azul Send, que te permite enviar la solicitud configurada.

6.4. Escribiendo el cuerpo de la petición (Prompt)

Ahora, ve a la pestaña de Body, selecciona raw y elige JSON en el menú desplegable. Aquí es donde haces tu pedido específico. Por ejemplo:

{
    "model": "gpt-4o-mini",
    "messages": [
        {
            "role": "system",
            "content": "You are a helpful assistant."
        },
        {
            "role": "user",
            "content": "Explícame qué es un Token con 50 palabras"
        }
    ]
}

Estás diciendo: «Quiero que el modelo ‘gpt-4o-mini’ me Explícame qué es un Token con 50 palabras».

La imagen es una captura de pantalla de Postman, . En ella, se está realizando una solicitud POST a la URL https://api.openai.com/v1/chat/completions. Aquí tienes una explicación detallada de cada parte:

Configuración de la solicitud:
- La solicitud es de tipo POST, como se muestra en el menú desplegable de la parte superior izquierda.
- La URL a la que se envía la solicitud es https://api.openai.com/v1/chat/completions, que corresponde al endpoint de OpenAI para completar mensajes de chat.

Sección «Body»:
- La sección del cuerpo de la solicitud está resaltada en un recuadro rojo.
- Se está enviando un cuerpo en formato JSON. El contenido incluye:
  - "model": "gpt-4o-mini", que especifica el modelo de lenguaje utilizado.
  - "messages", un array de mensajes que define la conversación:
  - El primer objeto tiene el "role": "system" y un "content": "You are a helpful assistant.", que establece el contexto para el asistente.
  - El segundo objeto tiene el "role": "user" y un "content": "Explícame qué es un Token con 50 palabras", que es la solicitud específica del usuario pidiendo una explicación breve.

Respuesta de la API:
- Debajo de la sección de configuración, se muestra la respuesta de la API en la pestaña Pretty, que formatea el JSON de manera legible.
- La respuesta tiene un estado 200 OK, indicando que la solicitud fue procesada con éxito.
- Se muestra el objeto de respuesta JSON, que contiene:
  - Un "id" de la respuesta.
  - "created", un campo de timestamp que indica cuándo se creó la respuesta.
  - "model", que confirma el modelo usado.
  - "choices", un array que contiene la respuesta generada. El contenido es:
  - Un objeto con el índice 0, indicando la primera opción.
  - "message", que contiene la respuesta del asistente, con el rol "assistant" y una explicación sobre qué es un token. La explicación menciona que un token es una unidad de valor digital en una blockchain, detalla sus posibles usos como activo o utilidad, y describe los tipos de tokens fungibles y no fungibles, como criptomonedas y NFTs.

Detalles adicionales:
- Se puede ver que la pestaña JSON está seleccionada en la sección «Body», lo que indica que el formato de envío de datos es JSON.
- En la parte inferior derecha, se muestra información sobre la respuesta de la API, incluyendo el estado de la solicitud (200 OK), el tiempo de respuesta (1042 ms), y el tamaño de la respuesta (1.28 KB).

6.5. Alternativa: Usando cURL para importar en Postman

Si prefieres, puedes utilizar el siguiente comando cURL. Esto te permitirá importar la configuración directamente en Postman.

curl --location 'https://api.openai.com/v1/chat/completions' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer TU_CLAVE_API' \
--data '{
    "model": "gpt-4o-mini",
    "messages": [
        {
            "role": "system",
            "content": "You are a helpful assistant."
        },
        {
            "role": "user",
            "content": "Explícame qué es un Token con 50 palabras"
        }
    ]
}

Nota: Asegúrate de reemplazar TU_CLAVE_API con tu clave real.

Para importar en Postman:

Copia el comando cURL.
En Postman, haz clic en Import (Importar) en la parte superior izquierda.
Selecciona la pestaña Raw Text.
Pega el comando cURL y haz clic en Continue.
Haz clic en Import para finalizar.

7. Enviando la petición y revisando la respuesta

Pulsa el botón Send y espera la respuesta. Si todo ha salido bien, verás una respuesta en formato JSON en la sección inferior. Es como recibir tu plato y probar el primer bocado.

***Captura de pantalla de Postman. A la derecha de la barra de solicitud, hay un botón grande y azul etiquetado como `Send`.***

7.1. Respuesta de la API y su análisis

Respuesta:

{
    "id": "chatcmpl-APpW4BJJrzTiW4EJqzGJwLgUayboN",
    "object": "chat.completion",
    "created": 1730719592,
    "model": "gpt-4o-mini-2024-07-18",
    "choices": [
        {
            "index": 0,
            "message": {
                "role": "assistant",
                "content": "Un token es una unidad de valor digital que existe en una blockchain. Representa un activo, un derecho o una utilidad y puede ser utilizado para diversas funciones, como transacciones, acceso a servicios o participación en votaciones. Los tokens pueden ser fungibles, como criptomonedas, o no fungibles, como NFTs.",
                "refusal": null
            },
            "logprobs": null,
            "finish_reason": "stop"
        }
    ],
    "usage": {
        "prompt_tokens": 28,
        "completion_tokens": 65,
        "total_tokens": 93,
        "prompt_tokens_details": {
            "cached_tokens": 0
        },
        "completion_tokens_details": {
            "reasoning_tokens": 0
        }
    },
    "system_fingerprint": "fp_0ba0d124f1"
}

Análisis de la respuesta:

La respuesta de la API de OpenAI que observas es el resultado de una solicitud completada, y aquí te explico cada parte:

Identificación y metadatos:
- "id": "chatcmpl-APpW4BJJrzTiW4EJqzGJwLgUayboN": Es un identificador único de la respuesta de la conversación.
- "object": "chat.completion": Te indica que el objeto de la respuesta es una finalización de chat.
- "created": 1730719592: Es un timestamp Unix que marca la fecha y hora de la creación de la respuesta.
- "model": "gpt-4o-mini-2024-07-18": Te muestra el modelo de lenguaje utilizado, en este caso, una versión de GPT-4 optimizada y fechada el 18 de julio de 2024.

Elecciones de respuesta:
- "choices": Es un array que contiene las posibles respuestas generadas. En este caso, solo tienes una opción.
  - "index": 0: Te indica la posición de la respuesta en la lista de respuestas posibles.
  - "message": Es el contenido de la respuesta:
  - "role": "assistant": Te señala que el contenido proviene del asistente.
  - "content": La respuesta del asistente, que te explica qué es un token de forma clara y concisa. Un token es una unidad de valor digital en una blockchain, que puede representar un activo, derecho o utilidad y puede ser usado en transacciones, acceso a servicios, votaciones, y puede ser fungible (como criptomonedas) o no fungible (como NFTs).
  - "refusal": null: No hubo una negativa a responder, lo que significa que la solicitud fue atendida sin restricciones.

Detalles adicionales:
- "logprobs": null: No se proporcionaron detalles sobre las probabilidades de los tokens generados.
- "finish_reason": "stop": Te indica que la respuesta terminó de forma natural y no fue interrumpida.

Uso de tokens:
- "usage": Detalla el uso de tokens en la solicitud:
  - "prompt_tokens": 28: Número de tokens que utilizaste en la entrada o prompt de la solicitud.
  - "completion_tokens": 65: Número de tokens usados para generar la respuesta.
  - "total_tokens": 93: Suma total de tokens que se usaron (prompt más respuesta).
  - "prompt_tokens_details": { "cached_tokens": 0 }: Detalle de los tokens almacenados en caché, que en este caso es 0.
  - "completion_tokens_details": { "reasoning_tokens": 0 }: Detalle de tokens usados para el razonamiento, que también es 0.

Fingerprint del sistema:
- "system_fingerprint": "fp_0ba0d124f1": Una huella única que posiblemente ayuda a identificar de manera interna la operación del sistema.

La API ha procesado exitosamente tu solicitud de chat, devolviendo una respuesta informativa sobre qué es un token. La respuesta se generó sin interrupciones, usando un total de 93 tokens (28 para la entrada y 65 para la respuesta).

8. Conceptos clave

Postman: Plataforma para enviar y gestionar solicitudes HTTP y probar APIs de forma eficiente.
APIs (Application Programming Interfaces): Conectores que permiten que diferentes sistemas intercambien datos y funcionalidades.
Claves API: Códigos únicos para autenticar y autorizar solicitudes a un servicio API.
Prompt: Texto o comando que indica a una API cómo debe responder.
Headers: Partes de una solicitud HTTP que contienen metadatos como la autenticación y tipo de contenido.
Authorization: Proceso para garantizar que un usuario tiene permiso para acceder a ciertos recursos.
Content-Type: Header que define el formato de datos de la solicitud, como application/json.
Método HTTP POST: Solicitud utilizada para enviar datos a un servidor, creando o actualizando recursos.
URL de API: La dirección que se usa para hacer la solicitud a una API específica.

9. Reflexiones finales

¡Felicidades! Has realizado tu primera conexión con la API de OpenAI utilizando Postman. Al igual que montar en bicicleta, puede parecer complicado al principio, pero una vez que le coges el truco, es pan comido. Ahora tienes las herramientas básicas para explorar y aprovechar al máximo las capacidades de la API de OpenAI.

Por hoy eso es todo, hasta la próxima!

Post Views: 120