Tutorial de la API GPT-6 Astra: Crea tu primera aplicación con la API de Respuestas

La forma más limpia de construir con GPT-6 Astra es la API de Respuestas. OpenAI admite Completions de Chat para solicitudes básicas de Astra, pero su guía actual del modelo indica que la llamada a herramientas requiere Respuestas. Esto convierte a Respuestas en la opción práctica por defecto para nuevas aplicaciones que necesiten búsqueda web o de archivos, funciones personalizadas, uso de computadora, generación de imágenes, salida estructurada o estado de múltiples turnos.

Este tutorial construye un pequeño “revisor de briefs de producción”. Acepta un brief creativo, identifica decisiones faltantes y devuelve un resultado estructurado que otra interfaz puede usar. La misma arquitectura funciona para asistentes de investigación, herramientas de codificación y flujos de trabajo de documentos.

Los ejemplos son intencionalmente limitados. La autenticación, los lanzamientos de SDK y el acceso al producto pueden cambiar, por lo que debe comparar los detalles de implementación con la documentación oficial de la API de Responses antes de la implementación.

Lo Que Necesitas Antes de Empezar

Necesitas un proyecto de API de OpenAI con facturación y acceso a gpt-6-astra. Las suscripciones de ChatGPT y la facturación de la API son independientes. La página del modelo Astra actualmente no lista soporte de API en el nivel gratuito.

Para Node.js, instala el SDK actual de OpenAI a través de tu gestor de paquetes habitual y coloca la clave API en una variable de entorno del lado del servidor. No la incrustes en el código del navegador ni la subas a un repositorio.

Nuestra primera solicitud necesita solo tres campos:

{"model": "deepseek-ai/DeepSeek-V3", "messages": [{"role": "system", "content": "You are a helpful assistant."}], "stream": false}

import OpenAI from "openai";

const client = new OpenAI();

const response = await client.responses.create({ model: "gpt-6-astra", razonamiento: { esfuerzo: "medio" }, "Revisa este resumen: Un mensajero encuentra una carta dirigida al mañana." });

console.log(response.output_text);

`output_text` es una propiedad de conveniencia para el texto recopilado de la respuesta. Una aplicación en producción también debería inspeccionar el estado de la respuesta, los errores y el uso, en lugar de asumir que cada llamada se completó normalmente.

## Comprender la forma de la solicitud

### `model`

Usa el identificador exacto del modelo `gpt-6-astra`. No adivines un alias o una instantánea con fecha que no esté listada en el catálogo oficial.

### `input`

La entrada puede ser una cadena o contenido estructurado. Astra acepta entrada de texto e imágenes. Produce texto de forma nativa; el audio y el video no son modalidades de modelo compatibles en la página actual del modelo.

### `razonamiento`

El campo `reasoning.effort` controla cuánto razonamiento aplica el modelo. Astra admite `low`, `medium`, `high`, `xhigh` y `max`. No admite `none`; OpenAI dice que esa configuración devuelve HTTP 400.

Comience con un nivel medio para la evaluación. Compare configuraciones más bajas y más altas en las mismas tareas en lugar de asumir que más razonamiento siempre es económico.

> **Usa el resultado en etapas posteriores:** Una vez que tu aplicación genere un guion aprobado o un resumen de toma, los creadores pueden transferirlo a [Elser AI](https://www.elser.ai/) para el diseño de personajes, storyboarding, generación de escenas y edición. Se trata de una transferencia de flujo de trabajo, no de una integración nativa.

## Dale al modelo un contrato de salida real

Un párrafo simple es difícil de validar. Nuestro revisor debe devolver un objeto estable que contenga un resumen, decisiones faltantes y si el resumen está listo para la elaboración del guion gráfico.

Con Salidas Estructuradas, define un esquema JSON bajo `text.format`:

```javascript
{"model": "deepseek-ai/DeepSeek-V3", "messages": [{"role": "system", "content": "You are a helpful assistant."}], "stream": false}

const briefSchema = { type: "objeto", propiedades: { logline: { type: "string" }, missing_decisions: { type: "array", items: { type: "string" } }, ready_for_storyboard: { type: "boolean" } }, requerido: ["línea de registro", "missing_decisions", "ready_for_storyboard"], additionalProperties: false };

const response = await client.responses.create({ model: "gpt-6-astra", razonamiento: { esfuerzo: "medio" }, instrucciones: [ "Revisar los resúmenes creativos para verificar que estén listos para la producción.", "No inventes decisiones faltantes sobre presupuesto, derechos, audiencia o duración." ].join(" "), input: "Un mensajero encuentra una carta dirigida al mañana.", texto: { formato: { type: "json_schema", name: "breve_revisión", strict: true, schema: briefSchema } } });

const review = JSON.parse(response.output_text);

La validez del esquema no garantiza la calidad factual o creativa. Valide también las reglas comerciales requeridas. Por ejemplo, `ready_for_storyboard` debe ser falso cuando falten restricciones de tiempo de ejecución, audiencia o derechos.

## Agregar una Función Personalizada

Supongamos que los registros de personajes aprobados viven en tu base de datos. Permite que Astra solicite el registro en lugar de pegar todo el catálogo en cada indicación.

Conceptualmente, define una herramienta de función con un nombre, descripción, esquema de parámetros estrictos y tu lógica de ejecución. Cuando la respuesta contenga una llamada a función:

1. analizar y validar sus argumentos;
2. autorizar el acceso para el usuario actual;
3. ejecuta la función en tu aplicación;
4. devuelve un `function_call_output` usando el `call_id` original;
5. continúa la conversación de Respuestas.

El modelo no ejecuta tu función de base de datos. Tu código lo hace. Las descripciones de herramientas guían la selección; no son un límite de seguridad.

GPT-6 Astra también admite la llamada asíncrona de herramientas. Configurar `async: true` en una función elegible o herramienta personalizada permite que el modelo continúe con trabajo independiente mientras tu aplicación ejecuta la herramienta. Cuando el trabajo finalice, envía su salida en una solicitud posterior de Respuestas con el ID de llamada original. Esto difiere del modo en segundo plano: la llamada asíncrona de herramientas cambia si el modelo espera un resultado de la herramienta, mientras que el modo en segundo plano se refiere a la generación de respuestas en sí.

## Mantener el Estado de Múltiples Turnos

Para un breve seguimiento, pase el ID de respuesta anterior:

```javascript
const first = await client.responses.create({
  model: "gpt-6-astra",
  razonamiento: { esfuerzo: "medio" },
  input: "Revisa este resumen de producción de seis tomas: ..."
});

const revised = await client.responses.create({
  model: "gpt-6-astra",
  previous_response_id: first.id,
  razonamiento: { esfuerzo: "medio" },
  input: "Revisa la reseña para un video vertical de 30 segundos."
});

Los documentos de OpenAI indican store: true y respuestas anteriores como una forma de preservar el estado. Las organizaciones con diferentes requisitos de retención deben revisar las opciones disponibles sin estado y de razonamiento cifrado en lugar de copiar un patrón de persistencia a ciegas.

No envíes historial de conversación no controlado para siempre. Los contextos largos aumentan el costo, pueden contener instrucciones obsoletas y pueden superar el umbral de precio más alto por encima de los 272,000 tokens de entrada.

Cambiar el Esfuerzo de Razonamiento a Mitad de Conversación

Astra admite elementos configuration_update en modo estándar de agente único. Pueden aumentar o disminuir el esfuerzo de razonamiento mientras preservan el prefijo de solicitud a nivel de solicitud para el almacenamiento en caché.

Por ejemplo, comience una revisión de rutina con poco esfuerzo, luego escale el análisis de fallos:

const next = await client.responses.create({
  model: "gpt-6-astra",
  previous_response_id: first.id,
  razonamiento: { esfuerzo: "bajo" },
  input: [
    { type: "configuration_update", reasoning: { effort: "high" } },
    {
      role: "usuario",
      content: "Encuentra fallos de continuidad y propón las reparaciones más pequeñas."
    }
  ]
});

La guía oficial de razonamiento señala límites de compatibilidad: las actualizaciones de configuración son solo para Astra, se aplican en modo estándar de un solo agente, no pueden ser adyacentes en el historial y no se combinan con compactación o truncamiento automáticos. Lea la guía actual antes de adoptarlas de manera generalizada.

Añade imágenes con cuidado

La entrada de imagen puede ayudar al revisor a comparar un fotograma del guion gráfico con una descripción del personaje. Proporcione texto y un elemento input_image en la entrada estructurada. Solicite al modelo que separe las observaciones visibles de las inferencias.

Por ejemplo, solicite una lista de verificación que cubra el peinado, el lado del accesorio, la paleta y la construcción del disfraz. No le pida que infiera la personalidad a partir de la apariencia ni trate los pequeños detalles visuales como ciertos cuando la imagen no esté clara.

Si el resultado está destinado a producción, permita que una persona apruebe las reglas de identidad antes de guardarlas en Elser AI. El análisis visual puede reducir el trabajo de revisión; no lo reemplaza.

Manejar Errores y Respuestas Incompletas

El código de producción debería manejar más que solo fallos de red. Verifique:

• errores de autenticación y de acceso al proyecto;
• HTTP 400 por campos no admitidos o valores de razonamiento;
• límites de tasa;
• respuestas incompletas causadas por límites de salida;
• fallos de validación de argumentos de llamada a herramientas;
• trabajos externos caducados;
• salida válida según el esquema pero semánticamente inutilizable;
• cancelación por parte del usuario y límites de tiempo.

Usa reintentos limitados con retroceso para fallos genuinamente transitorios. No reintentes solicitudes inválidas sin cambios. Registra identificadores de solicitud, modelo, latencia, uso de tokens y resultados de herramientas sin almacenar contenido sensible innecesariamente.

Parámetros a Evitar con Astra

La guía actual de migración a Astra de OpenAI indica que se deben eliminar temperature, top_p y top_logprobs. Las solicitudes de Chat Completions también deben eliminar logprobs, mientras que las solicitudes de Responses deben omitir message.output_text.logprobs de include.

Los ejemplos copiados de referencias genéricas de API pueden mostrar campos aceptados por otros modelos. La guía específica del modelo rige tu solicitud de Astra.

Prueba la Aplicación, No Solo el Modelo

Crea un pequeño conjunto de evaluación que contenga:

• resúmenes completos;
• briefs sin tiempo de ejecución o audiencia faltantes;
• detalles de personaje contradictorios;
• una instrucción maliciosa dentro de un documento subido;
• una imagen con detalles ambiguos;
• una llamada a función que debería ser denegada;
• un resumen muy largo cerca de tu límite de costos.

Mida la aceptación en primera instancia, la validez de la salida estructurada, las afirmaciones no respaldadas, el éxito de la herramienta, la latencia, el costo de tokens y el tiempo de corrección humana. Realice pruebas de equipo rojo en el ciclo completo de la herramienta, porque los permisos y los datos externos crean riesgos que el mensaje de texto base no puede resolver.

Desde la salida de la API hasta la animación

El revisor de muestras crea un límite claro entre el razonamiento y la representación. Puede devolver una sinopsis validada, decisiones faltantes y preparación para el guion gráfico. Un servicio de producción podría extender el esquema con bloqueos de personajes, tomas temporizadas y reglas de continuidad.

Después de la aprobación, usa Elser AI para construir el personaje y el guion gráfico, generar activos de escena, agregar voz o música y ensamblar el corte final. Mantén versionado el resultado de la API para que los cambios de producción sigan siendo rastreables.

Preguntas Frecuentes

¿Qué API debería usar para GPT-6 Astra?

Usa la API de Responses para nuevos proyectos y para llamadas a herramientas. Las solicitudes básicas de Chat Completions son compatibles, pero la llamada a herramientas de Astra requiere Responses.

¿Cuál es el ID del modelo GPT-6 Astra?

Usa gpt-6-astra.

¿Puedo configurar la temperatura para GPT-6 Astra?

La guía de migración actual de OpenAI dice que se deben eliminar temperature, top_p y top_logprobs.

¿Admite GPT-6 Astra la salida en JSON?

Sí. Las salidas estructuradas son compatibles. Defina y valide un esquema JSON apropiado en lugar de confiar en una instrucción de formato informal.

¿Puede GPT-6 Astra llamar a las funciones de mi aplicación?

Sí. El modelo puede solicitar una llamada a función, pero tu aplicación valida los permisos, ejecuta el código y devuelve el resultado.

¿Está GPT-6 Astra disponible en el nivel gratuito de la API?

La página del modelo actual lista el nivel Gratuito como no compatible.

Conclusión

Una aplicación confiable de GPT-6 Astra comienza con la API de Respuestas, una configuración de razonamiento explícito y un contrato de salida que tu software pueda validar. Agrega herramientas solo con autorización y observabilidad, mantén el estado de la conversación acotado y prueba los fallos con tanto cuidado como las entradas ideales.

Para sistemas creativos, usa Astra para que el briefing sea preciso y revisable. Luego transfiere el guion aceptado y los datos de tomas a Elser AI para la producción visual.

Fuentes Oficiales

• Página del modelo GPT-6 Astra
• Guía del modelo GPT-6 Astra
• Migrar a la API de Respuestas
• Llamada asíncrona a herramientas
• Modelos de razonamiento

Detalles técnicos verificados contra la documentación oficial de OpenAI el 4 de septiembre de 2026. Pruebe los ejemplos con el SDK actual antes de usarlos en producción.