> ## Documentation Index
> Fetch the complete documentation index at: https://docs.squarecloud.app/llms.txt
> Use this file to discover all available pages before exploring further.
# AI Gateway compatible con OpenAI (beta)
> Usa el modelo cubic de Square Cloud en tus productos con POST /v2/ai/chat/completions, compatible con OpenAI, con llamadas a herramientas y búsqueda web.
La clave de API de tu cuenta. Puedes encontrarla en la [configuración de tu cuenta](https://squarecloud.app/es/account/security).
Requiere una clave de API con el [scope](/es/api-reference/authentication#scopes) `ai:chat`.
El AI Gateway te permite usar el modelo de IA alojado por Square Cloud dentro de tus **propios** productos (chatbots, asistentes, automatizaciones) a través de un endpoint de chat completions **compatible con OpenAI**. Si tu código ya habla la API de OpenAI, también habla el AI Gateway: apunta el SDK a nuestra URL base, usa la clave de API de tu cuenta y define el modelo como `cubic`.
El AI Gateway está en **beta con acceso anticipado sin costo adicional**: durante la beta no se cobra nada más allá del presupuesto diario de tokens de IA de tu plan. Los límites y los planes con acceso pueden cambiar cuando termine la beta.
## Cómo conectarse
* **URL base:** `https://api.squarecloud.app/v2/ai`
* **Clave de API:** la clave de API de tu cuenta (la misma que usan la API de Square Cloud y la CLI, disponible en la [página de tu cuenta](https://squarecloud.app/es/account)). El encabezado `Authorization` se acepta con o sin el prefijo `Bearer `.
* **Modelo:** `cubic`, el modelo alojado por Square Cloud, el mismo que impulsa el asistente de IA del panel.
## Planes y límites
Cada solicitud descuenta sus tokens reales del **presupuesto diario de tokens de IA** de tu plan (el mismo presupuesto que usa el asistente del panel, que se reinicia a las 00:00 UTC). Standard y Pro también tienen un tope diario de solicitudes, y cada plan tiene una cuota diaria de uso justo en el gateway, dimensionada para un uso moderado (una protección para claves desatendidas, basada en lo que cuesta atender las solicitudes); ambos se reinician a la misma hora.
| Plan | Solicitudes por día | Cuota de uso justo | Ventana de contexto | Salida máxima | Solicitudes simultáneas | Intervalo entre solicitudes |
| - | - | - | - | - | - | - |
| Standard | 1.000 | base | 16.384 tokens | 4.096 | 1 | 5 s |
| Pro | 5.000 | base | 24.576 tokens | 6.144 | 1 | 2 s |
| Enterprise | ilimitadas | 5x la base | 32.768 tokens | 8.192 | 2 | ninguno |
Los planes Hobby (y las cuentas sin plan) no tienen acceso al AI Gateway: pasar a Standard o superior lo habilita.
## Contrato de la solicitud
Se acepta por compatibilidad con los SDKs; el gateway siempre responde como `cubic`.
Mensajes al estilo de OpenAI con los roles `system`, `user`, `assistant` y `tool`. El contenido debe ser un **string**: este endpoint es solo de texto, así que un array de varias partes (`image_url`, `input_audio`, `file`) se rechaza con `400 multimodal_not_supported`. Hasta **100 mensajes** por solicitud.
Se ajusta sin aviso al límite de salida de tu plan.
De 0 a 2.
Llamadas a funciones en el formato estándar de OpenAI, hasta **32 definiciones de herramientas**. Las llamadas a herramientas vuelven con `finish_reason: "tool_calls"`, y tú envías los resultados como mensajes con `role: "tool"`.
Valores estándar de `tool_choice` de OpenAI.
Los parámetros desconocidos se ignoran, con dos excepciones deliberadas: `audio` y un valor de `modalities` distinto de `["text"]` se **rechazan** en lugar de ignorarse, para que una solicitud de salida hablada nunca vuelva como texto en silencio.
**Entra texto, sale texto.** No se aceptan imágenes, audio ni archivos en ningún plan, y es una decisión de producto, no una carencia temporal. Envía texto y lee texto.
**Aún no compatible:** streaming (`stream: true` devuelve `400 stream_not_supported`).
### Búsqueda web integrada
El modelo decide por sí mismo buscar en la web cuando la conversación pide información actual o externa. Las búsquedas se ejecutan en el servidor y solo se devuelve la respuesta final, con las URLs de los resultados citadas. Si declaras tu propia herramienta llamada `web_search`, la tuya reemplaza a la integrada.
```javascript JavaScript (OpenAI SDK) theme={"system"}
import OpenAI from "openai";
const client = new OpenAI({
baseURL: "https://api.squarecloud.app/v2/ai",
apiKey: process.env.SQUARECLOUD_API_KEY,
});
const completion = await client.chat.completions.create({
model: "cubic",
messages: [
{ role: "system", content: "You are a helpful assistant." },
{ role: "user", content: "Explain what Square Cloud is in one sentence." },
],
});
console.log(completion.choices[0].message.content);
```
```python Python (OpenAI SDK) theme={"system"}
from openai import OpenAI
client = OpenAI(
base_url="https://api.squarecloud.app/v2/ai",
api_key="YOUR_API_KEY",
)
completion = client.chat.completions.create(
model="cubic",
messages=[
{"role": "system", "content": "You are a helpful assistant."},
{"role": "user", "content": "Explain what Square Cloud is in one sentence."},
],
)
print(completion.choices[0].message.content)
```
```bash cURL theme={"system"}
curl --request POST \
--url https://api.squarecloud.app/v2/ai/chat/completions \
--header 'Authorization: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"model": "cubic",
"messages": [
{ "role": "user", "content": "Explain what Square Cloud is in one sentence." }
]
}'
```
```json theme={"system"}
{
"id": "chatcmpl-9f2c1a7e4b3d8f6a0c5e2d1b",
"object": "chat.completion",
"created": 1754179200,
"model": "cubic",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "Square Cloud is a cloud platform that hosts your applications, bots, websites and databases with zero infrastructure setup."
},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 28,
"completion_tokens": 24,
"total_tokens": 52
}
}
```
## Errores
Todos los errores usan el formato de OpenAI `{ "error": { "message", "type", "param", "code" } }`, incluidos los de autenticación, scope, límite de tasa, cuerpo inválido, `500` y `503`, y el `code` siempre va en minúsculas.
| Estado | Código | Qué significa / qué hacer |
| - | - | - |
| 401 | `access_denied` | La clave de API falta, es inválida, fue revocada o expiró. |
| 403 | `upgrade_required` | El plan no tiene acceso al AI Gateway (Hobby o sin plan). Pasa a Standard o superior. |
| 403 | `missing_scope` | La clave de API no tiene el scope que necesita este endpoint. |
| 403 | `resource_not_allowed` | La clave de API está restringida a recursos que no incluyen esta solicitud. |
| 400 | `invalid_json_body` / `invalid_messages` / `invalid_tools` / `invalid_tool_choice` / `invalid_temperature` / `invalid_max_tokens` | Cuerpo de la solicitud mal formado: corrige el campo señalado. |
| 400 | `stream_not_supported` | Quita `stream: true`; el streaming aún no está disponible. |
| 400 | `multimodal_not_supported` | El endpoint es solo de texto. Envía el `content` de cada mensaje como string y elimina `audio` o cualquier `modalities` distinta de `["text"]`. |
| 400 | `context_length_exceeded` | Los mensajes más las definiciones de herramientas superan la ventana de contexto del plan. Acorta el historial o mejora tu plan. |
| 400 | `invalid_request` | El backend del modelo rechazó la solicitud: casi siempre es un error del protocolo de llamadas a herramientas (un mensaje `tool` que no responde a un `tool_calls` anterior, ids de llamada duplicados). |
| 413 | `payload_too_large` | El cuerpo de la solicitud supera lo que acepta este endpoint. Acorta el historial. |
| 429 | `concurrent_limit_reached` | Ya hay una solicitud en curso; espera a que termine (Enterprise permite 2 a la vez). |
| 429 | `rate_limit_exceeded` | Solicitudes enviadas más rápido que el intervalo del plan; añade la espera en el cliente. |
| 429 | `daily_request_limit_reached` | Se alcanzó el tope diario de solicitudes del plan (Standard 1.000 / Pro 5.000); se reinicia a las 00:00 UTC. Enterprise no tiene tope. |
| 429 | `daily_spend_limit_reached` | Se alcanzó la cuota diaria de uso justo del plan en el gateway; se reinicia a las 00:00 UTC. Enterprise tiene 5 veces la cuota base. |
| 429 | `daily_limit_reached` | Se agotó el presupuesto diario de tokens de IA; se reinicia a las 00:00 UTC. Mejorar el plan aumenta el presupuesto. |
| 429 | `rate_limited` | Se alcanzó el límite de solicitudes de la cuenta o de la clave de API; espera y vuelve a intentarlo. |
| 500 | `internal_server_error` | Fallo inesperado. Vuelve a intentarlo. |
| 503 | `server_overloaded` | La capacidad está llena momentáneamente, o la solicitud superó el plazo total de 90 segundos; vuelve a intentarlo en breve (los SDKs de OpenAI lo reintentan automáticamente). |
| 503 | `daily_capacity_reached` | Se agotó la capacidad diaria compartida del AI Gateway para toda la plataforma. Se reinicia a las 00:00 UTC; reintentar antes no sirve. |
| 503 | `database_unavailable` | La plataforma no está disponible por un momento. Vuelve a intentarlo en unos segundos. |
Tres de ellos se parecen, pero significan cosas distintas:
* `429 daily_spend_limit_reached`: el límite diario de **tu** clave, definido por tu plan.
* `503 daily_capacity_reached`: la capacidad diaria de la **plataforma** para el gateway, compartida por todos los clientes.
* `503 server_overloaded`: una sobrecarga momentánea, o una solicitud que tardó más de 90 segundos en total (incluidos la cola del proveedor, los reintentos y las rondas de búsqueda). Vuelve a intentarlo en unos segundos.
## Preguntas frecuentes
No, la API no guarda estado, exactamente igual que la de OpenAI: envía el historial de la conversación en `messages` en cada solicitud.
`cubic`, el modelo alojado por Square Cloud. No hay una lista de modelos para elegir; el campo `model` se acepta por compatibilidad con los SDKs.
Sí, ese es el caso de uso principal. Es una API HTTPS normal, así que funciona desde cualquier lugar.
Sí: ambos consumen el mismo presupuesto diario de tokens de IA, así que un uso intensivo del gateway reduce el presupuesto disponible para el asistente del panel, y viceversa.
## Relacionado
* SDKs: [`api.ai.chat()`](/es/sdks/js/ai) (JavaScript), [`client.ai.chat()`](/es/sdks/py/ai) (Python), [`c.AI.Chat()`](/es/sdks/go/ai) (Go)