AI Gateway compatible con OpenAI (beta)

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);

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)

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." }
    ]
  }'

{
  "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
  }
}

string

requerido

La clave de API de tu cuenta. Puedes encontrarla en la configuración de tu cuenta.

Requiere una clave de API con el scope 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). 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

string

Se acepta por compatibilidad con los SDKs; el gateway siempre responde como cubic.

array

requerido

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.

number

Se ajusta sin aviso al límite de salida de tu plan.

number

De 0 a 2.

array

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

string | object

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.

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);

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)

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." }
    ]
  }'

{
  "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

¿Recuerda las conversaciones?

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.

¿Qué modelo es?

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.

¿Puedo llamarlo desde una aplicación alojada en Square Cloud?

Sí, ese es el caso de uso principal. Es una API HTTPS normal, así que funciona desde cualquier lugar.

¿El uso del gateway afecta al asistente de IA del panel?

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() (JavaScript), client.ai.chat() (Python), c.AI.Chat() (Go)

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);

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)

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." }
    ]
  }'

{
  "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
  }
}

Primeros pasos

Cuenta

Aplicaciones

Bases de datos

Workspaces

IA

AI Gateway compatible con OpenAI (beta)

Cómo conectarse

Planes y límites

Contrato de la solicitud

Búsqueda web integrada

Errores

Preguntas frecuentes

Relacionado

​Cómo conectarse

​Planes y límites

​Contrato de la solicitud

​Búsqueda web integrada

​Errores

​Preguntas frecuentes

​Relacionado

Cómo conectarse

Planes y límites

Contrato de la solicitud

Búsqueda web integrada

Errores

Preguntas frecuentes

Relacionado