Cómo usar la API de GPT-6.1 Terra

GPT-6.1 Terra está disponible en la API de OpenAI como gpt-6.1-terra, desde el 26 de octubre de 2026. Funciona con la API de Responses, Chat Completions y Batch, cuesta $1 por millón de tokens de entrada y $5 por millón de tokens de salida, y acepta hasta 922.000 tokens de entrada y 128.000 tokens de salida. Si ya llamas a GPT-5.6 Terra, el cambio es en su mayor parte una modificación de una sola línea del modelo, con algunos ajustes que conviene revisar primero.

Esta guía cubre cómo obtener una clave, tu primera petición en curl, Python y Node, los seis niveles de esfuerzo de razonamiento, el uso de ordenador y otras herramientas, los controles de coste y qué probar cuando migres desde gpt-5.6-terra. Para ver la descripción general del modelo, consulta qué es GPT-6.1 Terra.

Qué admite la API

Fuente: la página del modelo GPT-6.1 Terra de OpenAI. Las herramientas alojadas necesitan la API de Responses, así que úsala para trabajo nuevo.

Paso 1: obtén una clave de API

Crea una clave en el panel de la plataforma de OpenAI y añade facturación. No hay nivel gratuito para Terra: un plan ChatGPT Plus o Pro te da Terra dentro de ChatGPT Work y Codex, pero no una clave de API. Nuestra guía sobre si GPT-6.1 Terra es gratis explica la diferencia.

Expórtala para que los ejemplos siguientes puedan leerla:

export OPENAI_API_KEY="sk-..."

Los límites de velocidad dependen de tu nivel de uso. La página del modelo indica 5.000 peticiones y 1 millón de tokens por minuto en el nivel Build, 10.000 y 4 millones en Launch, y 15.000 y 40 millones en Grow.

Paso 2: envía tu primera petición

Con curl, contra la API de Responses:

curl https://api.openai.com/v1/responses \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-6.1-terra",
    "reasoning": { "effort": "low" },
    "input": "Summarize the difference between PUT and PATCH in two sentences."
  }'

En Python con el SDK oficial:

from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-6.1-terra",
    reasoning={"effort": "low"},
    input="Summarize the difference between PUT and PATCH in two sentences.",
)

print(response.output_text)
print(response.usage)

En Node:

import OpenAI from "openai";

const client = new OpenAI();

const response = await client.responses.create({
  model: "gpt-6.1-terra",
  reasoning: { effort: "low" },
  input: "Summarize the difference between PUT and PATCH in two sentences.",
});

console.log(response.output_text);
console.log(response.usage);

Imprime usage desde el principio. Te indica los tokens de entrada, en caché y de salida, y los tokens de razonamiento se facturan como salida.

Paso 3: elige un esfuerzo de razonamiento

Terra admite seis niveles de esfuerzo. El predeterminado es medium.

Dos puntos destacan.

none es compatible. GPT-6.1 Sol lo eliminó, así que esta es una de las diferencias prácticas entre ambos. Un desarrollador en el foro de la comunidad de OpenAI informa de que con reasoning.effort: "none", Terra vuelve a aceptar temperature y top_p. Para un pipeline que etiqueta o extrae datos en volumen, none te da el menor coste por llamada y una salida repetible.

El esfuerzo bajo es el que más mejoró. En la prueba interna de factualidad de OpenAI, la tasa de error de Terra con esfuerzo bajo cayó del 53,6% en GPT-5.6 Terra al 16,7%. Artificial Analysis también midió mayores ganancias respecto a GPT-5.6 Terra en niveles de esfuerzo bajos (de 7 a 13 puntos) que en max (6 puntos). Si ejecutabas GPT-5.6 Terra en high para obtener una calidad aceptable, prueba low o medium en 6.1 Terra antes de asumir que necesitas el mismo ajuste.

Paso 4: usa herramientas, incluido el uso de ordenador

OpenAI presentó este lanzamiento en torno a «uso de ordenador rápido y capaz a un precio más bajo». El uso de ordenador, la búsqueda web, la búsqueda de archivos y las demás herramientas alojadas están disponibles en la API de Responses. Una llamada de búsqueda web tiene este aspecto:

response = client.responses.create(
    model="gpt-6.1-terra",
    reasoning={"effort": "low"},
    tools=[{"type": "web_search"}],
    input="What changed in the latest OpenAPI Specification release?",
)
print(response.output_text)

La llamada a funciones y las salidas estructuradas funcionan igual que en otros modelos GPT-6: define tus esquemas de funciones en tools, o pasa un esquema JSON en el ajuste de formato de texto, y valida lo que devuelve. Para ver con más detalle el uso de ordenador contra una aplicación real, nuestra guía de uso de ordenador de GPT-6 Astra también se aplica a Terra, a una décima parte del precio por token de Astra.

Paso 5: controla el coste

Las tarifas de Terra ya son bajas, y cuatro ajustes las reducen aún más:

• La caché de prompts es automática. La entrada en caché cuesta $0,05 por millón frente a $1 para la entrada nueva. Mantén el contenido estable (prompt de sistema, esquemas de herramientas, documentos de referencia) al principio del prompt. Las escrituras de caché cuestan $1,25 por millón para 30 minutos de retención, o $2,50 para 12 horas. Consulta nuestra guía de caché de prompts de GPT-6.
• Batch reduce a la mitad todas las tarifas para trabajos asíncronos: $0,50 de entrada, $2,50 de salida. Nuestra guía de la API Batch de OpenAI muestra el flujo completo.
• Flex ofrece la misma tarifa a la mitad en peticiones normales con service_tier: "flex", a cambio de respuestas más lentas y 429 ocasionales.
• La línea de 272K. Los prompts por encima de 272K tokens de entrada facturan toda la petición a 2x las tarifas de entrada y de caché, y 1,5x las de salida. Si estás cerca, recorta el contexto recuperado en lugar de cruzarla.

El modo rápido va en la dirección contraria: 2x la tarifa estándar ($2 de entrada, $10 de salida) para obtener respuestas más rápidas. La guía de precios de GPT-6.1 Terra tiene todas las tarifas en una sola tabla.

Migrar desde gpt-5.6-terra

El cambio del ID del modelo es una línea. Estas son las cosas que hay que revisar en torno a él:

1. Precio. La entrada baja de $2 a $1, la entrada en caché de $0,20 a $0,05, la salida de $12 a $5. Actualiza cualquier panel de costes o alerta de presupuesto que fije las tarifas en el código.
2. Ajuste de esfuerzo. Vuelve a probar con un esfuerzo más bajo. La calidad en low es la que más cambió.
3. Fecha de corte de conocimiento. La de Terra es el 1 de junio de 2026. Los prompts que asumen un corte anterior, o las pruebas con respuestas esperadas sensibles a la fecha, pueden cambiar.
4. Longitud y formato de salida. Un modelo nuevo puede escribir respuestas más largas o más cortas. Revisa usage.output_tokens y cualquier analizador que espere un formato fijo; usa salidas estructuradas cuando la forma importe.
5. Velocidad. OpenAI dice que Terra termina las tareas más de 3 veces más rápido de media que Astra y GPT-6.1 Sol. Los tiempos de espera ajustados para modelos más lentos están bien, pero la lógica de reintentos y sondeos diseñada en torno a esperas largas puede que ahora sea un desperdicio.
6. Codex. Si tu equipo usa Codex, Terra necesita Codex CLI 0.159.0 o posterior: codex -m gpt-6.1-terra.

OpenAI no ha anunciado una fecha de retirada para GPT-5.6 Terra, así que puedes ejecutar ambos en paralelo mientras comparas.

Deja que tu agente de programación demuestre la migración con Apidog CLI

Los pasos 1 a 6 son exactamente el tipo de comprobaciones que no deberías hacer a mano. Apunta tu agente de programación a Apidog CLI y podrá construir la prueba, ejecutarla en ambos modelos y decirte qué cambió.

Configúralo una vez:

npm install -g apidog-cli@latest
apidog auth login --with-token <YOUR_TOKEN>
apidog skill install

Luego dale un solo prompt a Claude Code, Codex o Cursor:

In Apidog project <id>, add POST https://api.openai.com/v1/responses as an endpoint.
Create a test case that sends my production prompt with model {{MODEL}} and reasoning
effort low, and asserts: status 200, output_text not empty, output matches our JSON
schema, usage.output_tokens under 3000. Run it with MODEL=gpt-5.6-terra and again with
MODEL=gpt-6.1-terra against the <env> environment, then compare tokens and failures.

El agente lee cada esquema, valida su payload y ejecuta el caso dos veces:

apidog cli-schema get endpoint-create
apidog endpoint create --project <id> --file endpoint.json
apidog cli-schema validate test-case-create --file case.json
apidog test-case create --project <id> --file case.json
apidog run --test-case <caseId> --project <id> -e <envId> --env-var "MODEL=gpt-5.6-terra" -r cli,json
apidog run --test-case <caseId> --project <id> -e <envId> --env-var "MODEL=gpt-6.1-terra" -r cli,json

Guarda tu clave de OpenAI en el entorno de Apidog. Cuando la ejecución con Terra pase, añádela a CI con -r junit para que un cambio posterior de prompt o de modelo no pueda romper el contrato en silencio; nuestra guía de Apidog CLI para CI/CD tiene el archivo del pipeline, y Apidog CLI en Codex cubre la configuración de Codex.

Preguntas frecuentes

¿Cuál es el ID del modelo GPT-6.1 Terra? gpt-6.1-terra. Hay una única instantánea, y también es la predeterminada.

¿GPT-6.1 Terra funciona con Chat Completions? Sí. Admite Responses, Chat Completions y Batch. Las herramientas alojadas, como la búsqueda web y el uso de ordenador, necesitan la API de Responses.

¿Puedo establecer temperature en GPT-6.1 Terra? Un informe de la comunidad dice que sí con reasoning.effort: "none". En otros niveles de esfuerzo, consulta la página del modelo antes de enviar ajustes de muestreo.

¿GPT-6.1 Terra admite la API Realtime? No. Realtime, Live, Assistants y el ajuste fino no son compatibles.

¿Cuál es el límite de velocidad de GPT-6.1 Terra? Depende de tu nivel: desde 5.000 peticiones y 1 millón de tokens por minuto en Build hasta 15.000 y 40 millones en Grow.

Siguiente paso

Cambia el ID del modelo en un endpoint, vuelve a probar con un esfuerzo más bajo y deja que tu agente compare las dos ejecuciones con Apidog CLI. Si los números se mantienen, despliégalo. ¿No sabes si Terra o Sol encaja con tu carga de trabajo? Lee GPT-6.1 Terra vs GPT-6.1 Sol.