how-tos

Guía de la GPT-6.2 API: primera solicitud en cURL y Python, Responses y Chat Completions

Poyo.ai Team
9 min read
Share:

Guía de la GPT-6.2 API: primera solicitud en cURL y Python

Esta guía de la GPT-6.2 API te lleva de una clave de API a una solicitud funcional a gpt-6.2-sol o gpt-6.2-astra en cURL y con el SDK de OpenAI para Python, tanto en el endpoint Responses como en Chat Completions. Todos los cuerpos de solicitud siguen el esquema publicado por PoYo y las notas de migración a GPT-6.2 de OpenAI a fecha de 18 de noviembre de 2026. Puedes probar antes tus prompts en la página del modelo GPT-6.2 Sol o en la página del modelo GPT-6.2 Astra.

¿No conoces todavía los modelos? El resumen de la GPT-6.2 API explica los límites y el posicionamiento.

Antes de empezar

Crea una clave en el panel de PoYo y guárdala en tu servidor:

export POYO_API_KEY="your-poyo-key"
FormatoEndpointCuándo usarlo
ResponsesPOST https://api.poyo.ai/v1/responsesCódigo nuevo, herramientas de funciones, entrada de imágenes, esfuerzo de razonamiento
Chat CompletionsPOST https://api.poyo.ai/v1/chat/completionsCódigo existente de Chat Completions, mensajes solo de texto, sin herramientas

Cada solicitud envía Authorization: Bearer $POYO_API_KEY. Los ejemplos usan gpt-6.2-sol; cámbialo por gpt-6.2-astra para usar Astra. Las estructuras de las solicitudes son idénticas.

Tres reglas de la guía de GPT-6.2 de OpenAI se aplican a todos los ejemplos siguientes:

  1. No envíes temperature ni top_p. OpenAI indica que se omitan, además de logprobs y top_logprobs en Chat Completions y top_logprobs en Responses. Los esquemas de PoYo siguen incluyendo temperature y top_p para modelos anteriores.
  2. No establezcas el esfuerzo de razonamiento en none; la API lo rechaza.
  3. Pon las instrucciones estables en un mensaje developer al principio de input. GPT-6.2 añade las instructions de nivel superior después de input, lo que las saca del prefijo cacheable.

Primera solicitud a la GPT-6.2 API con cURL

curl https://api.poyo.ai/v1/responses \
  -H "Authorization: Bearer $POYO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-6.2-sol",
    "input": [
      {"role": "developer", "content": "You are a code reviewer. Be specific and cite line numbers."},
      {"role": "user", "content": "Review this function for race conditions: ..."}
    ],
    "reasoning": {"effort": "medium"},
    "max_output_tokens": 8000,
    "store": false
  }'

model e input son obligatorios. input es una cadena simple o un array de elementos con role (developer, system, user, assistant) y content. Otros campos documentados que se usan en esta guía: reasoning, max_output_tokens, stream, store, tools, tool_choice, previous_response_id y metadata.

La respuesta es un objeto Responses devuelto directamente. El texto está en los bloques output[].content[] con type: "output_text"; el estado de la llamada, en status; y los recuentos, en usage.input_tokens, usage.output_tokens y usage.total_tokens.

Python con el SDK de OpenAI

Apunta el SDK a PoYo:

import os
from openai import OpenAI

client = OpenAI(base_url="https://api.poyo.ai/v1", api_key=os.environ["POYO_API_KEY"])

resp = client.responses.create(
    model="gpt-6.2-sol",
    input=[
        {"role": "developer", "content": "You are a senior backend engineer."},
        {"role": "user", "content": "Write a migration plan from Celery 4 to Celery 5."},
    ],
    reasoning={"effort": "medium"},
    max_output_tokens=8000,
)

print(resp.output_text)
print(resp.status, resp.usage)

resp.output_text es el helper del SDK que une todos los bloques output_text. Registra resp.usage en cada llamada; la sección de costes de más abajo lo utiliza.

Chat Completions para código existente

Si tu código ya usa chat.completions.create, cambia el modelo y elimina los campos de muestreo:

resp = client.chat.completions.create(
    model="gpt-6.2-sol",
    messages=[
        {"role": "system", "content": "You are a senior backend engineer."},
        {"role": "user", "content": "Explain the CAP theorem with one example per trade-off."},
    ],
    max_tokens=4000,
)
print(resp.choices[0].message.content, resp.choices[0].finish_reason)

La misma solicitud en cURL:

curl https://api.poyo.ai/v1/chat/completions \
  -H "Authorization: Bearer $POYO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-6.2-sol",
    "messages": [{"role": "user", "content": "Explain vector databases in one sentence."}],
    "max_tokens": 1000
  }'

El esquema de Chat Completions de PoYo documenta model, messages (content como cadena; roles system, user, assistant), max_tokens, stream, stop, n y los campos de penalización. No documenta tools, y OpenAI indica que las llamadas a herramientas de GPT-6.2 requieren Responses, así que los agentes deben ir en /v1/responses.

Configurar el esfuerzo de razonamiento en la GPT-6.2 API

OpenAI llama al campo reasoning.effort en Responses y reasoning_effort en Chat Completions. La referencia de Responses de PoYo documenta reasoning (ejemplo {"effort": "medium"}); su referencia de Chat Completions todavía no incluye reasoning_effort, así que esta guía configura el esfuerzo solo en Responses.

SituaciónValorFuente
Integración nuevamediumOpenAI: «Empieza con medium en una integración nueva».
Antes none o minimallowNota de migración a GPT-6.2 de OpenAI
Tareas largas o complejasUn nivel más altoOpenAI: un esfuerzo mayor «puede ayudarle a persistir hasta las comprobaciones finales»
noneSe rechazaPáginas de los modelos de OpenAI

La guía de razonamiento de OpenAI incluye low, medium, high, xhigh y max entre los valores posibles, pero indica que dependen del modelo. Las páginas de los modelos GPT-6.2 no enumeran el conjunto aceptado, así que envía una solicitud de prueba antes de fijar en el código un nivel superior a medium. Los tokens de razonamiento se facturan como salida y cuentan para max_output_tokens; OpenAI los reporta en usage.output_tokens_details.reasoning_tokens.

Streaming de respuestas de la GPT-6.2 API

Con "stream": true, PoYo devuelve text/event-stream. Cada línea data: es un JSON cuyo type indica el evento; el texto llega como response.output_text.delta, y response.completed lleva el objeto final con usage. PoYo no envía líneas event: separadas, y el stream termina con data: [DONE].

stream = client.responses.create(
    model="gpt-6.2-sol",
    input="Write a 100-word product introduction for a log search tool.",
    reasoning={"effort": "low"},
    max_output_tokens=2000,
    stream=True,
    store=False,
)

usage = None
for event in stream:
    if event.type == "response.output_text.delta":
        print(event.delta, end="", flush=True)
    elif event.type == "response.completed":
        usage = event.response.usage
    elif event.type == "response.failed":
        raise RuntimeError(event.response)
print("\n", usage)

En Chat Completions, stream=True devuelve eventos chat.completion.chunk; el texto está en choices[0].delta.content y el último chunk lleva usage.

Entrada de imágenes

GPT-6.2 acepta imágenes junto con texto. En PoYo, envíalas a Responses como bloques input_image con una URL pública o un Data URI completo (data:image/png;base64,...). La documentación de PoYo recomienda poner el texto antes que las imágenes:

{
  "model": "gpt-6.2-sol",
  "input": [
    {
      "role": "user",
      "content": [
        {"type": "input_text", "text": "List every service in this architecture diagram that writes to the database."},
        {"type": "input_image", "image_url": "https://example.com/diagram.png"}
      ]
    }
  ],
  "max_output_tokens": 3000
}

Leer el uso y calcular el coste de una solicitud

Precios de PoYo por 1M de tokens: Sol $1.60 de entrada, $8 de salida, $0.08 de lectura de caché y $2 de escritura en caché; Astra $6.40, $32, $0.32 y $8 (1 crédito = $0.005).

La guía de caché de OpenAI reporta las lecturas de caché facturadas en usage.input_tokens_details.cached_tokens y las escrituras en usage.input_tokens_details.cache_write_tokens. El esquema de PoYo incluye input_tokens_details y output_tokens_details sin enumerar sus claves, así que léelos de forma defensiva:

PRICES = {  # PoYo USD per 1M tokens: input, output, cache read, cache write
    "gpt-6.2-sol":   (1.60, 8.00, 0.08, 2.00),
    "gpt-6.2-astra": (6.40, 32.00, 0.32, 8.00),
}

def estimate_cost_usd(model: str, usage) -> float:
    p_in, p_out, p_read, p_write = PRICES[model]
    details = getattr(usage, "input_tokens_details", None)
    cached = getattr(details, "cached_tokens", 0) or 0
    written = getattr(details, "cache_write_tokens", 0) or 0
    fresh = usage.input_tokens - cached - written
    return (fresh * p_in + cached * p_read + written * p_write
            + usage.output_tokens * p_out) / 1_000_000

Tómalo como una estimación y concílialo con tu registro de uso de PoYo. Todos los precios de aquí son tarifas de contexto corto. OpenAI cobra más por encima de 272K tokens de entrada, así que consulta la página del modelo para cualquier solicitud de ese tamaño. Tienes ejemplos resueltos en precios de la GPT-6.2 API.

Errores que conviene gestionar

HTTPCausaQué hacer
400Campo no válido (validation_error, con detalles)Corrige el cuerpo; un esfuerzo none o un campo no documentado pueden acabar aquí
401Clave de API ausente o no válidaRevisa la cabecera Authorization
402Créditos insuficientesRecarga antes de reintentar
404Modelo desconocido (model_not_found)Revisa el ID: gpt-6.2-sol, gpt-6.2-astra
429Límite de tasaEspera y reintenta
500 / 502 / 503Error del servidor o del proveedor upstreamReintenta con backoff exponencial

La documentación de PoYo indica que los endpoints de LLM no tienen límite de tasa por ahora, pero gestiona 429 de todos modos. Con el SDK de OpenAI, captura openai.APIStatusError y ramifica según status_code. Reintenta solo los 5xx y 429; un 400 seguirá fallando hasta que cambie el cuerpo. Los cuerpos completos están en los códigos de error de PoYo.

Lista de comprobación antes de publicar

  • Mantén POYO_API_KEY en el servidor; nunca la incluyas en código de navegador o móvil.
  • Elimina temperature y top_p de todas las rutas de solicitud a GPT-6.2, incluidas las funciones auxiliares compartidas.
  • Define siempre max_output_tokens (o max_tokens) y deja espacio para los tokens de razonamiento dentro de ese límite.
  • Registra status / finish_reason y el bloque usage completo junto a tu propio ID de solicitud, para que las respuestas truncadas y los picos de coste sean visibles.
  • Pon el contexto largo y estable en el primer mensaje developer y la pregunta variable al final, lo que da a la caché de prompts la oportunidad de aplicarse.
  • Fija el ID de modelo en la configuración, para poder cambiar entre gpt-6.2-sol y gpt-6.2-astra sin un despliegue.

Para herramientas, streaming de llamadas a herramientas y caché en sesiones largas de agentes, sigue con GPT-6.2 API para agentes de programación.

Preguntas frecuentes

¿Cómo llamo a la GPT-6.2 API en Python?

Usa el SDK de OpenAI con base_url="https://api.poyo.ai/v1", tu clave de PoYo y model="gpt-6.2-sol" o "gpt-6.2-astra" en client.responses.create.

¿La GPT-6.2 API admite streaming?

Sí, en ambos endpoints. Define stream: true; Responses envía eventos tipados como response.output_text.delta y Chat Completions envía eventos chat.completion.chunk. Ambos terminan con data: [DONE].

¿Cómo configuro el esfuerzo de razonamiento de la GPT-6.2 API?

Envía "reasoning": {"effort": "medium"} en /v1/responses. OpenAI recomienda empezar con medium y rechaza none.

¿Por qué falla mi solicitud a la GPT-6.2 API con temperature?

OpenAI indica que se omitan temperature y top_p en GPT-6.2. Elimínalos y controla la longitud de la salida con max_output_tokens o max_tokens.

¿Cómo envío una imagen a la GPT-6.2 API?

Usa /v1/responses con un bloque input_image (URL o Data URI) después de un bloque input_text. El esquema de Chat Completions de PoYo solo documenta contenido como cadena.

Share: