Agentes y API

Qué es

i3dify convierte imágenes y PDF en piezas 3D que compartes con un enlace, en cualquiera de sus tipos de proyecto: un flipbook, un álbum de fotos, una pared de galería, un mockup, una taza, una credencial y más. Puedes hacerlo tú en el panel, o dejar que un agente o un script lo haga por ti, con las mismas herramientas que el producto usa por dentro.

• Describes lo que quieres y señalas los archivos. El agente elige el tipo de proyecto, sube las páginas, crea el proyecto y te entrega el enlace.
• Los archivos nunca pasan por el modelo. Van directo al almacenamiento de tu espacio de trabajo, y las herramientas solo mueven referencias a ellos.
• Todo lo que crea el agente aparece en tu panel, donde lo sigues editando como siempre.
• No sirve solo para proyectos nuevos. Un agente también puede editar y borrar proyectos, armar colecciones, filmar y editar piezas de Studio y recordar datos de tu marca.

Cuatro formas de entrar

Elige la que encaje con el lugar donde ya trabajas.

Conectar por MCP

MCP es el estándar que usan los asistentes para llamar herramientas externas. i3dify expone un único servidor MCP remoto. Te conectas una vez y, desde ahí, el asistente tiene las mismas herramientas que usa el asistente de IA del panel:

• Proyectos: detectar el tipo de proyecto que conviene a tus archivos, subirlos, crear un proyecto, agregar páginas o imágenes, cambiar su configuración o su visibilidad, leerlo, listar tus proyectos y borrar uno.
• Colecciones: crear una colección con tus proyectos, cambiar su aspecto y su contenido, y leerla.
• Studio: filmar un proyecto como composición de Studio, listar las composiciones y editar una.
• Espacio de trabajo: listar tus espacios de trabajo, ver un resumen de uno y recordar u olvidar datos que el asistente debe tener presentes.

Claude Code

Ejecuta esto en una terminal y después escribe /mcp dentro de Claude Code para iniciar sesión:

claude mcp add --transport http i3dify https://i3dify.com/api/mcp

Claude.ai y Claude Desktop

Agrega un conector personalizado en la configuración y pega esta URL:

https://i3dify.com/api/mcp

Cursor

Haz clic en el botón para agregar i3dify a Cursor y después inicia sesión cuando Cursor te lo pida:

O agrégalo a mano en .cursor/mcp.json:

{
  "mcpServers": {
    "i3dify": {
      "url": "https://i3dify.com/api/mcp"
    }
  }
}

VS Code

Ejecuta esto en una terminal y después inicia el servidor desde la lista de MCP de VS Code para iniciar sesión:

code --add-mcp '{"name":"i3dify","type":"http","url":"https://i3dify.com/api/mcp"}'

ChatGPT

Activa el modo desarrollador (Configuración, Apps y conectores, Avanzado), crea un conector con esta URL y elige OAuth. El modo desarrollador solo está en algunos planes de ChatGPT.

https://i3dify.com/api/mcp

Otros clientes MCP

Windsurf, Gemini CLI y cualquier cliente que hable MCP remoto por HTTP: agrega un servidor con la URL de arriba. El inicio de sesión es el mismo OAuth.

La pantalla de consentimiento

La primera vez que un cliente se conecta, i3dify abre una página de inicio de sesión en tu navegador y te pide permiso para que ese cliente actúe sobre tu cuenta. Usa tu login normal de i3dify. El cliente solo guarda un token propio, nunca tu contraseña.

Una vez conectado, pide lo que quieres con palabras simples: "haz un flipbook con este PDF", "convierte estas capturas en un mockup de teléfono". Si i3dify no logra saber qué tipo de proyecto quieres, no adivina: devuelve las opciones y el asistente te pregunta.

Claves de API

Los scripts y los servidores no pueden abrir un navegador para iniciar sesión, así que usan una clave de API. Una clave es tuya y empieza con i3d_. Por defecto llega a todos los espacios de trabajo de los que formas parte; marca Limitar a este workspace al crearla para dejarla en uno solo.

1. Abre la página de tu cuenta en el panel y entra a API keys.
2. Haz clic en Crear API key, ponle un nombre, elige si la limitas a este espacio de trabajo y cuándo vence (nunca, en 30 días, en 90 días o en un año) y cópiala. Se muestra una sola vez.
3. Envíala en cada solicitud como bearer token.

El encabezado se ve así:

Authorization: Bearer i3d_...

Permisos (scopes)

Una clave creada en la página de tu cuenta tiene los cuatro permisos. Una clave con menos solo se puede crear llamando a POST /api/v1/keys con una lista de scopes mientras tienes la sesión iniciada en i3dify en el navegador, porque una clave no puede crear otras claves. Una llamada que necesite un permiso que la clave no tiene falla con 403.

Trata una clave como una contraseña. Si se filtra, revócala desde la página de tu cuenta y crea una nueva. La vieja deja de funcionar al instante. La lista muestra si cada clave está activa, revocada o vencida, y cuándo se usó por última vez.

Un recorrido mínimo por la API REST

La API vive en https://i3dify.com/api/v1 y habla JSON. Este es el camino más corto desde un archivo en tu disco hasta un enlace para compartir. El id de tu espacio de trabajo sale de GET /api/v1/me.

curl -X POST https://i3dify.com/api/v1/uploads \
  -H "Authorization: Bearer i3d_..." \
  -H "Content-Type: application/json" \
  -d '{"workspaceId":"<workspace-id>","files":[{"name":"catalog.pdf","mime":"application/pdf","size":1048576}]}'

curl -X PUT "<uploadUrl>" \
  -H "Content-Type: application/pdf" \
  -H "x-upsert: true" \
  --data-binary @catalog.pdf

curl -X POST https://i3dify.com/api/v1/projects/from-files \
  -H "Authorization: Bearer i3d_..." \
  -H "Content-Type: application/json" \
  -d '{"workspaceId":"<workspace-id>","sources":[{"path":"<path>"}],"title":"Spring catalog"}'

curl https://i3dify.com/api/v1/projects/<project-id> \
  -H "Authorization: Bearer i3d_..."

Los archivos que ya están en la web se saltan los pasos 1 y 2: pasa { "url": "https://..." } como source. Y si prefieres mandar los bytes de una vez, POST /api/v1/projects/from-files también acepta multipart form data con los archivos como partes.

Límites

Cada solicitud que pasa por el asistente de IA, MCP, REST o la línea de comandos cuenta contra tu plan. El límite por minuto es por credencial (una clave, un cliente conectado), y cada tipo de llamada se cuenta por separado. Las solicitudes mensuales y los tokens de IA son por espacio de trabajo.

• Si superas el límite por minuto, la API responde 429 con un encabezado Retry-After. Cuando el espacio de trabajo usó sus solicitudes del mes, o no le quedan tokens de IA, las llamadas que cambian algo responden 402 hasta el mes siguiente, hasta que compres un paquete de tokens o cambies de plan.
• Solo el asistente de IA gasta tokens de IA. Un token es una milésima de dólar de costo de modelo. Las llamadas por MCP, REST o la línea de comandos no gastan ninguno, pero igual necesitan un saldo mayor que cero. La cuota mensual se renueva al empezar cada mes (UTC) y no se acumula; en la página de facturación se compran paquetes de 2.000 tokens por 5 USD que no vencen.
• La cuota de almacenamiento y el límite de proyectos de tu plan siguen aplicando. Un proyecto creado por un agente cuenta igual que uno creado a mano.
• El plan gratuito conserva la marca de agua de i3dify en el visor, igual que en el panel.

Lo que todavía no está

• No hay render de video sin navegador. Un agente puede crear una composición en Studio y darte su enlace, pero el video se renderiza en Studio, en tu navegador, cuando pulsas exportar.
• No hay webhooks. Para saber cuándo terminó un trabajo, lee el proyecto, o el trabajo en GET /api/v1/jobs/{id}.