Saltar al contenido principal
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 adicional, y el uso solo cuenta para los límites de tokens propios del gateway. 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 de los límites de tokens propios del gateway: un límite diario, que se reinicia a las 00:00 UTC, y un límite semanal de 4 veces el diario, que se reinicia el lunes a las 00:00 UTC. Son independientes de los límites del asistente de IA del panel, así que el tráfico del gateway nunca agota la cuota del asistente, y viceversa. 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 las 00:00 UTC. Todos los tamaños del plan Standard tienen los mismos límites en el gateway, y lo mismo ocurre con todos los tamaños de Pro. Los límites de tokens de Enterprise crecen con el plan: 10M tokens por día en Enterprise 32, 12M en Enterprise 48, 14M en Enterprise 64, 16M en Enterprise 96 y 20M en Enterprise 128 o superior, con 4 veces eso por semana.
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
El nombre actual de OpenAI para el límite de tokens de la respuesta, el que envían los SDK de OpenAI. Tiene prioridad sobre max_tokens cuando llegan los dos. Se ajusta sin aviso al límite de salida de tu plan.
number
El nombre heredado, que se sigue aceptando. 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.

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

Reintentos

La mayoría de las respuestas 429 y 503 le indican a tu cliente cuándo volver a intentarlo, con encabezados que leen los SDKs de OpenAI: Los SDKs de OpenAI respetan un Retry-After de hasta 60 segundos. Una espera más larga pasa al backoff propio del SDK, salvo que la respuesta también traiga x-should-retry: false, que desactiva sus reintentos automáticos. Sin un SDK de OpenAI, lee Retry-After tú mismo y espera esos segundos antes de la siguiente solicitud.

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.
No. El gateway tiene sus propios límites diario y semanal de tokens, independientes de los del asistente del panel, así que un uso intensivo del gateway nunca agota la cuota del asistente, y viceversa.

Relacionado