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

[Canonical HTML page](https://gradiently.design/es/guide/gradiently-for-developers)

Una clave, un espacio de trabajo, ocho permisos. Cómo buscar Marks, componer diseños, crear otros tamaños y renderizar archivos terminados desde tu propio código o un asistente de IA, con los límites y errores que te encontrarás por el camino.

## The short version

- Gradiently tiene una API JSON de diseño en https://gradiently.design/api y un servidor MCP alojado, y ambos se basan en los mismos endpoints.
- Cada petición lleva una clave de API del espacio de trabajo, creada en Ajustes › API y agentes por un propietario o administrador del espacio de trabajo.
- Una clave funciona exactamente en un espacio de trabajo, actúa como la persona que la creó y solo puede acceder a los endpoints que permiten sus permisos.
- La API puede buscar en el Mercado, componer y editar diseños en el Mark de una marca, guardar copias en otros tamaños y renderizar diseños guardados en PNG o PDF.
- Una clave nunca puede gestionar claves, acceder a la facturación, cambiar la cuenta ni regalar un Mark; eso siempre requiere una persona con la sesión iniciada.

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](https://gradiently.design/es/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](https://gradiently.design/es/guide/link-preview-image) 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](https://gradiently.design/es/guide/bulk-create-from-spreadsheet) en el Studio puede hacer el trabajo sin nada de código.

## API o servidor MCP

### Servidor MCP

- Para asistentes de IA compatibles con servidores MCP remotos.
- Claude: `https://gradiently.design/api/mcp`. ChatGPT: `https://gradiently.design/api/mcp/chatgpt`.
- Las herramientas consultan tu marca, guardan diseños y devuelven enlaces al Studio.
- Ideal cuando quieres pedir el trabajo en lenguaje natural.

### API HTTP

- Para scripts, back ends y automatizaciones.
- JSON sobre HTTPS en `https://gradiently.design/api`.
- Tú eliges la marca, envías el contenido y gestionas cada respuesta.
- Ideal cuando necesitas un resultado exacto y repetible.

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](https://gradiently.design/es/guide/what-is-mcp) lo explica con palabras sencillas y [conectar un asistente de IA](https://gradiently.design/es/guide/connect-ai-assistant) 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.

| Permiso | En Ajustes | Qué permite |
| --- | --- | --- |
| `designs:read` | Leer diseños | Marcas, diseños, miniaturas, subidas y renders |
| `designs:write` | Crear y editar diseños | Crear, cambiar, duplicar y eliminar diseños, subir imágenes, usar el Designer |
| `marks:read` | Buscar Marks | Buscar en el Mercado y leer Marks |
| `marks:claim` | Reservar Marks | Reservar un Mark disponible para el creador de la clave |
| `brand:generate` | Generar marcas | Endpoints de generación de marcas |
| `workspaces:read` | Leer el espacio de trabajo | El espacio de trabajo, sus miembros y el registro de auditoría |
| `personalities:write` | Editar marcas | Crear, renombrar y eliminar marcas, cambiar el Mark de una marca |
| `members:write` | Invitar a miembros | Enviar invitaciones al espacio de trabajo |

Los ocho permisos. Una clave nueva empieza con los cinco que necesita la mayor parte del trabajo; Reservar Marks queda desactivado hasta que lo elijas, porque una reserva te convierte en titular de un Mark.

> **Una clave es una contraseña** Guárdala en una variable de entorno o en un almacén de secretos, una clave por herramienta, con los menos permisos que hagan el trabajo. Nunca pongas una clave en una página web, una app móvil o un repositorio: Gradiently solo guarda un hash, así que una clave filtrada debe revocarse y sustituirse.

## Tu primera petición

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. **Busca en el Mercado** Un `GET` a `/api/marks` con `?q=` devuelve 24 Marks por página y un `nextCursor` para la siguiente.
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. **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.

```bash
export GRADIENTLY_API_KEY="gr_live_…"

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

Buscar en el Mercado requiere `marks:read`. Los códigos funcionan con o sin puntos, en mayúsculas o minúsculas.

```json
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": [ … ] }
```

En la API, las marcas se llaman personalities. Las composiciones incluyen statement, editorial, poster, split, stat, quote, list, event y minimal.

Un post vertical de Instagram que dice Pan recién hecho desde las 7:00 con una pequeña línea Ven a vernos, sobre un fondo degradado vivo

Lo que produce esa petición: las palabras colocadas por el motor de composición sobre el Mark de la marca, en el tamaño vertical de Instagram de 1080×1350.

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](https://gradiently.design/es/guide/copy-to-sizes) explica la recomposición.

```json
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 }
```

El ancho y el alto van de 1 a 4096. Renderizar requiere la misma licencia de exportación para el Mark del diseño que el Studio; sin ella la respuesta es 402.

## 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](https://gradiently.design/es/guide/ai-credits-explained) detalla la asignación.

| Límite | Asignación |
| --- | --- |
| Cada petición con una clave | 120 por minuto y clave |
| Escrituras (POST, PATCH, DELETE) | 90 por minuto y cuenta, compartidas con la app |
| Renders | 10 por minuto y cuenta |
| Diseños nuevos y duplicados | 60 por minuto y cuenta |
| Subidas | 60 por minuto y cuenta |

Ventanas deslizantes de un minuto. Si te pasas, la respuesta es 429 con una cabecera `Retry-After` en segundos: espera ese tiempo, no reintentes enseguida.

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](https://gradiently.design/es/guide/workspace-roles).

## FAQ

### ¿Tiene Gradiently una API?

Sí. Tiene una API JSON en `https://gradiently.design/api` y un servidor MCP alojado, ambos utilizables con una clave de API del espacio de trabajo o, en el caso de ChatGPT y Claude, con inicio de sesión OAuth.

### ¿Quién puede crear una clave de API de Gradiently?

Los propietarios y administradores de un espacio de trabajo, en Ajustes › API y agentes. La clave se muestra una sola vez y solo funciona en ese espacio de trabajo.

### ¿Puedo renderizar un diseño en PNG con la API?

Sí. `POST /api/designs/:id/render` devuelve un PNG o un PDF en base64, de hasta 4096 píxeles por lado, siempre que tengas la licencia de exportación del Mark del diseño.

### ¿Usar la API gasta créditos de IA?

Componer, editar y renderizar diseños, no. Pedírselo al Designer de Gradiently mediante la API o la herramienta `design` gasta los créditos de IA del espacio de trabajo.

### ¿Cuáles son los límites de uso de la API?

120 peticiones por minuto y clave, con límites más bajos para escrituras, renders y subidas. Si superas un límite recibes un 429 con una cabecera `Retry-After`.