API de Aiva Studio

La API pública y el MCP son dos transportes sobre el mismo registro de operaciones que usa el tablero. Lo único que cambia entre ellos es cómo se prueba la identidad: una tool nueva aparece en los tres a la vez.

Base: https://studio.aivacompany.com

---

Autenticación

Una sola credencial para todo: una clave sk_live_… que se crea en Ajustes → Claves de API.

Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxx

De la clave se guarda únicamente su SHA-256. Se muestra en claro una sola vez, al crearla — no hay forma de recuperarla después, ni para nosotros. Si se pierde, se revoca y se emite otra.

Permisos

Scope	Qué habilita
read	Consultar marca, productos, material, trabajos, calendario, presupuesto
write	Además, crear briefs, entradas de calendario y planes de generación
generate	Además, aprobar lotes (es decir, gastar)

Una clave nunca llega a admin ni a owner: no puede cambiar el plan, tocar credenciales ni administrar miembros. Con write alcanza como mucho el rol editor.

Límite de tasa

120 peticiones por minuto por clave (no por dirección IP). Al pasarse, 429.

---

Errores

Forma estable, siempre JSON:

{ "error": "Mensaje pensado para que lo lea una persona", "reason": "role" }

Código	Cuándo
400	Cuerpo malformado o datos que no pasan la validación
401	Clave ausente, inválida, vencida o revocada
403	La clave no tiene el permiso, o la operación no se expone por este canal
404	La tool no existe
422	Regla de negocio: supera el tope, falta la clave de generación, el modo realista bloquea la pieza
429	Límite de tasa

Nunca sale el mensaje crudo de la base: filtraría nombres de tablas y columnas.

---

REST

GET /api/public/v1/tools

Catálogo de lo que esta clave puede llamar. Cada entrada trae allowed, así no hay que descubrirlo a fuerza de 403.

{
  "tools": [
    {
      "name": "buscar_material",
      "description": "Busca tomas dentro del material propio…",
      "inputSchema": { "type": "object", "properties": { "…": {} } },
      "mutates": false,
      "minRole": "viewer",
      "allowed": true
    }
  ],
  "scopes": ["read"]
}

POST /api/public/v1/tools

{ "tool": "buscar_material", "input": { "tags": ["fuego", "comida"], "limit": 5 } }

Respuesta:

{ "ok": true, "result": { "scenes": [ … ], "count": 5 } }

---

MCP

POST /api/mcp — Streamable HTTP sin estado, JSON-RPC 2.0, misma clave. Protocolo 2025-06-18.

// initialize
{ "jsonrpc": "2.0", "id": 1, "method": "initialize" }

// tools/list — sólo devuelve lo que la clave puede llamar de verdad
{ "jsonrpc": "2.0", "id": 2, "method": "tools/list" }

// tools/call
{
  "jsonrpc": "2.0", "id": 3, "method": "tools/call",
  "params": { "name": "consultar_marca", "arguments": {} }
}

Un fallo de una tool vuelve como result con isError: true, no como error de JSON-RPC: así el modelo lo lee y corrige, en vez de creer que el transporte está caído.

Por qué el MCP es de solo lectura

No es cautela genérica. Son dos razones concretas:

1. El mecanismo de confirmación asume una pantalla. Las mutaciones van en dos fases: la primera devuelve una vista previa y un token firmado, la segunda ejecuta lo previsualizado. Ese token viaja por la interfaz y nunca como texto hacia el modelo. Por MCP tendría que pasar por el contexto del modelo, que debilita el mecanismo de verdad.
2. Una clave es un espacio de trabajo, no una persona. El registro de auditoría diría "la clave X" en vez de "Juan", y un audit que no puede nombrar a alguien no sirve para responder quién hizo qué.

Tres candados independientes lo sostienen, y ninguno alcanza solo: la variable MCP_EXPOSE_WRITE_TOOLS en false, las claves emitidas sin el scope de escritura, y assertCanExecute, que rechaza mutar cuando no hay un actor identificado.

Se habilitarán cuando exista una confirmación que no dependa de una pantalla.

---

Tools disponibles

Marca y bibliotecas

Tool	Muta	Qué hace
consultar_marca	no	Marca activa con sus tres archivos, y si alcanza para escribir textos
listar_productos	no	Productos y si tienen foto real aprobada
crear_producto	sí	Producto con su foto real de referencia
listar_lugares	no	Espacios del negocio con su foto
crear_lugar	sí	Espacio del negocio: la terraza, la barra, el salón
listar_personas	no	Presentadores reutilizables
crear_persona	sí	Presentador reutilizable a partir de una foto aprobada

Material propio y radar

Tool	Muta	Qué hace
buscar_material	no	Tomas por etiqueta, producto o lugar, con el segundo exacto
listar_material	no	Videos cargados y cuáles falta analizar
analizar_material	sí	Corta un video en tomas, saca miniaturas y lo vuelve buscable
escanear_nicho	sí	Mira una cuenta del rubro y guarda lo que rinde por encima de su propia media
registrar_referencia	sí	Guarda el desglose estructural de una pieza que funciona
listar_referencias	no	Referencias ordenadas por cuánto superan la media de su cuenta

Estrategia

Tool	Muta	Qué hace
crear_brief	sí	Brief validado contra la puerta de cumplimiento del formato
listar_briefs	no	Briefs del espacio de trabajo
revisar_variacion	no	Si un lote varía de verdad o es la misma pieza repetida
sugerir_formatos	no	En qué formatos llevar el mismo mensaje

Generación

Tool	Muta	Qué hace
planificar_lote	sí	Arma el plan y su costo sin gastar
aprobar_lote	sí	Aprueba y encola. Acá empieza el gasto
listar_trabajos	no	Estado, costo, semilla y error de cada trabajo
listar_resultados	no	Piezas ya generadas, con su imagen, para elegir cuáles animar
marcar_ganadoras	sí	Marca qué piezas valen la pena. Animar exige esto primero
consultar_presupuesto	no	Gasto del mes contra el tope

Calendario y publicación

Tool	Muta	Qué hace
crear_entrada_calendario	sí	Evento puntual o recurrente con su plantilla de brief
que_toca_esta_semana	no	Qué hay que producir en los próximos días
brief_desde_calendario	sí	Convierte una entrada del calendario en un brief listo
programar_publicacion	sí	Programa una pieza en un canal
exportar_paquete	no	Archivo, texto, etiquetas y relación de aspecto
listar_canales	no	Qué canales están conectados y cuáles faltan

---

Tres cosas que conviene saber antes de automatizar

El costo se estima antes, siempre. planificar_lote devuelve el costo y el presupuesto restante sin gastar nada; aprobar_lote es el que gasta. La separación existe también por API, no sólo en la pantalla: un script que llame directo a aprobar sin haber mirado el plan se va a chocar igual con el tope mensual, que se aplica en el código.

Animar exige elegir primero. planificar_lote con kind: "animate" requiere que cada variación traiga el sourceJobId de una estática marcada como ganadora con marcar_ganadoras. No es burocracia: un video cuesta entre diez y cien veces más que la imagen de la que sale, y ese saldo es de la cuenta del cliente, no un crédito nuestro.

El modo realista puede rechazar una pieza. Si el espacio de trabajo está en modo real, una variación que nombra un producto o un lugar sin foto real aprobada devuelve 422 con el motivo y el arreglo. No es un error del integrador: es la regla que evita que salga publicado un local que no es el del cliente.