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

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

Yksi avain, yksi työtila, kahdeksan käyttöoikeutta. Etsi Markeja, sommittele designeja, tee muita kokoja ja renderöi tiedostot omalla koodilla tai tekoälyavustajalla. Tutustu myös rajoihin ja virheisiin.

## The short version

- Gradientlyllä on JSON-suunnittelu-API osoitteessa https://gradiently.design/api sekä ylläpidetty MCP-palvelin, jotka käyttävät samoja rajapintapisteitä.
- Jokaiseen pyyntöön liitetään työtilan API-avain, jonka työtilan omistaja tai ylläpitäjä luo kohdassa Asetukset › API ja agentit.
- Avain toimii täsmälleen yhdessä työtilassa luojansa nimissä ja pääsee vain käyttöoikeuksiensa sallimiin rajapintapisteisiin.
- API voi hakea Markkinoilta, sommitella ja muokata designeja brändin Markille, tallentaa kopioita muissa ko’oissa sekä renderöidä tallennettuja designeja PNG- tai PDF-muotoon.
- Avain ei koskaan voi hallita avaimia, käyttää laskutusta, muuttaa tiliä tai lahjoittaa Markia; näihin tarvitaan aina kirjautunut ihminen.

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](https://gradiently.design/fi/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](https://gradiently.design/fi/guide/link-preview-image) muuttava toimitus tai sisältökalenterista viikon julkaisut tekevä sisäinen työkalu. Jos lähtötiedot ovat jo taulukossa, Studion [eräluonti](https://gradiently.design/fi/guide/bulk-create-from-spreadsheet) voi hoitaa työn ilman koodia.

## API vai MCP-palvelin

### MCP-palvelin

- MCP-etäpalvelimia tukeville tekoälyavustajille.
- Claude: `https://gradiently.design/api/mcp`. ChatGPT: `https://gradiently.design/api/mcp/chatgpt`.
- Työkalut hakevat brändisi, tallentavat designeja ja palauttavat Studio-linkkejä.
- Sopii parhaiten, kun haluat pyytää työn tavallisilla sanoilla.

### HTTP API

- Skripteille, taustapalveluille ja automaatioille.
- JSON HTTPS:n kautta osoitteessa `https://gradiently.design/api`.
- Valitset brändin, lähetät sisällön ja käsittelet jokaisen vastauksen.
- Sopii parhaiten täsmälliseen, toistettavaan lopputulokseen.

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](https://gradiently.design/fi/guide/what-is-mcp) selittää sen selkeästi ja [tekoälyavustajan yhdistäminen](https://gradiently.design/fi/guide/connect-ai-assistant) 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.

| Käyttöoikeus | Asetuksissa | Mitä se sallii |
| --- | --- | --- |
| `designs:read` | Lue designeja | Brändit, designit, pikkukuvat, ladatut tiedostot ja renderöinnit |
| `designs:write` | Luo ja muokkaa designeja | Luo, muuta, kopioi ja poista designeja, lataa kuvia, käytä Designeria |
| `marks:read` | Hae Markeja | Hae Markkinoilta ja lue Markeja |
| `marks:claim` | Lunasta Markeja | Lunasta vapaa Mark avaimen luojalle |
| `brand:generate` | Luo brändejä | Brändien luontirajapinnat |
| `workspaces:read` | Lue työtilaa | Työtila, sen jäsenet ja tapahtumaloki |
| `personalities:write` | Muokkaa brändejä | Luo, nimeä uudelleen ja poista brändejä sekä vaihda brändin Mark |
| `members:write` | Kutsu jäseniä | Lähetä kutsuja työtilaan |

Kahdeksan käyttöoikeutta. Uudessa avaimessa on aluksi viisi useimpiin tehtäviin tarvittavaa oikeutta. Lunasta Markeja on pois käytöstä, kunnes valitset sen, koska lunastus tekee sinusta Markin haltijan.

> **Avain on salasana** Säilytä avain ympäristömuuttujassa tai salaisuuksien säilytyspalvelussa. Käytä yhtä avainta työkalua kohden ja vain tehtävän vaatimia oikeuksia. Älä koskaan laita avainta verkkosivulle, mobiilisovellukseen tai repositorioon. Gradiently tallentaa vain tiivisteen, joten vuotanut avain on peruutettava ja korvattava.

## Ensimmäinen pyyntösi

1. **Luo avain** Avaa **Asetukset › API ja agentit**, valitse työtila, nimeä avain käyttökohteensa mukaan ja kopioi se, kun se ilmestyy.
2. **Hae Markkinoilta** `GET` osoitteeseen `/api/marks` parametrilla `?q=` palauttaa 24 Markia sivua kohden sekä `nextCursor`-arvon seuraavaa sivua varten.
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. **Renderöi se** Kutsu `POST /api/designs/:id/render` määrittämällä leveys, korkeus ja muoto. Pura vastauksena saamasi base64-tiedosto.

```bash
export GRADIENTLY_API_KEY="gr_live_…"

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

Haku Markkinoilta vaatii `marks:read`-oikeuden. Koodit toimivat pisteillä tai ilman, kirjainkoosta riippumatta.

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

API:ssa brändien nimi on personalities. Asetteluihin kuuluvat statement, editorial, poster, split, stat, quote, list, event ja minimal.

Instagramin pystyjulkaisu, jossa lukee Tuoretta leipää 7.00 alkaen ja pienellä Tule käymään elävän liukuväritaustan päällä

Pyynnön tulos: sommittelumoottori sijoittaa sanat brändin Markille Instagramin 1080×1350-pystykoossa.

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](https://gradiently.design/fi/guide/copy-to-sizes) selittää sovittamisen.

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

Leveys ja korkeus ovat väliltä 1 ja 4096. Renderöinti vaatii saman designin Markin vientilisenssin kuin Studio; ilman sitä vastaus on 402.

## 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ä](https://gradiently.design/fi/guide/ai-credits-explained) käsittelee käyttömäärät.

| Raja | Sallittu määrä |
| --- | --- |
| Jokainen avaimella tehty pyyntö | 120 minuutissa avainta kohden |
| Kirjoitukset (POST, PATCH, DELETE) | 90 minuutissa tiliä kohden, yhteinen sovelluksen kanssa |
| Renderöinnit | 10 minuutissa tiliä kohden |
| Uudet designit ja kopiot | 60 minuutissa tiliä kohden |
| Lataukset | 60 minuutissa tiliä kohden |

Liukuvat minuutin aikaikkunat. Ylitys palauttaa koodin 429 ja `Retry-After`-otsakkeen sekunteina. Odota sen verran ennen uutta yritystä.

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

## FAQ

### Onko Gradientlyllä API?

Kyllä. JSON-API on osoitteessa `https://gradiently.design/api`, ja tarjolla on myös ylläpidetty MCP-palvelin. Molemmat toimivat työtilan API-avaimella tai ChatGPT:ssä ja Claudessa OAuth-kirjautumisella.

### Kuka voi luoda Gradientlyn API-avaimen?

Työtilan omistajat ja ylläpitäjät kohdassa Asetukset › API ja agentit. Avain näytetään kerran ja toimii vain kyseisessä työtilassa.

### Voinko renderöidä designin PNG-muotoon API:lla?

Kyllä. `POST /api/designs/:id/render` palauttaa PNG- tai PDF-tiedoston base64-muodossa, enintään 4096 pikseliä sivua kohden, kun sinulla on designin Markin vientilisenssi.

### Kuluttaako API:n käyttö tekoälykrediittejä?

Sommittelu, muokkaus ja renderöinti eivät kuluta. Gradientlyn oman Designerin käyttö API:n tai `design`-työkalun kautta kuluttaa työtilan tekoälykrediittejä.

### Mitkä ovat API:n pyyntörajoitukset?

120 pyyntöä minuutissa avainta kohden, pienemmät rajat kirjoituksille, renderöinneille ja latauksille. Ylityksestä saat koodin 429 ja `Retry-After`-otsakkeen.