# GPT-6 Astra — /chat/completions

API de chat GPT-6 Astra (OpenAI), el modelo insignia de la familia GPT-6: ventana de contexto de 1 050 000 tokens, hasta 128 000 tokens de salida por petición, cinco niveles de razonamiento de low a max, entrada de imágenes, llamadas a herramientas y salida JSON. Compatible con el SDK de OpenAI y disponible también en /v1/responses.

**Endpoint:** `POST https://nezhagate.com/v1/chat/completions`

## Inicio rápido

Dos pasos: envía una petición y luego recibe la respuesta en streaming. Sustituye YOUR_API_KEY por tu clave y los comandos de abajo funcionan tal cual. El endpoint sigue el formato Chat Completions de OpenAI, así que al código de OpenAI que ya tengas solo hay que cambiarle `base_url` y `model`.

**Paso 1 · Envía una petición**

```
curl https://nezhagate.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-6-astra", "messages": [{"role": "user", "content": "Explica la fotosíntesis en una frase"}]}'
```

Respuesta (HTTP 200)

```
{
  "id": "chatcmpl-7f3c9a1e2b4d6f8a",
  "object": "chat.completion",
  "created": 1791281400,
  "model": "gpt-6-astra",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "La fotosíntesis es el proceso por el que las plantas usan la luz solar para transformar el dióxido de carbono y el agua en azúcar y liberar oxígeno.",
        "reasoning_content": "..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 18,
    "completion_tokens": 186,
    "total_tokens": 204,
    "prompt_tokens_details": {"cached_tokens": 0},
    "completion_tokens_details": {"reasoning_tokens": 144}
  }
}
```

`message.content` es la respuesta y `message.reasoning_content`, el razonamiento. `usage` recoge los tokens que se cobran en esta petición: los tokens de razonamiento forman parte de `completion_tokens` y se cobran al precio de salida.

**Paso 2 · Recibe la respuesta en streaming (recomendado)**

```
curl -N https://nezhagate.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-6-astra", "stream": true, "messages": [{"role": "user", "content": "Explica la fotosíntesis en una frase"}]}'
```

El streaming es SSE estándar: cada fragmento lleva texto en `choices[0].delta.content`, el último fragmento lleva `usage` y al final llega `data: [DONE]`. Usa streaming con respuestas largas y con modelos de razonamiento: una petición sin streaming se corta pasados unos 10 minutos.

**Python (SDK de OpenAI)**

```
from openai import OpenAI

client = OpenAI(base_url="https://nezhagate.com/v1", api_key="YOUR_API_KEY")

# 1. Una petición, una respuesta
resp = client.chat.completions.create(
    model="gpt-6-astra",
    messages=[{"role": "user", "content": "Explica la fotosíntesis en una frase"}],
)
print(resp.choices[0].message.content)

# 2. En streaming
stream = client.chat.completions.create(
    model="gpt-6-astra",
    messages=[{"role": "user", "content": "Explica la fotosíntesis en una frase"}],
    stream=True,
)
for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)
```

## Autenticación
```
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

## De un vistazo

| Ventana de contexto | 1 050 000 tokens |
| --- | --- |
| Salida máxima por petición | 128 000 tokens |
| Entrada | Texto, imágenes |
| Razonamiento | Según `reasoning_effort` (medium si no se envía); el resumen llega en `reasoning_content` |
| Llamadas a herramientas | Sí (formato `tools` de OpenAI) |
| Salida JSON | Sí (`response_format`) |
| Búsqueda web | Sí (`web_search: true`; la búsqueda en sí es gratis) |
| Endpoints | /v1/chat/completions · /v1/responses |
| Streaming | Sí (`stream: true`, SSE) |
| Forma de cobro | Por token: entrada, salida (razonamiento incluido) y aciertos de caché tienen cada uno su precio; los fallos no se cobran |

## Parámetros de la petición

El cuerpo JSON de `POST /v1/chat/completions`, igual que en la API Chat Completions de OpenAI. Estos son los parámetros habituales y lo que hace cada uno en este modelo:

| Parámetro | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| model | string | Sí | El ID del modelo: `gpt-6-astra`. |
| messages | array | Sí | La conversación: cada mensaje tiene un `role` (`system`, `user`, `assistant` o `tool`) y un `content`. `content` es una cadena o un array de partes `text` e `image_url` (entrada de imágenes; ver más abajo). En conversaciones de varios turnos, envía todo el historial en orden. |
| stream | boolean | No | Con `true`, la respuesta llega en streaming como SSE, con `usage` en el último fragmento. Por defecto es `false`. |
| max_tokens | integer | No | Este modelo no acepta un límite de salida: `max_tokens` / `max_completion_tokens` se ignoran sin dar error. Si quieres una respuesta corta, pídela en el prompt. |
| temperature / top_p | number | No | Este modelo no acepta parámetros de muestreo; se ignoran sin dar error. |
| reasoning_effort | string | No | Profundidad de razonamiento: low / medium / high / xhigh / max; por defecto, medium. Los niveles más altos razonan más y con más cuidado, pero tardan más y gastan más tokens de salida. El nivel también puede ir en el ID del modelo, por ejemplo `gpt-6-astra-high`. |
| tools / tool_choice | array / string | No | Llamadas a funciones en el formato estándar de OpenAI. Cuando el modelo llama a una función, devuelve `finish_reason: "tool_calls"` con `tool_calls`; ver más abajo. |
| response_format | object | No | `{"type": "json_object"}` hace que el modelo devuelva solo JSON válido; indica también en el prompt que quieres JSON y qué campos debe tener. |
| web_search | boolean | No | Con `true`, primero se hace una búsqueda web y los resultados se entregan al modelo como referencia; ver más abajo. |

`frequency_penalty` y `presence_penalty` también se ignoran. Los demás parámetros de OpenAI se pasan al modelo tal cual.

## Precio

Se cobra por token, a las tarifas vigentes de la tabla de abajo (por millón de tokens). Solo se cobran las peticiones que salen bien, según el uso real: los fallos, los tiempos de espera agotados y los rechazos no se cobran. 1 crédito = $0.005.

| Tipo | USD / 1M de tokens | Créditos / 1M de tokens |
| --- | --- | --- |
| Entrada | $3.00 | 600 |
| Salida (razonamiento incluido) | $15.00 | 3000 |
| Acierto de caché | $0.30 | 60 |

Por ejemplo, una petición con 2 000 tokens de entrada y 1 000 tokens de salida (razonamiento incluido) cuesta aproximadamente $0.021.

## Razonamiento

`reasoning_effort` acepta low / medium / high / xhigh / max; si no lo envías, la pasarela pide medium. Los niveles más altos razonan más y responden con más fiabilidad, pero tardan más y gastan más tokens de salida; para preguntas sencillas basta con low.

El resumen del razonamiento llega en `message.reasoning_content` (`delta.reasoning_content` en streaming). El nivel también puede ir en el ID del modelo (`gpt-6-astra-low`, `gpt-6-astra-high` o `gpt-6-astra-xhigh`), con el mismo efecto, y se cobra como `gpt-6-astra`.

En /v1/responses, la profundidad va en `reasoning.effort`, y solo se devuelve un resumen si envías tú mismo `reasoning.summary` (la pasarela no lo añade).

Los tokens de razonamiento forman parte de `usage.completion_tokens` y se cobran al precio de salida (algunos modelos los desglosan además en `completion_tokens_details.reasoning_tokens`).

## Caché de prompts

No hace falta ningún parámetro: el proveedor del modelo puede guardar en caché automáticamente un prefijo largo que se repite (el mismo prompt de sistema, los turnos anteriores de una conversación), y la parte en caché se cobra al precio de caché, más bajo. Si se guarda en caché y cuánto lo decide el proveedor; pon al principio de los mensajes lo que nunca cambia para conseguir más aciertos.

El número de tokens en caché llega en `usage.prompt_tokens_details.cached_tokens`; esa parte se cobra al precio de acierto de caché y el resto de la entrada, al precio de entrada.

## Entrada de imágenes

Pon una parte `image_url` en el array `content`. Lo recomendado es un data URI en base64 (`data:image/png;base64,...`), que todas las líneas pueden leer; un enlace público a una imagen tiene que descargarlo la línea, y alguna línea puede no conseguirlo o agotar el tiempo de espera. Las imágenes cuentan como tokens de entrada según las reglas del proveedor.

```
curl https://nezhagate.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-6-astra", "messages": [{"role": "user", "content": [{"type": "text", "text": "¿Qué hay en esta imagen?"}, {"type": "image_url", "image_url": {"url": "data:image/png;base64,iVBORw0KGgo..."}}]}]}'
```

## Llamadas a herramientas (function calling)

Describe tus funciones en `tools` con JSON Schema. Cuando el modelo decide llamar a una, devuelve `finish_reason: "tool_calls"` con el nombre de la función y los argumentos (una cadena JSON) en `message.tool_calls`.

```
curl https://nezhagate.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-6-astra", "messages": [{"role": "user", "content": "¿Qué tiempo hace ahora en Shanghái?"}], "tools": [{"type": "function", "function": {"name": "get_weather", "description": "Current weather of a city", "parameters": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]}}}]}'
```

Ejecuta la función, añade el resultado como un mensaje `role: "tool"` con el `tool_call_id` correspondiente y vuelve a enviar la conversación; entonces el modelo dará su respuesta final. `tool_choice` acepta `auto`, `none`, `required` o una función concreta.

## La API Responses (/v1/responses)

Este modelo también está disponible en la API Responses de OpenAI, la que usan Codex y herramientas similares. Las peticiones y las respuestas siguen el formato Responses de OpenAI: la entrada va en `input` y la profundidad de razonamiento, en `reasoning.effort`.

```
curl https://nezhagate.com/v1/responses \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-6-astra", "input": "Explica la fotosíntesis en una frase", "reasoning": {"effort": "medium", "summary": "auto"}}'
```

Este endpoint no añade un nivel de razonamiento por defecto ni devuelve un resumen por su cuenta; si quieres uno, envía `"summary": "auto"` como arriba. Se cobra igual que el endpoint de chat; la búsqueda web solo está disponible en /v1/chat/completions.

## Búsqueda web

Añade `"web_search": true` a la petición (o una entrada `{"type": "web_search"}` en `tools`): la pasarela primero busca en la web en tiempo real según la conversación, entrega al modelo hasta 5 resultados con sus enlaces como referencia, y el modelo responde citando sus fuentes. La búsqueda en sí es gratis; el texto de referencia se cobra como tokens de entrada.

```
curl https://nezhagate.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-6-astra", "web_search": true, "messages": [{"role": "user", "content": "¿Cuáles son las noticias de tecnología más importantes de hoy?"}]}'
```

## Líneas y fiabilidad

- Cada modelo se sirve por varias líneas. Si una da error, agota el tiempo de espera o está ocupada, la pasarela pasa a la siguiente antes de devolver nada, así que no tienes que reintentar y nunca se cobra dos veces.

- Cuando un streaming empieza a enviar datos, ya no cambia de línea: si se corta a medias, se cobra el uso generado hasta ese momento (consulta [Facturación y reembolsos](https://nezhagate.com/es/docs/guide/billing)).

- Cuando todas las líneas están ocupadas, la pasarela devuelve 429 con `Retry-After`: espera esos segundos y reintenta. Las peticiones fallidas no se cobran. El estado de cada modelo aparece en la [página de estado](https://nezhagate.com/es/status).

## Errores y reembolsos

Los errores llegan como un objeto `error` (`message`, `type`, `code`, `param`); decide según el estado HTTP y `code`, nunca comparando el texto de `message`. Las peticiones fallidas no se cobran; la lista completa está en [Códigos de error](https://nezhagate.com/es/docs/guide/errors).

| HTTP | code | Causa | Qué hacer |
| --- | --- | --- | --- |
| 400 | invalid_messages / invalid_role / invalid_max_tokens | En una petición de chat, `messages` falta, está vacío o tiene un formato incorrecto, un `role` no es uno de los valores permitidos, o `max_tokens` no es un entero positivo. `param` indica el campo. | Corrige el campo que indica `param`. |
| 400 | model_not_found | El ID del modelo está mal escrito, falta `model`, o el modelo no se puede usar en este endpoint (por ejemplo, un modelo de chat en el endpoint de imágenes). | Usa un ID de modelo de `GET /v1/models` o de la [referencia de la API](https://nezhagate.com/es/docs/api). |
| 400 | max_tokens_too_small | Un modelo de razonamiento gastó todo `max_tokens` en razonar y no escribió ninguna respuesta (chat sin streaming). | Sube `max_tokens` y reintenta. |
| 4xx | invalid_request | El proveedor del modelo rechazó la petición (por ejemplo, por un contexto demasiado largo o un parámetro no admitido); el estado y `message` se transmiten tal como los envió el proveedor, y `code` es el valor del proveedor. | Modifica la petición según lo que indique `message`. |
| 401 | invalid_api_key | La clave no existe, se eliminó o está desactivada, o la cuenta está desactivada. | Revisa la clave en la página API Keys de la consola. |
| 402 | insufficient_quota | No hay saldo suficiente para retener el importe de esta petición. La pasarela retiene primero el coste máximo posible de la petición, así que una ráfaga de llamadas simultáneas también puede provocarlo. | Si se debe a una ráfaga, espera unos segundos y reintenta; si no, recarga. |
| 403 | permission_denied | El modelo no está en la lista de modelos permitidos de la clave. | Usa un modelo de la lista o edita la lista en la consola. |
| 429 | rate_limit_exceeded | Se superó el límite de peticiones por minuto configurado en esta clave (contado sobre los últimos 60 segundos). Sin cabecera `Retry-After`. | Espera unos segundos y reintenta, o sube el límite de la clave en la consola. |
| 429 | rate_limit_exceeded | Todas las líneas de este modelo están ocupadas y la petición no se envió. Solo en los endpoints de chat: los trabajos de imagen y vídeo nunca se rechazan, sino que esperan en cola. Los endpoints compatibles con OpenAI añaden `Retry-After`. | Espera los segundos que indica `Retry-After` y reintenta. |
| 502 | upstream_timeout | Una línea agotó el tiempo de espera, incluido el caso de tardar demasiado en enviar el primer token. | Reintenta; para respuestas largas, usa `stream: true`. |
| 502 | upstream_unavailable | Una línea falló o no está disponible por el momento. | Reintenta en breve. |
| 502 | upstream_busy | El proveedor del modelo está limitando las peticiones. Un 429 del proveedor nunca te llega como 429; en su lugar recibes este 502. | Reintenta en breve. |
| 502 | empty_completion | El proveedor del modelo devolvió un contenido vacío. No es una valoración de tu contenido. | Reintenta. |
| 503 | model_maintenance | El modelo está en mantenimiento y no acepta peticiones; mientras tanto, ningún otro modelo responde en su lugar. | Reintenta cuando termine el mantenimiento; consulta el [estado del servicio](https://nezhagate.com/es/status). |

Si un streaming falla después de empezar a enviar datos, el código de estado no cambia: el error llega como una línea de datos con `error`, o el streaming simplemente termina (sin `data: [DONE]`). Trátalo como interrumpido.