# Grok 4.7 — /chat/completions

API de chat Grok 4.7 (xAI), modelo insignia de razonamiento que destaca en razonamiento complejo, programación y análisis de documentos largos. Siempre razona antes de responder, con el razonamiento en `reasoning_content`; entrada de imágenes, llamadas a herramientas y salida estructurada. Compatible con el SDK de OpenAI.

**Endpoint:** `POST https://kovapi.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://kovapi.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "grok-4.7", "messages": [{"role": "user", "content": "Explica la fotosíntesis en una frase"}]}'
```

Respuesta (HTTP 200)

```
{
  "id": "chatcmpl-7f3c9a1e2b4d6f8a",
  "object": "chat.completion",
  "created": 1791281400,
  "model": "grok-4.7",
  "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://kovapi.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "grok-4.7", "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://kovapi.com/v1", api_key="YOUR_API_KEY")

# 1. Una petición, una respuesta
resp = client.chat.completions.create(
    model="grok-4.7",
    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="grok-4.7",
    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

| Entrada | Texto, imágenes |
| --- | --- |
| Razonamiento | Siempre razona antes de responder; el razonamiento 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 |
| 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: `grok-4.7`. |
| 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 | Solo limita la respuesta visible; el razonamiento no cuenta para este límite (los tokens de razonamiento se siguen cobrando al precio de salida). |
| temperature / top_p | number | No | Parámetros de muestreo; se pasan al modelo tal cual (`temperature` va de 0 a 2). Puede que los modelos de razonamiento no los respeten. |
| reasoning_effort | string | No | No tiene efecto: este modelo siempre razona y decide cuánto. |
| 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. |
| stop | string / array | No | Este modelo no lo admite; si lo envías, recibes un 400. |

La pasarela elimina `presence_penalty`, `frequency_penalty` y `logit_bias` (este modelo no los admite; no da error). Los demás parámetros se pasan 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 | $0.30 | 60 |
| Salida (razonamiento incluido) | $0.90 | 180 |
| Acierto de caché | $0.075 | 15 |

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

## Razonamiento

Este modelo siempre razona antes de responder; el razonamiento llega en `message.reasoning_content` (`delta.reasoning_content` en streaming). No se puede desactivar, y `reasoning_effort` y `thinking` no tienen efecto.

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 siempre se puede leer; un enlace público a una imagen hay que descargarlo primero, y de vez en cuando no se consigue o agota el tiempo de espera. Las imágenes cuentan como tokens de entrada según las reglas del fabricante del modelo.

```
curl https://kovapi.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "grok-4.7", "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://kovapi.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "grok-4.7", "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.

## 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://kovapi.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "grok-4.7", "web_search": true, "messages": [{"role": "user", "content": "¿Cuáles son las noticias de tecnología más importantes de hoy?"}]}'
```

## Fiabilidad y reintentos automáticos

- Si una petición da error, agota el tiempo de espera o choca con el límite de capacidad, la pasarela la reintenta automáticamente 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 se reintenta automáticamente: si se corta a medias, se cobra el uso generado hasta ese momento (consulta [Facturación y reembolsos](https://docs.kovapi.com/es/guide/billing)).

- Cuando el modelo está al límite de su capacidad, 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://kovapi.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://docs.kovapi.com/es/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://docs.kovapi.com/es/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 | El modelo está al límite de su capacidad 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 | El proveedor 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 | El proveedor 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://kovapi.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.