Suunnittelu-API kehittäjille: Gradientlyn API ja MCP-palvelin

Gradiently on suunnittelutyökalun lisäksi suunnittelu-API. Yhdellä rajatuin oikeuksin varustetulla avaimella voit hakea Markeja, luoda brändisi Markia käyttäviä designeja, muuttaa niiden tekstejä, tallentaa kopioita muissa ko’oissa ja renderöidä tuloksen PNG- tai PDF-muotoon. Kaikki kulkee JSON-muodossa HTTPS:n kautta. Samat toiminnot ovat käytettävissä ylläpidetyllä MCP-palvelimella, joten ChatGPT, Claude tai muu MCP-etäpalvelimia tukeva avustaja voi tehdä työn sanallisen pyynnön perusteella ja palauttaa Studiossa avautuvan linkin.

Tämä sivu antaa kehittäjälle yleiskuvan API:n käyttötarkoituksista, avaimista ja käyttöoikeuksista, ensimmäisestä pyynnöstä sekä suunnittelussa huomioitavista rajoista. Täydellinen dokumentaatio on osoitteessa /developers.

Mitä Gradientlyn API osaa

API on sama, jota Gradientlyn sovellus käyttää. Avain näkee samat tiedot ja käy läpi samat tarkistukset kuin sen luoja selaimessa. Hyödylliset tehtävät jakautuvat viiteen ryhmään.

• Etsi ilme. Hae julkisilta Markkinoilta nimellä, värisanoilla tai koodilla ja lue minkä tahansa julkisen Markin koko resepti.
• Tee designeja. Kuvaile sisältö ja asettelu, ja anna sommittelumoottorin sijoittaa ne brändin Markille. Voit myös muokata Gradientlyn pohjaa tai lähettää kokonaisen designdokumentin.
• Muuta designeja. Muokkaa elementtejä, korvaa valittujen tekstielementtien sanat, vaihda designin Mark ja tallenna kopioita muissa ko’oissa.
• Renderöi. Muunna tallennettu design PNG- tai PDF-muotoon Studion omalla moottorilla tai julkaise siihen katselulinkki.
• Lue työtilaa. Listaa brändit, niiden designit, ladatut tiedostot ja jäsenet sekä lue brändin fontit, logot ja värit.

Tavallisia käyttökohteita ovat joka uudesta tuotteesta tuotekortin renderöivä kauppa, jokaisen otsikon linkin esikatselukuvaksi muuttava toimitus tai sisältökalenterista viikon julkaisut tekevä sisäinen työkalu. Jos lähtötiedot ovat jo taulukossa, Studion eräluonti voi hoitaa työn ilman koodia.

API vai MCP-palvelin

Työkalukutsu tekee samat pyynnöt samalla avaimella kuin oma koodisi. Siksi siihen pätevät samat rajat ja virheilmoitukset. Jos MCP on uusi asia, mikä on MCP selittää sen selkeästi ja tekoälyavustajan yhdistäminen neuvoo ChatGPT:n ja Clauden käyttöönoton.

API-avaimet ja käyttöoikeudet

Avaimet luodaan kohdassa Asetukset › API ja agentit, ja vain työtilan omistajat ja ylläpitäjät voivat luoda niitä. Avain näytetään kerran, alkaa merkkijonolla gr_live_, ei vanhene eikä ole muokattavissa. Muuttaaksesi sen oikeuksia luo uusi avain ja peruuta vanha. Se toimii luojansa nimissä vain siinä työtilassa, johon se tehtiin, ja lakkaa toimimasta, jos henkilö poistuu työtilasta tai hänen rooliaan alennetaan.

Ensimmäinen pyyntösi

1. 1

   Luo avain

   Avaa Asetukset › API ja agentit, valitse työtila, nimeä avain käyttökohteensa mukaan ja kopioi se, kun se ilmestyy.

2. 2

   Hae Markkinoilta

   GET osoitteeseen /api/marks parametrilla ?q= palauttaa 24 Markia sivua kohden sekä nextCursor-arvon seuraavaa sivua varten.

3. 3

   Sommittele design

   Lähetä tekstit osoitteeseen POST /api/agent/compose kokovalinnan ja asettelun kanssa. Saat designin tunnisteen, Studio-linkin ja mahdolliset tarkistuksessa löytyneet ongelmat.

4. 4

   Renderöi se

   Kutsu POST /api/designs/:id/render määrittämällä leveys, korkeus ja muoto. Pura vastauksena saamasi base64-tiedosto.

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

Mark huolehtii designin luettavuudesta: sen rauhallisin alue siirtyy sanojen taakse ja Automaattinen muste valitsee vaalean tai tumman tekstin riveittäin. Kun haluat samasta julkaisusta tarinan ja X-julkaisun, MCP-työkalu resize_copies tallentaa kopiot enintään kahdeksaan kokoon kerralla ja sovittaa asettelun kuten Studio. Kopioi eri kokoihin selittää sovittamisen.

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 }

Krediitit, rajat ja virheet

Kun oma avustajasi sommittelee designin piirto- ja muokkaustyökaluilla, Gradientlyn tekoälykrediittejä ei kulu. Gradientlyn oman Designerin käyttö /api/agent- tai /api/batches-rajapinnan tai design-työkalun kautta kuluttaa työtilan krediittejä samalla tavalla kuin Studiossa. Tekoälykrediitit selitettynä käsittelee käyttömäärät.

Virheet palautetaan tilakoodina ja luettavana error-viestinä. Tavallisimmat ovat 401 puuttuvalle tai peruutetulle avaimelle, 403 puuttuvalle käyttöoikeudelle, 402 vientilisenssin tai krediittien puuttuessa, 409 designin muututtua lukemisen jälkeen ja 422 kentän hylätylle validoinnille. Lähetä baseUpdatedAt PATCH-pyynnössä, jotta saat koodin 409 sen sijaan, että kirjoittaisit kollegan muutoksen yli.

Mitä avain ei koskaan voi tehdä

Jotkin toiminnot vaativat aina Gradientlyyn kirjautuneen ihmisen käyttöoikeuksista riippumatta. Avain ei voi luoda tai peruuttaa avaimia, muuttaa tiliä, käyttää laskutusta tai maksaa, siirtää, listata tai vapauttaa Markia, muuttaa jäsenten rooleja tai päästä muihin työtiloihin. Maksua vaativa lunastus pysähtyy ja pyytää siirtymään Gradientlyn kassalle. Rajat ovat tarkoituksellisia: automaatio voi tehdä ja renderöidä töitä, mutta omistus ja raha pysyvät ihmisten hallinnassa. Roolit käsitellään artikkelissa työtilan roolit.