GPT-5.6 Terra API: capacidades, clave y conexión (2026)

GPT-5.6 es la familia de modelos que OpenAI presentó en julio de 2026, dividida en tres niveles: Sol, Terra y Luna. Sol apunta a tareas de gama alta, Terra busca el equilibrio entre capacidad y coste, y Luna cubre escenarios ligeros de alta concurrencia. Para la mayoría de los equipos, Terra es el nivel por el que conviene empezar: asume atención al cliente, procesamiento de documentos, asistentes de código y pasos intermedios de agentes, sin fallar tanto como el nivel ligero en tareas complejas ni obligar a pagar el coste del nivel superior en todas las peticiones.

Al empezar de verdad, los problemas suelen concentrarse en tres puntos: cómo se escribe el ID del modelo, de dónde se obtiene la clave y qué parámetros hay que cambiar en el SDK de OpenAI existente. Este artículo sigue ese orden y añade la facturación del contexto largo, la caché, el diagnóstico de errores y el control de costes.

Nota: OpenAI, GPT y ChatGPT son marcas de sus titulares; este artículo solo describe la conexión técnica. Las especificaciones, la longitud de contexto y las reglas de facturación figuran en la documentación oficial de OpenAI y en la página de precios de modelos; aquí no se fija un precio unitario.

1. Qué es GPT-5.6 Terra

El ID de modelo de GPT-5.6 Terra es gpt-5.6-terra. Es un modelo de conversación y razonamiento general, acepta texto e imágenes y devuelve texto. Sus especificaciones principales son:

Elemento	Información oficial
ID del modelo	`gpt-5.6-terra`
Ventana de contexto	1.050.000 tokens
Entrada máxima	922.000 tokens
Salida máxima	128.000 tokens
Entrada/salida	Texto, imágenes → texto
Corte de conocimiento	16 de febrero de 2026
Intensidad de razonamiento	De none a max; por defecto, medium
Interfaces principales	Chat Completions, Responses, Batch

Estas cifras dicen dos cosas. Primera: un contexto de un millón de tokens significa «que cabe», no «que conviene»; cuanto más larga es la entrada, más latencia y coste, y por encima de cierto umbral se activa facturación adicional. Segunda: el límite de salida de 128K sirve para informes largos, código extenso y extracción estructurada, pero conviene poner max_tokens o max_output_tokens como red de seguridad para evitar salidas sin límite.

Desde el punto de vista de la selección, Terra encaja en estas tareas:

Preguntas de atención al cliente, clasificación de tickets, respuestas a correos y comentarios;
Resúmenes y extracción de campos de contratos, informes y páginas web largas;
Explicación de código, generación de pruebas unitarias y primera criba en revisiones de código;
Planificación, selección de herramientas y organización de resultados en flujos de agentes;
Procesamiento por lotes sin conexión, como reescribir títulos de productos o etiquetar comentarios.

Si la tarea exige el máximo razonamiento en varios pasos, matemáticas complejas o refactorización de código muy difícil, conviene evaluar el nivel Sol; si solo es clasificación de textos cortos en gran volumen, Luna suele salir más rentable.

2. Contexto largo y caché: mira primero la facturación

La facturación de GPT-5.6 Terra no es «un precio unitario por todos los tokens». En las reglas oficiales, lo que más se pasa por alto es el recargo por contexto largo y la diferencia de la caché.

Situación de facturación	Regla oficial	Efecto real
Entrada normal	Se cobra al precio de entrada	El prompt de sistema, el historial y las definiciones de herramientas cuentan como entrada
Lectura de caché	Bastante por debajo de la entrada normal	Cuanto más estable sea el prefijo reutilizado, mayor el ahorro
Escritura de caché	Por encima de la entrada normal; OpenAI la indica como 1,25 veces el precio de entrada	Cachea solo lo que sabes que se reutilizará
Más de 272K de entrada	Toda la petición se cobra a 2 veces la entrada y 1,5 la salida	No se recarga solo el exceso: se aplica al total
Tokens de salida	Al precio de salida	Las respuestas y el código largos suelen costar más que la entrada

La clave aquí es «toda la petición». Cuando la entrada de una petición supera los 272K tokens, el multiplicador se aplica a toda la entrada y toda la salida de esa petición, no solo al tramo que excede el límite. Meter un documento de 300K tokens de golpe y dividirlo en dos peticiones de 150K pueden producir facturas totalmente distintas.

Por eso, para documentos largos conviene este orden:

Haz primero recuperación o resumen y mete en el contexto solo los pasajes relevantes.
Si hay que procesar el texto completo, divide por capítulos o límites de negocio y mantén cada lote por debajo de 272K de entrada.
Cuando haga falta agregar entre lotes, pide primero al modelo un resultado intermedio estructurado y haz una segunda ronda de fusión.
Activa la caché para prompts de sistema y definiciones de herramientas estables; no los reescribas en cada llamada.
Calcula con registros de uso reales, no con un «cuánto cuesta una llamada de media» improvisado.

Los precios unitarios, los multiplicadores de caché y las reglas de contexto largo figuran en precios de modelos y en la versión vigente de la documentación oficial.

3. Dos formas de obtener la API Key

Vía uno: conexión directa a la plataforma de OpenAI

Regístrate e inicia sesión en la plataforma para desarrolladores de OpenAI y completa la configuración de organización, proyecto y facturación.
Crea una clave en la página API Keys y nómbrala por proyecto o entorno, por ejemplo prod-customer-service.
Confirma el saldo del proyecto, los límites de tasa y el permiso del modelo gpt-5.6-terra.
Guarda la clave en una variable de entorno del servidor o en un gestor de secretos; no la pongas en el código frontend ni en Git.

La Base URL directa es https://api.openai.com/v1. La ventaja es que la facturación es clara y el modelo está disponible en cuanto se publica; el coste es que necesitas un método de pago internacional disponible, acceso de red estable y gestionar por tu cuenta el tipo de cambio y la factura.

Vía dos: pasarela de IA de ZSQH

Después de registrarte en la pasarela de IA de ZSQH, crea una clave y usa la misma para llamar a varios modelos habilitados, con la facturación y el consumo centralizados en un solo panel. La pasarela ofrece una entrada compatible con OpenAI y su Base URL es https://ai.zhongshangqihang.com/v1; normalmente solo hay que cambiar tres cosas en el SDK de OpenAI existente: base_url, api_key y model.

Esta vía encaja en equipos que necesitan pago local, factura en yuanes y varios modelos a la vez. Qué modelos están habilitados y cómo se escribe cada nombre se consulta en la página de precios de modelos.

4. Base URL y compatibilidad

Elemento	Conexión directa a OpenAI	Pasarela ZSQH
Base URL	`https://api.openai.com/v1`	`https://ai.zhongshangqihang.com/v1`
API Key	Creada en la plataforma de OpenAI	Creada en la consola de la pasarela
Nombre del modelo	`gpt-5.6-terra`	Según la página de precios del sitio
SDK	SDK de OpenAI	SDK de OpenAI
Facturación y factura	Según las reglas de la plataforma	Factura en yuanes, según la política de la plataforma

El error de configuración más frecuente es que sobre o falte /v1 en la Base URL. Algunos SDK añaden /chat/completions automáticamente y otros exigen la ruta completa; mezclar la dirección oficial con la de la pasarela suele dar 401 o 404. Al diagnosticar, mira primero a qué dominio se envió realmente la petición y después revisa la ruta.

5. Llamada con curl

export ZSQH_API_KEY="sk-tu-clave"

curl "https://ai.zhongshangqihang.com/v1/chat/completions" \
  -H "Authorization: Bearer $ZSQH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6-terra",
    "messages": [
      {"role": "system", "content": "Eres un editor técnico. Responde de forma concreta y ejecutable."},
      {"role": "user", "content": "Explica en tres puntos el riesgo de coste de las peticiones con contexto largo"}
    ],
    "max_tokens": 800
  }'

Si devuelve model not found, comprueba primero que el nombre coincide con la página de precios; si devuelve un error de parámetros, revisa si esa interfaz acepta max_tokens, porque algunas nuevas usan max_output_tokens. Guíate por la documentación oficial o del sitio y no copies tutoriales antiguos.

6. Llamada con Python

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["ZSQH_API_KEY"],
    base_url="https://ai.zhongshangqihang.com/v1",
)

resp = client.chat.completions.create(
    model="gpt-5.6-terra",  # según la página de precios del sitio
    messages=[
        {"role": "system", "content": "Eres un asistente de revisión de contratos; devuelve solo JSON."},
        {"role": "user", "content": "Extrae los hitos de pago, los importes y las penalizaciones por incumplimiento."},
    ],
    response_format={"type": "json_object"},
    max_tokens=1200,
)

print(resp.choices[0].message.content)

Dos recomendaciones prácticas: primera, la salida estructurada necesita una validación de respaldo en el código; no supongas que el modelo siempre devolverá JSON válido. Segunda, si el modelo o la pasarela rechazan algún parámetro de muestreo, quítalo y vuelve a intentarlo; el soporte exacto figura en la documentación oficial.

7. Lista de control de costes

Elige el nivel según la tarea: clasificación, extracción y reescritura simples en el nivel ligero; producción diaria con Terra; razonamiento muy difícil con Sol.
Controla el prefijo de entrada: deja prompts de sistema, definiciones de herramientas y bases de conocimiento fijas al principio y mantenlos estables para acertar en caché.
Divide las peticiones largas: cuando una entrada se acerque a 272K, sepárala en lotes para no activar el multiplicador de contexto largo en toda la petición.
Limita la salida: fija max_tokens y pide primero la conclusión y luego los detalles para reducir texto largo inútil.
Usa Batch para tareas offline: los procesos por lotes que no necesitan respuesta en tiempo real deberían ir por la interfaz Batch, que suele tener descuento.
Separa claves por proyecto: una clave por línea de negocio, con límite de gasto y alertas, para cortar a tiempo las llamadas anómalas.
Registra el consumo: guarda al menos el ID de petición, el modelo, los tokens de entrada y salida, los aciertos de caché y la latencia, y revísalo cada semana.

El objetivo del control de costes no es «gastar poco», sino «verlo claro». Sin registros de uso no se puede saber si la factura subió por el contexto largo, por los reintentos o por salidas inútiles.

8. Errores habituales

Error	Causa habitual	Solución
`401 Unauthorized`	Clave incorrecta, sin Bearer o clave eliminada	Vuelve a copiar la clave y revisa la cabecera
`404 Not Found`	Falta o sobra `/v1` en la Base URL	Escribe la dirección según la documentación
`model not found`	Nombre de modelo incorrecto o no habilitado	Copia el nombre desde la página de precios
`400 Bad Request`	Parámetro no admitido o formato incorrecto	Elimina los parámetros sospechosos y revisa el JSON
`429 Too Many Requests`	Concurrencia o frecuencia excedida	Baja la concurrencia y reintenta con retroceso exponencial
`context_length_exceeded`	La entrada supera el contexto máximo	Divide en lotes, recupera o resume
`insufficient_quota`	Saldo insuficiente o cuota agotada	Recarga o cambia de clave

El orden de diagnóstico debería empezar por la autenticación: valida la clave con la petición mínima, después el nombre del modelo y solo entonces sospecha de la red o de los parámetros. Así evitas cambiar código una y otra vez en la dirección equivocada.

Preguntas frecuentes

¿Cómo elegir entre GPT-5.6 Terra y GPT-5.5?

Terra es el nivel equilibrado de la serie GPT-5.6, con un corte de conocimiento más reciente, y encaja en la mayoría de las tareas diarias de producción; GPT-5.5 sigue siendo válido para razonamiento difícil y agentes complejos ya existentes. Lo más seguro es hacer un A/B con tu propio conjunto de evaluación y enrutar por tarea, en lugar de mirar solo la tabla de especificaciones.

¿Terra admite entrada de imágenes?

Sí. La especificación oficial es entrada de texto e imágenes y salida de texto, adecuada para reconocer recibos, entender capturas y responder preguntas sobre imágenes. Las imágenes consumen tokens de entrada, así que estima el coste antes de procesar en lote.

¿Se puede meter un libro entero en el contexto de 1,05 millones de tokens?

Técnicamente sí, pero no conviene hacerlo por defecto. Superar los 272K de entrada activa el multiplicador de contexto largo y la latencia sube de forma notable. Es más económico recuperar los capítulos relevantes, resumirlos por partes y luego agregar.

¿Qué hay que cambiar en un SDK de OpenAI existente?

Normalmente solo tres cosas: base_url apunta a la pasarela, api_key se sustituye por la clave de la pasarela y model se escribe con el nombre de la página de precios. La estructura de mensajes no cambia, pero el soporte de parámetros nuevos depende de la documentación oficial o del sitio.

¿Por qué la misma petición se cobra distinto dos veces?

Influyen la longitud de entrada y salida, si acierta la caché y si se activa el multiplicador de contexto largo. Cruza el ID de petición con los registros de uso para localizar la diferencia.

Siguiente paso

Primero regístrate en la pasarela de IA de ZSQH, crea una clave de prueba, ejecuta la petición mínima con curl y después intégrala en el código de negocio. Los nombres de modelo, el contexto y los precios figuran en precios de modelos.

Lecturas relacionadas: