API-dokumentaatio

Johdanto

Flixy API:n avulla ohjelmistosi voi käyttää Flixy Studion ominaisuuksia: luoda valmiita verkkosivustoja kuvauksen perusteella, muokata ja kääntää niitä, kirjoittaa sivustojen sisältöä, lukea ruokalistoja, luetteloita ja PDF-tiedostoja sekä luoda kuvia ja logoja. Maksat vain onnistuneista kutsuista, ennakkoon maksetusta saldosta.

Pitkät toiminnot (sivuston luominen, muokkaaminen tai kääntäminen) suoritetaan tehtävinä: API vastaa heti, ja sinä seuraat tehtävää tai vastaanotat webhookin. Sisältö, asiakirjojen lukeminen ja kuvat vastaavat suoraan, yleensä muutamassa sekunnissa.

Kehittäjäkonsoli

Avaimia, saldoa, latauksia, webhookeja ja kutsulokeja hallitaan kehittäjäkonsolissa osoitteessa dev.flixy.studio.

• Erillinen kehittäjätili. Kuten muillakin tekoälyalustoilla, kehittäjätilisi on erillinen Flixy Studio -tilistäsi: sillä on oma rekisteröitymisensä, kirjautumisensa ja istuntonsa. Uloskirjautuminen yhdestä ei koskaan kirjaa sinua ulos toisesta. Voit käyttää molemmissa samaa sähköpostiosoitetta.
• Yhdistetty organisaatio. Jos käytät myös Flixy Studiota, voit yhdistää organisaatiosi kehittäjätiliisi, jolloin API voi työskennellä sen verkkosivustojen parissa. Katso Yhdistetty organisaatio.
• Tilin suojaus. Kaksivaiheinen vahvistus, aktiiviset istunnot ja tietojen vienti löytyvät konsolista kohdasta Tili.

Todennus

Lähetä avaimesi jokaisen pyynnön Authorization-otsakkeessa. Avaimet alkavat fx_live_ tai fx_test_.

Authorization: Bearer fx_live_8sJ2…

curl https://flixy.studio/v1/account \
  -H "Authorization: Bearer $FLIXY_API_KEY"

Jokaisella avaimella on oikeudet (scopes). Kutsu ilman tarvittavaa oikeutta palauttaa 403 missing_scope.

Testi- ja live-avaimet

• Testiavaimet (fx_test_…) ovat maksuttomia. Ne palauttavat realistisia esimerkkivastauksia käyttämättä tekoälyä, joten voit rakentaa ja testata koko integraatiosi. Sivustotehtävät valmistuvat muutamassa sekunnissa esimerkkisivustolla.
• Live-avaimet (fx_live_…) palauttavat oikeita tuloksia, ja ne veloitetaan saldostasi.

Jokainen vastaus sisältää otsakkeen Flixy-Mode: test tai Flixy-Mode: live.

Pyynnöt ja vastaukset

Lähetä JSON-runkoja otsakkeella Content-Type: application/json (enintään 16 Mt). Vastaukset ovat JSONia. Päivämäärät ovat ISO 8601 -muodossa UTC-ajassa. Jokaisessa vastauksessa on X-Request-Id-otsake: anna se tuellemme, jos tarvitset apua kutsun kanssa.

Aseta Accept-Language saadaksesi virheilmoitukset omalla kielelläsi (fr, en, es, de, it, pt, nl, ca, el, sv, no, da, fi, is, et, lv, lt, ja; oletuksena englanti).

Virheet

Virheet käyttävät tavallisia HTTP-tilakoodeja, ja niillä on aina sama muoto:

{
  "error": {
    "type": "billing_error",
    "code": "insufficient_balance",
    "message": "Insufficient balance: top up your developer account…",
    "request_id": "req_5c1f0a9e2b7d4c11"
  }
}

Nopeusrajoitukset

• 60 pyyntöä minuutissa avainta kohden (otsake X-RateLimit-Limit).
• 3 sivustotehtävää samanaikaisesti tiliä kohden. Tämä ei rajoita sisältö-, asiakirja- ja kuvakutsuja.
• Kun raja saavutetaan, API vastaa 429 ja Retry-After-otsakkeella sekunteina.

Tarvitsetko enemmän? Kirjoita osoitteeseen contact@flixy.studio ja kerro käyttötapauksestasi.

Idempotenssi

Verkkovirheitä sattuu. Lisää Idempotency-Key-otsake (8–100 merkkiä, esimerkiksi oma tilaustunnuksesi) mihin tahansa POST-pyyntöön: jos lähetät saman pyynnön uudelleen 24 tunnin kuluessa, API palauttaa ensimmäisen vastauksen — otsakkeella Idempotent-Replayed: true — eikä koskaan suorita tai veloita työtä kahdesti.

Tehtävät

Sivuston luominen, muokkaaminen ja kääntäminen kestää noin 30 sekunnista 3 minuuttiin. Nämä päätepisteet vastaavat 202 Accepted ja palauttavat tehtävän. Seuraa sitä 5 sekunnin välein tai odota tapahtumaa job.succeeded / job.failed webhookin kautta.

{
  "id": "job_69023cfbb08a8130d8f6",
  "object": "job",
  "type": "site",
  "status": "succeeded",
  "mode": "live",
  "site_id": "691589621",
  "price": 0.72,
  "currency": "EUR",
  "created_at": "2026-11-11T09:45:01Z",
  "finished_at": "2026-11-11T09:46:35Z",
  "result": { "id": "691589621", "object": "site", "status": "ready", "pages": ["index.html", "menu.html"] }
}

status on queued, running, succeeded tai failed. Epäonnistuneesta tehtävästä ei koskaan veloiteta, ja sen error kertoo syyn.

Luo sivusto

Luo valmiin verkkosivuston kuvauksen perusteella. Oikeus: sites:write.

curl https://flixy.studio/v1/sites \
  -H "Authorization: Bearer $FLIXY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042" \
  -d '{
    "prompt": "Website for an artisan bakery in Lyon: sourdough breads, pastries, online pre-orders",
    "language": "fr",
    "structure": "multipage",
    "features": ["contact_form", "map", "shop"],
    "business": { "name": "Boulangerie du Parc", "city": "Lyon", "phone": "+33 4 00 00 00 00" }
  }'

const res = await fetch('https://flixy.studio/v1/sites', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.FLIXY_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': 'order-1042',
  },
  body: JSON.stringify({
    prompt: 'Website for an artisan bakery in Lyon: sourdough breads, pastries, online pre-orders',
    language: 'fr',
    business: { name: 'Boulangerie du Parc', city: 'Lyon' },
  }),
});
const job = await res.json(); // 202 → { id: 'job_…', status: 'queued', site_id: '…' }

import os, requests

job = requests.post(
    'https://flixy.studio/v1/sites',
    headers={'Authorization': f"Bearer {os.environ['FLIXY_API_KEY']}", 'Idempotency-Key': 'order-1042'},
    json={'prompt': 'Website for an artisan bakery in Lyon: sourdough breads, pastries, online pre-orders',
          'language': 'fr', 'business': {'name': 'Boulangerie du Parc', 'city': 'Lyon'}},
    timeout=30,
).json()

function flixy(string $method, string $path, ?array $body = null): array {
    $ch = curl_init('https://flixy.studio/v1' . $path);
    curl_setopt_array($ch, [
        CURLOPT_CUSTOMREQUEST => $method,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('FLIXY_API_KEY'), 'Content-Type: application/json'],
        CURLOPT_POSTFIELDS => $body ? json_encode($body) : null,
    ]);
    return json_decode(curl_exec($ch), true);
}

$job = flixy('POST', '/sites', ['prompt' => 'Website for an artisan bakery in Lyon', 'language' => 'fr']);

Hae sivusto

Palauttaa sivuston, sen tilan ja sen sivut. Lisää include=html saadaksesi jokaisen sivun täydellisen HTML:n (kuvat isännöi Flixy). Oikeus: sites:read.

{
  "id": "691589621",
  "object": "site",
  "name": "Boulangerie du Parc",
  "status": "ready",
  "language": "fr",
  "pages": ["index.html", "menu.html", "contact.html"],
  "owner": "developer",
  "html": { "index.html": "<!doctype html>…" }
}

Lisää listaukseen owner=developer tai owner=organization suodattaaksesi omistajan mukaan. Yhdistetyn organisaation sivustoille palautetaan myös dashboard_url ja editor_url, joilla ne avataan Flixy Studiossa.

Muokkaa sivustoa

Tekee arkikielellä kuvatun muutoksen, kuten Flixy-editorissa. Jokainen muutos luo uuden version. Oikeus: sites:write.

curl https://flixy.studio/v1/sites/691589621/edits \
  -H "Authorization: Bearer $FLIXY_API_KEY" -H "Content-Type: application/json" \
  -d '{"instruction": "Add an opening hours section: Tuesday to Saturday, 7am to 7pm"}'

Käännä sivusto

Kääntää sivuston jokaisen sivun — navigaation, painikkeet, lomakkeet, kuvien kuvaukset sekä otsikon ja kuvauksen hakukoneille — säilyttäen ulkoasun, kuvat, linkit, hinnat ja yhteystiedot. Oikeus: sites:write.

Kirjoita verkkosisältöä

Kirjoittaa sisältöä, joka on tarkoitettu julkaistavaksi verkkosivustolla tai yrityksen lähetettäväksi asiakkailleen. Vastaa suoraan. Oikeus: content:write.

curl https://flixy.studio/v1/content \
  -H "Authorization: Bearer $FLIXY_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "type": "product_description",
    "language": "it",
    "topic": "Pizza Margherita cooked in a wood-fired oven",
    "facts": "San Marzano tomatoes, fior di latte mozzarella, fresh basil, 48-hour dough",
    "length": "short"
  }'

{
  "id": "job_af25ef1e01c5dbb8e400",
  "object": "content",
  "type": "product_description",
  "language": "it",
  "title": "Pizza Margherita al forno a legna",
  "html": "<p>…</p>",
  "text": "…",
  "meta": { "title": "…", "description": "…" },
  "items": [],
  "ai_generated": true,
  "usage": { "price": 0.01, "currency": "EUR", "mode": "live" }
}

Kenttä html sisältää vain turvallisia tekstitageja (otsikot, kappaleet, luettelot, linkit), ei koskaan skriptejä tai tyylejä.

Lue asiakirja

Lukee ruokalistan, luettelon, hinnaston, käyntikortin, mainoslehtisen tai esitteen ja palauttaa jäsenneltyä sisältöä valmiina verkkosivustolle. Vain se, mitä on oikeasti kirjoitettu, palautetaan. Oikeus: extract:write.

{
  "object": "extract",
  "kind": "menu",
  "business": { "name": "Trattoria Sole", "phone": "…", "hours": "…" },
  "language": "es",
  "sections": [
    { "title": "Pizzas", "items": [ { "name": "Margherita", "description": "…", "price": "11.50" } ] }
  ],
  "colors": ["#b5121b"],
  "usage": { "price": 0.03, "currency": "EUR", "mode": "live" }
}

Luo kuva

Luo valokuvan, piirroksen tai logon verkkosivustolle. Kuvaa isännöi Flixy, ja tiedostossa on tekoälyn tuottaman median vakiomuotoinen IPTC-merkintä. Oikeus: images:write.

Saldo ja tili

Palauttaa saldosi, käynnissä oleville tehtäville varatun summan, käytettävissä olevan summan, kuukauden kulusi ja käytössä olevan avaimen. Oikeus: account:read.

{
  "object": "account",
  "balance": 48.92,
  "available": 45.92,
  "reserved": 3.00,
  "currency": "EUR",
  "spent_this_month": 12.40,
  "key": { "name": "Production server", "mode": "live", "scopes": ["sites:write", "sites:read"] },
  "limits": { "requests_per_minute": 60, "concurrent_site_jobs": 3 }
}

Käyttö ja hinnat

/v1/usage palauttaa kutsusi ja summat toiminnoittain tietyltä ajanjaksolta. /v1/pricing palauttaa nykyiset tyypilliset ja vähimmäishinnat valuutassasi.

Jokainen onnistunut kutsu maksaa sen vaatiman tekoälytyön todellisen kustannuksen kerrottuna Flixyn katteella, vähimmäishinnalla toimintoa kohden. Ennen sivustotehtävän alkua saldostasi varataan arvioitu summa; tarkka hinta veloitetaan lopuksi ja loput vapautetaan. Epäonnistuneista ja hylätyistä kutsuista ei koskaan veloiteta.

Webhookit

Lisää palvelimesi https-osoite kehittäjätilassasi ja valitse tapahtumat: job.succeeded, job.failed, balance.low, topup.succeeded. Flixy lähettää POST-pyynnön, jossa on JSON-tapahtuma; vastaa 2xx-tilalla 10 sekunnin kuluessa. Epäonnistuneita toimituksia yritetään uudelleen; toistuvasti epäonnistuva osoite keskeytetään.

POST /your/webhook
Flixy-Signature: t=1762854395,v1=8f0c3b…

{
  "id": "evt_2b0a…",
  "object": "event",
  "type": "job.succeeded",
  "created_at": "2026-11-11T09:46:35Z",
  "data": { "id": "job_6902…", "type": "site", "status": "succeeded", "site_id": "691589621", "price": 0.72 }
}

Tarkista allekirjoitus

Otsake Flixy-Signature sisältää aikaleiman t ja arvon v1, joka on HMAC-SHA256 merkkijonosta t + "." + raw body webhook-salaisuudellasi. Hylkää yli 5 minuuttia vanhat viestit.

import crypto from 'node:crypto';

export function verifyFlixy(rawBody, header, secret) {
  const p = Object.fromEntries(header.split(',').map((x) => x.split('=')));
  const sig = crypto.createHmac('sha256', secret).update(`${p.t}.${rawBody}`).digest('hex');
  return Math.abs(Date.now() / 1000 - Number(p.t)) < 300
    && crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(p.v1));
}

import hmac, hashlib, time

def verify_flixy(raw_body: bytes, header: str, secret: str) -> bool:
    p = dict(x.split('=', 1) for x in header.split(','))
    sig = hmac.new(secret.encode(), f"{p['t']}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return abs(time.time() - int(p['t'])) < 300 and hmac.compare_digest(sig, p['v1'])

function flixy_verify(string $raw, string $header, string $secret): bool {
    parse_str(str_replace(',', '&', $header), $p);
    $sig = hash_hmac('sha256', $p['t'] . '.' . $raw, $secret);
    return abs(time() - (int)$p['t']) < 300 && hash_equals($sig, (string)$p['v1']);
}

Laskutus

• Lataa saldoa alkaen 10 € kehittäjätilassasi kortilla. ALV lisätään maasi mukaan; jokaisesta latauksesta lähetetään lasku.
• Ota automaattinen lataus käyttöön, jotta valitsemasi summa ladataan, kun saldosi laskee alle kynnysarvon.
• Aseta tilille kuukausittainen kulukatto ja avainkohtainen päiväkatto.
• Saat sähköpostin ja balance.low-webhookin, kun saldosi on vähissä.

Täydelliset ehdot: Flixy API:n ehdot ja käyttökäytäntö.

Tietoturvan tarkistuslista

• Säilytä avaimet palvelimellasi, ympäristömuuttujissa tai salaisuuksien hallintatyökalussa — ei koskaan verkkosivulla, mobiilisovelluksessa tai koodivarastossa.
• Luo yksi avain sovellusta kohden ja anna sille vain tarvittavat oikeudet.
• Rajaa live-avaimet palvelimiesi IP-osoitteisiin ja aseta päiväkatto.
• Tarkista jokaisen webhookin allekirjoitus ja aikaleima.
• Käytä idempotenssiavainta jokaisessa POST-pyynnössä.
• Poista avain heti, jos se on voinut paljastua, ja luo sitten uusi.
• Tarkista tekoälyn tuottama sisältö ennen sen julkaisemista ja kerro käyttäjillesi, kun sisältö on tekoälyn tuottamaa, jos laki sitä edellyttää.

Käyttökäytäntö

Flixy API on tehty verkkosivustoille ja niiden sisällölle. Se hylkää veloituksetta verkkosivustoihin liittymättömät yleiset kysymykset, koodin muille ohjelmistoille, yritykset muuttaa Flixyn ohjeita sekä käytäntöjämme rikkovan sisällön (laiton, vihamielinen, alaikäisiä koskeva seksuaalinen sisältö, tietojenkalastelu- tai toisena esiintymisen sivut, roskaposti, valearvostelut). Lue API:n ehdot ja käyttökäytäntö kokonaisuudessaan.

Yhdistetty organisaatio

Yhdistä Flixy Studio -organisaatiosi konsolista (Organisaatio). Flixy Studio -tilin omistaja hyväksyy yhdistämisen ollessaan kirjautuneena Flixy Studioon, ja kumpi tahansa osapuoli voi poistaa sen milloin tahansa. Yhdistämisen jälkeen:

• API voi listata, lukea, muokata ja kääntää organisaation verkkosivustoja (sites:read, sites:write);
• voit luoda sivuston suoraan organisaatioon parametrilla "destination": "organization" tai siirtää API:n luoman sivuston kutsulla POST /v1/sites/{id}/transfer (maksuton) julkaistaksesi sen verkkotunnuksessa Flixy Studiosta;
• kaikki API-työ veloitetaan API-saldostasi: organisaation krediittejä ei koskaan käytetä.

curl "https://flixy.studio/v1/sites?owner=organization" \
  -H "Authorization: Bearer $FLIXY_API_KEY"

curl -X POST https://flixy.studio/v1/sites/691589621/transfer \
  -H "Authorization: Bearer $FLIXY_API_KEY"

{
  "id": "691589621",
  "object": "site",
  "owner": "organization",
  "dashboard_url": "https://flixy.studio/app/?v=sites",
  "editor_url": "https://flixy.studio/691589621"
}

Ilman yhdistettyä organisaatiota nämä kutsut palauttavat 409 organization_not_linked.

Muutosloki

• v1 — marraskuu 2026. Ensimmäinen versio: sivustot, muokkaukset, käännökset, sisältö, asiakirjojen lukeminen, kuvat, tehtävät, webhookit, ennakkoon maksettu saldo.

Muutoksista, jotka voivat rikkoa integraatiosi, ilmoitetaan sähköpostitse vähintään 90 päivää etukäteen.