API’en er den samme, som Gradiently-appen bruger, så en nøgle ser de samme data og består de samme tjek, som dens skaber ville i appen, begrænset til ét arbejdsområde og til dens tilladelser. En nøgle, der kalder et endpoint, som ingen af dens tilladelser dækker, får 403.
Basis-URL og godkendelse
Alle stier nedenfor ligger under https://. Send din nøgle som bearer-token med hver forespørgsel. Indhold sendes som JSON med Content-Type: application/, undtagen uploads.
curl https://gradiently.design/api/marks/mine \
-H "Authorization: Bearer gr_live_…"- En nøgle er altid bundet til det arbejdsområde, den blev oprettet i. Du behøver ikke angive arbejdsområdet; sender du
X-Workspaceeller?workspace=, skal det være nøglens eget, ellers fejler forespørgslen med 403. - Indholdet i forespørgsler tjekkes strengt: et felt, som endpointet ikke kender, fejler med 422.
- Svar er JSON, medmindre andet er angivet (billeder, omdirigeringer og Designers stream). Fejlbeskeder til API-nøgler er på engelsk.
- En nøgle handler som sin skaber. Designs og brands, den laver, hører til arbejdsområdet; Marks, den sikrer sig, ejes af dens skaber.
Arbejdsområde
/ api/ meTilladelse
workspaces:read og designs:readHvad det gør
/ api/ workspacesTilladelse
workspaces:readHvad det gør
/ api/ workspaces/ :idTilladelse
workspaces:readHvad det gør
/ api/ workspaces/ :id/ membersTilladelse
workspaces:readHvad det gør
/ api/ workspaces/ :id/ auditTilladelse
workspaces:readHvad det gør
/ api/ workspaces/ :id/ invitesTilladelse
members:writeHvad det gør
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 er admin, editor eller viewer. Personen skal bekræfte den samme e-mailadresse, før invitationen kan accepteres.Brands
/ api/ personalitiesTilladelse
designs:readHvad det gør
{ items }./ api/ personalitiesTilladelse
personalities:writeHvad det gør
/ api/ personalities/ :idTilladelse
personalities:writeHvad det gør
/ api/ personalities/ :idTilladelse
personalities:writeHvad det gør
/ api/ personalities/ :id/ designsTilladelse
designs:readHvad det gør
/ api/ personalities/ :id/ brandTilladelse
designs:readHvad det gør
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 er valgfri ved oprettelse. En profil kan også indeholde audience, uses, keywords, dos, donts, website, handle og fonts.Listen over designs tager ?q= til at søge i titler og ?mark= til at filtrere efter Mark. Hvert element har id, personalityId, markId, title, form, thumb, shared og updatedAt, uden dokumentet.
Designs
/ api/ agent/ composeTilladelse
designs:writeHvad det gør
/ api/ designsTilladelse
designs:writeHvad det gør
/ api/ designs/ :idTilladelse
designs:readHvad det gør
/ api/ designs/ :idTilladelse
designs:writeHvad det gør
/ api/ designs/ :idTilladelse
designs:writeHvad det gør
/ api/ designs/ :id/ duplicateTilladelse
designs:writeHvad det gør
/ api/ designs/ :id/ thumbTilladelse
designs:readHvad det gør
/ api/ designs/ :id/ renderTilladelse
designs:readHvad det gør
Den nemmeste måde at lave et design fra kode på er POST /: du beskriver indholdet, og layoutmotoren placerer det med brandets Mark. Samme endpoint remixer en skabelon (template med text, photos, icons, hide) eller redigerer et gemt design med designId og ops.
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 viser, hvad gennemgangen fandt (margener, overlap, hierarki, 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 er valgfri; uden den bærer designet brandets Mark. Hent et design med GET / api/ designs/ :id for at se et fuldt dokument.PATCH / tager en hvilken som helst af title, doc, markId og shared. Sættes shared til true, udgives et visningslink på /. Send baseUpdatedAt, den updatedAt, du sidst læste, så afvises gemningen med 409, hvis nogen har ændret designet siden.
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 tælles fra 0; en PDF uden page har alle sider, hver i sin størrelse fra Studiet, som forespørgslen skal passe til. Regn med op til tre minutter.Gengivelse kræver samme eksportlicens til designets Mark som i Studiet; uden den er svaret 402. Gengivelsen udgiver aldrig designet og gemmer ingen fil.
Uploads
/ api/ uploadsTilladelse
designs:writeHvad det gør
/ api/ uploadsTilladelse
designs:readHvad det gør
/ api/ uploads/ :idTilladelse
designs:readHvad det gør
?w= beder om en bredde./ api/ uploads/ :idTilladelse
designs:writeHvad det gør
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 eller AVIF, højst 8 MB, med en type, der passer til indholdet. Brug den returnerede url som billedets src eller som foto i en skabelon.Video, lyd og undertekster
Upload video og lyd som multipart-feltet file til POST /. Grænserne er 100 MB for video, 25 MB for lyd og én time pr. kilde. Svaret indeholder den private url og verificerede duration. GET / viser arbejdsområdets medier; GET / kontrollerer deres faktiske metadata. Læsning kræver designs:read; upload og sletning kræver designs:write.
Marks
/ api/ marksTilladelse
marks:readHvad det gør
/ api/ marks/ :codeTilladelse
marks:readHvad det gør
/ api/ marks/ mineTilladelse
marks:readHvad det gør
/ api/ agent/ markTilladelse
marks:readHvad det gør
/ api/ marksTilladelse
brand:generateHvad det gør
/ api/ marks/ :idTilladelse
brand:generateHvad det gør
/ api/ marks/ :code/ claimTilladelse
marks:claimHvad det gør
/ api/ marks/ :code/ buyTilladelse
marks:claimHvad det gør
GET / tager q (navn eller kode), tone (dark eller light), material, status (listed, house eller sale) og cursor. Den svarer { "items": [ … ], "nextCursor": "…" } med 24 Marks pr. side. En Mark har id, code, name, recipe, status, creator, holder og createdAt.
En Mark sikres til nøglens skaber, aldrig til arbejdsområdet. Gratis Marks, og Marks, der er dækket af en kredit til at sikre sig Marks, gennemføres med det samme. Kræver det betaling, svarer kaldet 402 med checkout: true, og buy svarer 409 med checkout: true; gør dem færdige i Gradiently, for en nøgle kan ikke betale. buy tager { "priceCents": … }, den listepris, du så, og fejler med 409, hvis den er ændret.
Designer
/ api/ agentTilladelse
designs:writeHvad det gør
/ api/ batchesTilladelse
designs:writeHvad det gør
/ api/ batchesTilladelse
designs:readHvad det gør
/ api/ batches/ :idTilladelse
designs:readHvad det gør
/ api/ batches/ :idTilladelse
designs:writeHvad det gør
/ api/ agent/ runs?designId=Tilladelse
designs:readHvad det gør
/ api/ agent/ runs/ :idTilladelse
designs:writeHvad det gør
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 løbende; hvert element får en designId og url, når det er gemt. state ender som done, stopped eller failed.Designer bruger arbejdsområdets AI-kreditter. Når saldoen er lavere end det, en tur kræver, svarer / og / 402 med code: "credits". Højst to serier kører ad gangen pr. person. Værktøjet design på MCP og AI-assistenter læser Designers stream og gemmer resultatet for dig, hvilket er nemmere end selv at håndtere streamen.
Fejl
En fejl svarer med en statuskode og et JSON-indhold med en læselig error-besked. Nogle tilføjer felter, som er nævnt nedenfor. Den eneste undtagelse er /: et indhold, der ikke er gyldig JSON, svarer 400 med et JSON-RPC-fejlobjekt i stedet, { "jsonrpc": "2.0", "id": null, "error": { "code": -32700, "message": "Parse error" } }.
{ "error": "API key lacks required scope for this endpoint." }Hvornår
Hvornår
checkout: true), ingen eksportlicens eller for få AI-kreditter (code: "credits").Hvornår
Hvornår
Hvornår
Hvornår
Hvornår
Retry-After, og prøv igen.Hvornår
Retry-After.Hvornår
Hastighedsgrænser
Grænser tælles over et glidende vindue på ét minut, medmindre andet er angivet. Går du over, er svaret 429 med en Retry-After-header i sekunder og et retryAfter-felt i indholdet. Sæt farten ned, og prøv igen efter den tid; prøv ikke igen med det samme.
Tilladt
Tilladt
Tilladt
Tilladt
Tilladt
Tilladt
Tilladt
Eksport og Designer har også en fælles kapacitet. Når den er fuld, er svaret 503 eller 429 med Retry-After, også selvom du er under dine egne grænser. Via MCP tæller et værktøjskald én gang for MCP-forespørgslen og én gang for hver API-forespørgsel, værktøjet laver.
Sideinddeling
Lister returnerer én side ad gangen. Bed om næste side med ?cursor=.
- Søgning i Markedet (
/): 24 pr. side. Sendapi/ marks nextCursorfra svaret med; den er null på sidste side. - Mark-versioner: send værdien
nextfra svaret med; den er null på sidste side. - Et brands designs: 100 pr. side, nyeste først. Send
idfor det sidste design, du modtog. - Uploads: 60 pr. side, nyeste først. Send
idfor den sidste upload. - Brands, arbejdsområder, medlemmer og revisionsloggen: 100 pr. side. Send
idfor det sidste element (userIdfor medlemmer). Brands vises fra/somapi/ personalities { items }.
Nøgler, tilladelser og udskiftning står på API-nøgler og tilladelser. Mangler du et endpoint, der ikke står her, så fortæl os det.