# Gemini 4 Argon — /chat/completions

Gemini 4 Argon Beta admite conversación de texto, streaming y tres niveles de razonamiento: Low / Medium / High; Low es el predeterminado. Compatible con el SDK de OpenAI. El razonamiento se cobra como salida.

**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": "gemini-4-argon", "messages": [{"role": "user", "content": "Explica la fotosíntesis en una frase"}]}'
```

Respuesta (HTTP 200)

```
{
  "id": "chatcmpl-7f3c9a1e2b4d6f8a",
  "object": "chat.completion",
  "created": 1791281400,
  "model": "gemini-4-argon",
  "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": "gemini-4-argon", "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="gemini-4-argon",
    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="gemini-4-argon",
    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

| Contexto compartido por entrada y salida | Aprox. 1 millón tokens |
| --- | --- |
| Entrada | Texto |
| Razonamiento | Elige `low / medium / high`; predeterminado: `low`. Todos usan las mismas tarifas por token. |
| Llamadas a herramientas | Sin garantía: `tools` puede ignorarse y el modelo responde directamente |
| Búsqueda web | Sí (`web_search: true`; la búsqueda en sí es gratis) |
| Endpoints | /v1/chat/completions |
| 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: `gemini-4-argon`. |
| messages | array | Sí | La conversación: cada mensaje tiene un `role` (`system`, `user`, `assistant` o `tool`) y un `content`. 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 | Longitud de salida solicitada, incluido el razonamiento. Esta Beta no garantiza un límite rígido. Limita la extensión en el prompt y divide las tareas para controlar el coste. |
| temperature / top_p | number | No | Se pueden enviar parámetros de muestreo; sus efectos no se han verificado por separado en esta Beta. |
| reasoning_effort | string | No | Elige `low / medium / high`; predeterminado: `low`. Todos usan las mismas tarifas por token. |
| 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. |

Empieza con los parámetros de esta página. No se promete aún el uso de herramientas, entrada multimodal ni modo JSON.

## 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 | $0.50 | 100 |
| Salida (razonamiento incluido) | $3.00 | 600 |
| Acierto de caché | $0.05 | 10 |

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

## Razonamiento

Usa `reasoning_effort` con `low`, `medium` o `high`; si se omite, se usa `low`.

El razonamiento visible se devuelve en `reasoning_content`. `usage.completion_tokens` incluye razonamiento y respuesta; no sumes el razonamiento una segunda vez.

Las tarifas son iguales en los tres niveles. Un esfuerzo mayor puede consumir más tokens de salida.

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`).

```
{
  "model": "gemini-4-argon",
  "messages": [{"role": "user", "content": "Explica la fotosíntesis en una frase"}],
  "reasoning_effort": "medium"
}
```

## Caché de prompts

Se admite caché implícita automática. Las entradas largas repetidas pueden acertar; los aciertos reales cuestan una décima parte de la entrada normal. Repetir no garantiza un acierto y no se ofrece creación de caché explícita.

`usage.prompt_tokens` es la entrada total. `usage.prompt_tokens_details.cached_tokens` es la parte de ese total servida desde caché. Solo los aciertos reales usan la tarifa de caché.

## Búsqueda web

El `web_search` opcional de la pasarela aporta texto recuperado al modelo. No implica búsqueda web nativa ni herramientas verificadas.

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

## Límites de la Beta

- Se verificaron texto, streaming y tres niveles de razonamiento. Herramientas, entrada multimodal y modo JSON siguen sin verificar.

- El contexto oficial es de aproximadamente un millón de tokens, compartido por entrada y salida. Se probó recuperación con entradas largas, pero no la ventana completa ni salida de un millón de tokens.

- Divide las tareas largas. `max_tokens` no es un límite rígido de presupuesto verificado. Las solicitudes fallidas no se cobran; las interrumpidas que produjeron salida se liquidan por uso real.

## 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.