Die API ist dieselbe, die auch die Gradiently-App nutzt. Ein Schlüssel sieht also dieselben Daten und durchläuft dieselben Prüfungen wie sein Ersteller in der App, beschränkt auf einen Arbeitsbereich und seine Scopes. Ein Schlüssel, der einen Endpunkt aufruft, den keiner seiner Scopes abdeckt, bekommt 403.
Basis-URL und Authentifizierung
Alle Pfade unten liegen unter https://. Schick deinen Schlüssel bei jeder Anfrage als Bearer-Token mit. Anfragekörper sind JSON mit Content-Type: application/, außer bei Uploads.
curl https://gradiently.design/api/marks/mine \
-H "Authorization: Bearer gr_live_…"- Ein Schlüssel ist immer an den Arbeitsbereich gebunden, in dem er erstellt wurde. Du musst den Arbeitsbereich nicht angeben; wenn du
X-Workspaceoder?workspace=schickst, muss es der des Schlüssels sein, sonst scheitert die Anfrage mit 403. - Anfragekörper werden streng geprüft: Ein Feld, das der Endpunkt nicht kennt, führt zu 422.
- Antworten sind JSON, sofern nicht anders angegeben (Bilder, Weiterleitungen und der Stream des Designers). Fehlermeldungen an API-Schlüssel sind auf Englisch.
- Ein Schlüssel handelt als sein Ersteller. Designs und Marken, die er erstellt, gehören dem Arbeitsbereich; Marks, die er sichert, hält sein Ersteller.
Arbeitsbereich
/ api/ meScope
workspaces:read und designs:readWas er tut
/ api/ workspacesScope
workspaces:readWas er tut
/ api/ workspaces/ :idScope
workspaces:readWas er tut
/ api/ workspaces/ :id/ membersScope
workspaces:readWas er tut
/ api/ workspaces/ :id/ auditScope
workspaces:readWas er tut
/ api/ workspaces/ :id/ invitesScope
members:writeWas er tut
GET /api/me
{
"viewer": { "id": "…", "name": "Ada Moss", "handle": "ada", "workspaceId": "…" },
"workspaces": [{ "id": "…", "name": "Hearth", "role": "owner" }],
"activeWorkspaceId": "…",
"personalities": [{ "id": "…", "slug": "hearth", "name": "Hearth", "markId": "…" }]
}POST /api/workspaces/:id/invites
{ "email": "sam@example.com", "role": "editor" }
{ "id": "…", "expiresInDays": 7 }role ist admin, editor oder viewer. Die Person muss dieselbe E-Mail-Adresse bestätigen, bevor sie annimmt.Marken
/ api/ personalitiesScope
designs:readWas er tut
{ items }./ api/ personalitiesScope
personalities:writeWas er tut
/ api/ personalities/ :idScope
personalities:writeWas er tut
/ api/ personalities/ :idScope
personalities:writeWas er tut
/ api/ personalities/ :id/ designsScope
designs:readWas er tut
/ api/ personalities/ :id/ brandScope
designs:readWas er tut
POST /api/personalities
{ "name": "Hearth Bakery", "markId": "…" }
PATCH /api/personalities/:id
{ "profile": { "about": "A neighbourhood bakery", "voice": "warm, plain" } }
{ "id": "…", "slug": "hearth-bakery", "name": "Hearth Bakery", "markId": "…", "profile": { … } }markId ist beim Erstellen optional. Ein Profil kann außerdem audience, uses, keywords, dos, donts, website, handle und fonts enthalten.Die Designliste nimmt ?q= für die Suche in Titeln und ?mark= als Filter nach Mark. Jeder Eintrag hat id, personalityId, markId, title, form, thumb, shared und updatedAt, ohne das Dokument.
Designs
/ api/ agent/ composeScope
designs:writeWas er tut
/ api/ designsScope
designs:writeWas er tut
/ api/ designs/ :idScope
designs:readWas er tut
/ api/ designs/ :idScope
designs:writeWas er tut
/ api/ designs/ :idScope
designs:writeWas er tut
/ api/ designs/ :id/ duplicateScope
designs:writeWas er tut
/ api/ designs/ :id/ thumbScope
designs:readWas er tut
/ api/ designs/ :id/ renderScope
designs:readWas er tut
Am einfachsten erstellst du ein Design per Code mit POST /: Du beschreibst den Inhalt, und die Layout-Engine platziert ihn mit dem Mark der Marke. Derselbe Endpunkt remixt eine Vorlage (template mit text, photos, icons, hide) oder bearbeitet mit designId und ops ein gespeichertes Design.
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": [ … ] }issues listet, was die Prüfung gefunden hat (Ränder, Überschneidungen, Hierarchie, Kontrast).POST /api/designs
{
"personalityId": "…",
"form": "blank",
"title": "Launch post",
"doc": { "ratio": "custom", "width": 1080, "height": 1350, "shift": [0.5, 0.5, 0.5, 0.5], "elements": [] }
}
{ "id": "…", "personalityId": "…", "markId": null, "title": "Launch post", "form": "blank", "doc": { … }, "updatedAt": "…", "thumb": null, "shared": false }markId ist optional; ohne diese Angabe trägt das Design den Mark der Marke. Lies ein Design mit GET / api/ designs/ :id, um ein vollständiges Dokument zu sehen.PATCH / nimmt beliebige von title, doc, markId und shared. Wenn du shared auf true setzt, wird ein Ansichtslink unter / veröffentlicht. Schick baseUpdatedAt, also das updatedAt, das du zuletzt gelesen hast, damit das Speichern mit 409 abgelehnt wird, falls jemand das Design inzwischen geändert hat.
POST /api/designs/:id/render
{ "width": 1080, "height": 1350, "format": "png", "page": 0 }
{ "id": "…", "data": "iVBORw0KGgo…", "encoding": "base64", "mimeType": "image/png", "width": 1080, "height": 1350, "pages": 1 }page zählt ab 0; ein PDF ohne page enthält jede Seite, jeweils in ihrer Größe aus dem Studio, zu der die Anfrage passen muss. Rechne mit bis zu drei Minuten.Zum Rendern braucht es für den Mark des Designs dieselbe Exportlizenz wie im Studio; ohne sie lautet die Antwort 402. Beim Rendern wird das Design nie veröffentlicht und keine Datei gespeichert.
Uploads
/ api/ uploadsScope
designs:writeWas er tut
/ api/ uploadsScope
designs:readWas er tut
/ api/ uploads/ :idScope
designs:readWas er tut
?w= fragt eine Breite an./ api/ uploads/ :idScope
designs:writeWas er tut
curl https://gradiently.design/api/uploads \
-H "Authorization: Bearer $GRADIENTLY_API_KEY" \
-F "file=@shopfront.jpg;type=image/jpeg"
# { "id": "…", "url": "/api/uploads/…" }file: PNG, JPEG, WebP, GIF oder AVIF, höchstens 8 MB, mit einem Typ, der zum Inhalt passt. Nutze die zurückgegebene url als src eines Bildes oder als Foto in einer Vorlage.Video, Audio und Untertitel
Lade Video und Audio als Multipart-Feld file an POST / hoch. Die Grenzen sind 100 MB für Video, 25 MB für Audio und eine Stunde je Quelle. Die Antwort enthält die private url und die geprüfte duration. GET / listet die Medien des Arbeitsbereichs; GET / prüft ihre tatsächlichen Metadaten. Lesen braucht designs:read; Hochladen und Löschen brauchen designs:write.
Marks
/ api/ marksScope
marks:readWas er tut
/ api/ marks/ :codeScope
marks:readWas er tut
/ api/ marks/ mineScope
marks:readWas er tut
/ api/ agent/ markScope
marks:readWas er tut
/ api/ marksScope
brand:generateWas er tut
/ api/ marks/ :idScope
brand:generateWas er tut
/ api/ marks/ :code/ claimScope
marks:claimWas er tut
/ api/ marks/ :code/ buyScope
marks:claimWas er tut
GET / nimmt q (Name oder Code), tone (dark oder light), material, status (listed, house oder sale) und cursor. Die Antwort ist { "items": [ … ], "nextCursor": "…" } mit 24 Marks pro Seite. Ein Mark hat id, code, name, recipe, status, creator, holder und createdAt.
Gesichert wird immer für den Ersteller des Schlüssels, nie für den Arbeitsbereich. Kostenloses Sichern und Sichern, das durch ein Guthaben zum Sichern gedeckt ist, wird sofort abgeschlossen. Braucht das Sichern eine Zahlung, antwortet es mit 402 und checkout: true, und buy antwortet mit 409 und checkout: true; schließ diese Fälle in Gradiently ab, denn ein Schlüssel kann nicht bezahlen. buy nimmt { "priceCents": … }, den angebotenen Preis, den du gesehen hast, und scheitert mit 409, wenn er sich geändert hat.
Der Designer
/ api/ agentScope
designs:writeWas er tut
/ api/ batchesScope
designs:writeWas er tut
/ api/ batchesScope
designs:readWas er tut
/ api/ batches/ :idScope
designs:readWas er tut
/ api/ batches/ :idScope
designs:writeWas er tut
/ api/ agent/ runs?designId=Scope
designs:readWas er tut
/ api/ agent/ runs/ :idScope
designs:writeWas er tut
POST /api/batches
{
"personalityId": "…",
"see": false,
"plan": {
"brief": "Autumn menu launch, Saturday 4 October",
"items": [
{ "size": "ig-post", "brief": "The announcement" },
{ "size": "ig-story", "brief": "Three new loaves, one line each" }
]
}
}
{ "id": "…", "state": "running", "items": [{ "index": 0, "title": "…", "state": "…" }] }GET / api/ batches/ :id regelmäßig ab; jeder Eintrag bekommt eine designId und eine url, sobald er gespeichert ist. state endet als done, stopped oder failed.Der Designer verbraucht die KI-Credits des Arbeitsbereichs. Liegt das Guthaben unter dem, was ein Durchgang braucht, antworten / und / mit 402 und code: "credits". Pro Person laufen höchstens zwei Reihen gleichzeitig. Das Werkzeug design unter MCP und KI-Assistenten liest den Stream des Designers und speichert das Ergebnis für dich, was einfacher ist, als den Stream selbst zu verarbeiten.
Fehler
Ein Fehler antwortet mit einem Statuscode und einem JSON-Körper mit einer lesbaren Meldung in error. Manche fügen Felder hinzu, die unten genannt sind. Die einzige Ausnahme ist /: Ein Körper, der kein gültiges JSON ist, antwortet mit 400 und stattdessen einem JSON-RPC-Fehlerobjekt, { "jsonrpc": "2.0", "id": null, "error": { "code": -32700, "message": "Parse error" } }.
{ "error": "API key lacks required scope for this endpoint." }Wann
Wann
checkout: true), keine Exportlizenz oder zu wenige KI-Credits (code: "credits").Wann
Wann
Wann
Wann
Wann
Retry-After ab und versuch es noch mal.Wann
Retry-After.Wann
Ratenlimits
Limits zählen über ein gleitendes Fenster von einer Minute, sofern nicht anders angegeben. Wer darüber liegt, bekommt 429 mit einem Header Retry-After in Sekunden und einem Feld retryAfter im Körper. Werde langsamer und versuch es nach dieser Zeit erneut; wiederhole die Anfrage nicht sofort.
Kontingent
Kontingent
Kontingent
Kontingent
Kontingent
Kontingent
Kontingent
Exporte und der Designer haben außerdem eine gemeinsame Kapazität. Ist sie ausgeschöpft, lautet die Antwort 503 oder 429 mit Retry-After, auch wenn du unter deinen eigenen Limits liegst. Über MCP zählt ein Werkzeugaufruf einmal für die MCP-Anfrage und einmal für jede API-Anfrage, die das Werkzeug stellt.
Paginierung
Listen liefern eine Seite nach der anderen. Die nächste Seite fragst du mit ?cursor= an.
- Suche im Markt (
/): 24 pro Seite. Gib denapi/ marks nextCursoraus der Antwort mit; auf der letzten Seite ist er null. - Versionen von Marks: Gib den Wert
nextaus der Antwort mit; auf der letzten Seite ist er null. - Designs einer Marke: 100 pro Seite, die neuesten zuerst. Gib die
iddes letzten Designs mit, das du bekommen hast. - Uploads: 60 pro Seite, die neuesten zuerst. Gib die
iddes letzten Uploads mit. - Marken, Arbeitsbereiche, Mitglieder und das Audit-Log: 100 pro Seite. Gib die
iddes letzten Eintrags mit (userIdbei Mitgliedern). Marken werden über/alsapi/ personalities { items }aufgelistet.
Schlüssel, Scopes und Rotation findest du unter API-Schlüssel und Scopes. Fehlt ein Endpunkt, den du brauchst, sag uns Bescheid.