API on sama, jota Gradientlyn sovellus käyttää, joten avain näkee samat tiedot ja käy läpi samat tarkistukset kuin sen luoja sovelluksessa, rajattuna yhteen työtilaan ja avaimen oikeuksiin. Avain, joka kutsuu päätepistettä, jota mikään sen oikeuksista ei kata, saa vastaukseksi 403.
Perus-URL ja tunnistautuminen
Kaikki alla olevat polut ovat osoitteen https:// alla. Lähetä avaimesi bearer-tunnisteena jokaisen pyynnön mukana. Rungot ovat JSONia otsakkeella Content-Type: application/, latauksia lukuun ottamatta.
curl https://gradiently.design/api/marks/mine \
-H "Authorization: Bearer gr_live_…"- Avain on aina sidottu työtilaan, jossa se luotiin. Työtilaa ei tarvitse nimetä; jos lähetät
X-Workspace- tai?workspace=-arvon, sen on oltava avaimen oma työtila, tai pyyntö epäonnistuu koodilla 403. - Pyyntöjen rungot tarkistetaan tiukasti: kenttä, jota päätepiste ei tunne, epäonnistuu koodilla 422.
- Vastaukset ovat JSONia, ellei toisin mainita (kuvat, uudelleenohjaukset ja Designerin virta). API-avaimille palautettavat virheilmoitukset ovat englanniksi.
- Avain toimii luojansa nimissä. Sen tekemät designit ja brändit kuuluvat työtilalle; sen lunastamat Markit ovat sen luojan hallussa.
Työtila
/ api/ meOikeus
workspaces:read ja designs:readMitä se tekee
/ api/ workspacesOikeus
workspaces:readMitä se tekee
/ api/ workspaces/ :idOikeus
workspaces:readMitä se tekee
/ api/ workspaces/ :id/ membersOikeus
workspaces:readMitä se tekee
/ api/ workspaces/ :id/ auditOikeus
workspaces:readMitä se tekee
/ api/ workspaces/ :id/ invitesOikeus
members:writeMitä se tekee
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 on admin, editor tai viewer. Kutsutun on vahvistettava sama sähköpostiosoite ennen hyväksymistä.Brändit
/ api/ personalitiesOikeus
designs:readMitä se tekee
{ items }./ api/ personalitiesOikeus
personalities:writeMitä se tekee
/ api/ personalities/ :idOikeus
personalities:writeMitä se tekee
/ api/ personalities/ :idOikeus
personalities:writeMitä se tekee
/ api/ personalities/ :id/ designsOikeus
designs:readMitä se tekee
/ api/ personalities/ :id/ brandOikeus
designs:readMitä se tekee
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 on luotaessa valinnainen. Profiilissa voi olla myös audience, uses, keywords, dos, donts, website, handle ja fonts.Designilistaus hyväksyy parametrin ?q= otsikoiden hakemiseen ja ?mark= Markin mukaan suodattamiseen. Jokaisella kohteella on id, personalityId, markId, title, form, thumb, shared ja updatedAt, ilman dokumenttia.
Designit
/ api/ agent/ composeOikeus
designs:writeMitä se tekee
/ api/ designsOikeus
designs:writeMitä se tekee
/ api/ designs/ :idOikeus
designs:readMitä se tekee
/ api/ designs/ :idOikeus
designs:writeMitä se tekee
/ api/ designs/ :idOikeus
designs:writeMitä se tekee
/ api/ designs/ :id/ duplicateOikeus
designs:writeMitä se tekee
/ api/ designs/ :id/ thumbOikeus
designs:readMitä se tekee
/ api/ designs/ :id/ renderOikeus
designs:readMitä se tekee
Helpoin tapa tehdä design koodista on POST /: kuvailet sisällön, ja asettelumoottori sijoittaa sen brändin Markin päälle. Sama päätepiste muokkaa mallipohjaa (template yhdessä arvojen text, photos, icons ja hide kanssa) tai muokkaa tallennettua designia, kun annat designId- ja ops-arvot.
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 luettelee arvioinnin löydökset (marginaalit, päällekkäisyydet, hierarkia, kontrasti).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 on valinnainen; ilman sitä designissa on brändin Mark. Lue design osoitteesta GET / api/ designs/ :id, niin näet kokonaisen dokumentin.PATCH / hyväksyy minkä tahansa kentistä title, doc, markId ja shared. Kun shared on true, osoitteeseen / julkaistaan katselulinkki. Lähetä baseUpdatedAt eli viimeksi lukemasi updatedAt, niin tallennus hylätään koodilla 409, jos joku on muuttanut designia sen jälkeen.
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 lasketaan nollasta; PDF ilman page-arvoa sisältää kaikki sivut, kunkin Studion koossa, jota pyynnön on vastattava. Varaa aikaa jopa kolme minuuttia.Renderöinti vaatii designin Markille saman vientilisenssin kuin Studio; ilman sitä vastaus on 402. Renderöinti ei koskaan julkaise designia eikä tallenna tiedostoa.
Lataukset
/ api/ uploadsOikeus
designs:writeMitä se tekee
/ api/ uploadsOikeus
designs:readMitä se tekee
/ api/ uploads/ :idOikeus
designs:readMitä se tekee
?w= pyytää tiettyä leveyttä./ api/ uploads/ :idOikeus
designs:writeMitä se tekee
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 tai AVIF, enintään 8 Mt, ja sen tyypin on vastattava sisältöä. Käytä palautettua url-arvoa kuvan src-arvona tai mallipohjan valokuvana.Video, ääni ja tekstitykset
Lähetä video ja ääni multipart-kenttänä file osoitteeseen POST /. Rajat ovat 100 Mt videolle, 25 Mt äänelle ja yksi tunti lähdettä kohti. Vastaus sisältää yksityisen url-osoitteen ja tarkistetun duration-keston. GET / näyttää työtilan median; GET / tarkistaa sen todelliset metatiedot. Lukeminen vaatii designs:read-oikeuden; lähettäminen ja poistaminen vaativat designs:write-oikeuden.
Markit
/ api/ marksOikeus
marks:readMitä se tekee
/ api/ marks/ :codeOikeus
marks:readMitä se tekee
/ api/ marks/ mineOikeus
marks:readMitä se tekee
/ api/ agent/ markOikeus
marks:readMitä se tekee
/ api/ marksOikeus
brand:generateMitä se tekee
/ api/ marks/ :idOikeus
brand:generateMitä se tekee
/ api/ marks/ :code/ claimOikeus
marks:claimMitä se tekee
/ api/ marks/ :code/ buyOikeus
marks:claimMitä se tekee
GET / hyväksyy parametrit q (nimi tai koodi), tone (dark tai light), material, status (listed, house tai sale) ja cursor. Se vastaa muodossa { "items": [ … ], "nextCursor": "…" }, 24 Markia sivulla. Markilla on id, code, name, recipe, status, creator, holder ja createdAt.
Lunastus tehdään aina avaimen luojalle, ei koskaan työtilalle. Ilmaiset lunastukset ja lunastuskrediitillä katetut lunastukset valmistuvat heti. Maksua vaativa lunastus vastaa koodilla 402 ja arvolla checkout: true, ja buy vastaa koodilla 409 ja arvolla checkout: true; viimeistele ne Gradientlyssä, koska avain ei voi maksaa. buy ottaa { "priceCents": … } eli näkemäsi listahinnan ja epäonnistuu koodilla 409, jos hinta on muuttunut.
Designer
/ api/ agentOikeus
designs:writeMitä se tekee
/ api/ batchesOikeus
designs:writeMitä se tekee
/ api/ batchesOikeus
designs:readMitä se tekee
/ api/ batches/ :idOikeus
designs:readMitä se tekee
/ api/ batches/ :idOikeus
designs:writeMitä se tekee
/ api/ agent/ runs?designId=Oikeus
designs:readMitä se tekee
/ api/ agent/ runs/ :idOikeus
designs:writeMitä se tekee
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; jokainen kohde saa designId- ja url-arvot, kun se on tallennettu. state päättyy arvoon done, stopped tai failed.Designer kuluttaa työtilan AI-krediittejä. Kun saldo on pienempi kuin vuoro vaatii, / ja / vastaavat koodilla 402 ja arvolla code: "credits". Kullakin henkilöllä voi olla käynnissä enintään kaksi sarjaa kerrallaan. Sivun MCP ja tekoälyavustajat design-työkalu lukee Designerin virran ja tallentaa tuloksen puolestasi, mikä on yksinkertaisempaa kuin virran käsitteleminen itse.
Virheet
Virhe palauttaa tilakoodin ja JSON-rungon, jossa on luettava error-viesti. Joissakin on lisäkenttiä, jotka nimetään alla. Ainoa poikkeus on /: jos runko ei ole kelvollista JSONia, vastaus on 400 ja sen sijaan JSON-RPC-virheolio, { "jsonrpc": "2.0", "id": null, "error": { "code": -32700, "message": "Parse error" } }.
{ "error": "API key lacks required scope for this endpoint." }Milloin
Milloin
checkout: true), vientilisenssi puuttuu tai AI-krediittejä on liian vähän (code: "credits").Milloin
Milloin
Milloin
Milloin
Milloin
Retry-After-otsakkeen ilmoittamat sekunnit ja yritä uudelleen.Milloin
Retry-After-otsaketta.Milloin
Pyyntörajat
Rajat lasketaan liukuvassa yhden minuutin ikkunassa, ellei toisin mainita. Rajan ylittäminen palauttaa koodin 429, sekunteina ilmoitetun Retry-After-otsakkeen ja rungossa retryAfter-kentän. Hidasta ja yritä uudelleen vasta sen ajan jälkeen; älä yritä heti uudelleen.
Määrä
Määrä
Määrä
Määrä
Määrä
Määrä
Määrä
Vienneillä ja Designerilla on lisäksi yhteinen kapasiteetti. Kun se on täynnä, vastaus on 503 tai 429 ja Retry-After, vaikka omat rajasi eivät olisi täynnä. MCP:n kautta työkalukutsu lasketaan kerran MCP-pyynnöstä ja kerran jokaisesta työkalun tekemästä API-pyynnöstä.
Sivutus
Luettelot palautetaan sivu kerrallaan. Pyydä seuraava sivu parametrilla ?cursor=.
- Markkinoiden haku (
/): 24 sivulla. Välitä vastauksenapi/ marks nextCursor; viimeisellä sivulla se on null. - Markien versiot: välitä vastauksen
next-arvo; viimeisellä sivulla se on null. - Brändin designit: 100 sivulla, uusin ensin. Välitä viimeisen saamasi designin
id. - Lataukset: 60 sivulla, uusin ensin. Välitä viimeisen latauksen
id. - Brändit, työtilat, jäsenet ja tapahtumaloki: 100 sivulla. Välitä viimeisen kohteen
id(jäsenilläuserId). Brändit luetellaan osoitteesta/muodossaapi/ personalities { items }.
Avaimet, oikeudet ja avainten vaihtaminen ovat sivulla API-avaimet ja oikeudet. Jos tarvitsemasi päätepiste puuttuu täältä, kerro meille.