API de diseño para desarrolladores: la API y el MCP de Gradiently

Gradiently es una API de diseño además de una herramienta de diseño. Con una sola clave acotada puedes buscar Marks, crear diseños que lleven el Mark de tu marca, cambiar sus palabras, guardar copias en otros tamaños y renderizar el resultado en PNG o PDF, todo como JSON sobre HTTPS. Las mismas capacidades se ofrecen como servidor MCP alojado, así que ChatGPT, Claude o cualquier asistente compatible con servidores MCP remotos puede hacer el trabajo a partir de una petición en lenguaje natural y darte un enlace que se abre en el Studio.

Esta página es la visión general para desarrolladores: para qué sirve la API, cómo funcionan las claves y los permisos, una primera petición y los límites que conviene tener en cuenta en el diseño. La referencia completa está en /developers.

Qué puede hacer la API de Gradiently

La API es la misma que usa la propia app de Gradiently, así que una clave ve los mismos datos y pasa las mismas comprobaciones que pasaría su creador en el navegador. Los trabajos útiles se agrupan en cinco bloques.

• Encontrar un look. Busca en el Mercado público por nombre, palabras de color o código, y lee la receta completa de cualquier Mark público.
• Crear diseños. Describe el contenido y una composición y deja que el motor de composición lo coloque sobre el Mark de la marca, adapta una de las plantillas de Gradiently o envía un documento de diseño completo.
• Cambiar diseños. Edita por elemento, sustituye las palabras de los elementos de texto elegidos, pon otro Mark en un diseño y guarda copias en otros tamaños.
• Renderizar. Convierte un diseño guardado en PNG o PDF con el propio motor del Studio, o publica un enlace de visualización.
• Leer el espacio de trabajo. Lista las marcas, sus diseños, subidas y miembros, y lee las tipografías, logotipos y colores de una marca.

Usos típicos: una tienda que renderiza una tarjeta de producto para cada artículo nuevo, una redacción que convierte cada titular en una imagen de vista previa de enlace o una herramienta interna que crea los posts de la semana a partir de un calendario de contenidos. Si tus datos de origen ya están en una hoja de cálculo, crear en lote en el Studio puede hacer el trabajo sin nada de código.

API o servidor MCP

Una llamada a una herramienta hace las mismas peticiones que haría tu código, con la misma clave, así que cuenta para los mismos límites y falla con los mismos mensajes. Si MCP es nuevo para ti, qué es MCP lo explica con palabras sencillas y conectar un asistente de IA recorre la configuración de ChatGPT y Claude.

Claves de API y permisos

Las claves se crean en Ajustes › API y agentes, y solo los propietarios y administradores de un espacio de trabajo pueden crearlas. Una clave se muestra una sola vez, empieza por gr_live_, no caduca y no se puede editar: para cambiar lo que puede hacer, crea una nueva y revoca la antigua. Actúa como la persona que la creó, dentro del único espacio de trabajo para el que se hizo, y deja de funcionar si esa persona se va o pierde su rol.

Tu primera petición

1. 1

   Crea una clave

   Abre Ajustes › API y agentes, elige el espacio de trabajo, ponle a la clave el nombre del sitio donde va a ejecutarse y cópiala cuando aparezca.

2. 2

   Busca en el Mercado

   Un GET a /api/marks con ?q= devuelve 24 Marks por página y un nextCursor para la siguiente.

3. 3

   Compón un diseño

   Envía el texto a POST /api/agent/compose con un tamaño predefinido y una composición. Recibes un id de diseño, un enlace al Studio y los problemas detectados en la revisión.

4. 4

   Renderízalo

   Llama a POST /api/designs/:id/render con un ancho, un alto y un formato, y decodifica el archivo en base64 que devuelve.

export GRADIENTLY_API_KEY="gr_live_…"

curl "https://gradiently.design/api/marks?q=deep%20teal" \
  -H "Authorization: Bearer $GRADIENTLY_API_KEY"

POST /api/agent/compose
{
  "personalityId": "…",
  "composition": {
    "size": "ig-post",
    "layout": "statement",
    "blocks": [
      { "role": "headline", "text": "Fresh bread from 7am" },
      { "role": "cta", "text": "Visit us" }
    ]
  }
}

{ "id": "…", "url": "/studio/…", "issues": [], "elements": [ … ] }

Como el diseño está sobre un Mark, la legibilidad se resuelve sola: la zona más tranquila del Mark se coloca detrás de las palabras y Tinta automática elige texto claro u oscuro en cada línea. Para publicar el mismo post como story y como post de X, la herramienta MCP resize_copies guarda copias en hasta ocho tamaños a la vez, recompuestas como lo hace el Studio. Copiar a tamaños explica la recomposición.

POST /api/designs/:id/render
{ "width": 1080, "height": 1350, "format": "png", "page": 0 }

{ "data": "iVBORw0KGgo…", "encoding": "base64", "mimeType": "image/png", "width": 1080, "height": 1350, "pages": 1 }

Créditos, límites y errores

Cuando tu propio asistente compone un diseño mediante las herramientas de dibujo y edición, no se gastan créditos de IA de Gradiently. Pedírselo al Designer de Gradiently, mediante /api/agent, /api/batches o la herramienta design, gasta los créditos del espacio de trabajo exactamente igual que en el Studio. Los créditos de IA explicados detalla la asignación.

Los errores llegan como un código de estado con un mensaje error legible. Los que más verás: 401 por una clave ausente o revocada, 403 por un permiso que falta, 402 cuando se necesita una licencia de exportación o créditos, 409 cuando un diseño ha cambiado desde que lo leíste y 422 cuando un campo no pasa la validación. Envía baseUpdatedAt con un PATCH para recibir ese 409 en lugar de sobrescribir la edición de un compañero.

Lo que una clave nunca puede hacer

Algunas acciones siempre requieren una persona con la sesión iniciada en Gradiently, sean cuales sean los permisos. Una clave no puede crear ni revocar claves, cambiar la cuenta, acceder a la facturación ni pagar nada, transferir, poner en venta ni liberar un Mark, cambiar los roles de los miembros ni acceder a ningún espacio de trabajo que no sea el suyo. Una reserva que requiere pago se detiene y pide pasar por caja en Gradiently. Estos límites son deliberados: una automatización puede crear y renderizar trabajo, pero la propiedad y el dinero se quedan en manos de personas. Los roles se explican en roles del espacio de trabajo.