API dokumentacija

Įvadas

Flixy API leidžia jūsų programinei įrangai naudoti Flixy Studio funkcijas: kurti visas svetaines pagal aprašymą, jas redaguoti ir versti, rašyti svetainių turinį, skaityti meniu, katalogus ir PDF failus, kurti paveikslėlius ir logotipus. Mokate tik už sėkmingus iškvietimus, iš išankstinio mokėjimo likučio.

Ilgos užduotys (svetainės kūrimas, redagavimas ar vertimas) vykdomos kaip užduotys: API iš karto atsako, o jūs sekate užduotį arba gaunate webhook. Turinys, dokumentų skaitymas ir paveikslėliai atsako tiesiogiai, paprastai per kelias sekundes.

Kūrėjų konsolė

Raktai, likutis, papildymai, webhooks ir iškvietimų žurnalai valdomi kūrėjų konsolėje adresu dev.flixy.studio.

• Atskira kūrėjo paskyra. Kaip ir kitose DI platformose, jūsų kūrėjo paskyra yra atskirta nuo jūsų Flixy Studio paskyros: ji turi savo registraciją, prisijungimą ir sesiją. Atsijungus nuo vienos, niekada neatsijungiama nuo kitos. Abiem galite naudoti tą patį el. pašto adresą.
• Susieta organizacija. Jei naudojate ir Flixy Studio, galite susieti savo organizaciją su kūrėjo paskyra, kad API galėtų dirbti su jos svetainėmis. Žr. Susieta organizacija.
• Paskyros sauga. Dviejų veiksmų patvirtinimas, aktyvios sesijos ir duomenų eksportas pasiekiami konsolėje, skiltyje Paskyra.

Autentifikavimas

Siųskite savo raktą kiekvienos užklausos antraštėje Authorization. Raktai prasideda fx_live_ arba fx_test_.

Authorization: Bearer fx_live_8sJ2…

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

Kiekvienas raktas turi teises (scopes). Iškvietimas be tinkamos teisės grąžina 403 missing_scope.

Bandomieji ir live raktai

• Bandomieji raktai (fx_test_…) nemokami. Jie grąžina realistiškus pavyzdinius atsakymus nenaudodami DI, todėl galite sukurti ir išbandyti visą integraciją. Svetainių užduotys baigiamos po kelių sekundžių su pavyzdine svetaine.
• Live raktai (fx_live_…) grąžina tikrus rezultatus ir apmokestinami iš jūsų likučio.

Kiekviename atsakyme yra antraštė Flixy-Mode: test arba Flixy-Mode: live.

Užklausos ir atsakymai

Siųskite JSON turinį su Content-Type: application/json (daugiausia 16 MB). Atsakymai pateikiami JSON formatu. Datos nurodomos ISO 8601 formatu UTC laiku. Kiekvienas atsakymas turi antraštę X-Request-Id: nurodykite ją mūsų pagalbos tarnybai, jei jums reikia pagalbos dėl iškvietimo.

Nustatykite Accept-Language, kad klaidų pranešimus gautumėte savo kalba (fr, en, es, de, it, pt, nl, ca, el, sv, no, da, fi, is, et, lv, lt, ja; numatytoji – anglų).

Klaidos

Klaidoms naudojami standartiniai HTTP būsenos kodai, jos visada būna tokios pačios formos:

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

Užklausų limitai

• 60 užklausų per minutę vienam raktui (antraštė X-RateLimit-Limit).
• 3 svetainių užduotys vienu metu vienai paskyrai. Turinio, dokumentų ir paveikslėlių iškvietimams šis limitas netaikomas.
• Pasiekus limitą, API atsako 429 su antrašte Retry-After sekundėmis.

Reikia daugiau? Parašykite adresu contact@flixy.studio ir aprašykite savo naudojimo atvejį.

Idempotencija

Tinklo klaidų pasitaiko. Pridėkite antraštę Idempotency-Key (nuo 8 iki 100 simbolių, pavyzdžiui, savo užsakymo ID) prie bet kurio POST: jei tą pačią užklausą išsiųsite dar kartą per 24 valandas, API grąžins pirmąjį atsakymą — su antrašte Idempotent-Replayed: true — ir niekada nevykdys bei neapmokestins darbo du kartus.

Užduotys

Svetainės kūrimas, redagavimas ir vertimas trunka nuo maždaug 30 sekundžių iki 3 minučių. Šie galiniai taškai atsako 202 Accepted su užduotimi. Tikrinkite ją kas 5 sekundes arba laukite job.succeeded / job.failed webhook.

{
  "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 yra queued, running, succeeded arba failed. Nepavykusi užduotis niekada neapmokestinama, o jos error paaiškina priežastį.

Sukurti svetainę

Sukuria visą svetainę pagal aprašymą. Teisė: 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']);

Gauti svetainę

Grąžina svetainę, jos būseną ir puslapius. Pridėkite include=html, kad gautumėte visą kiekvieno puslapio HTML (paveikslėliai talpinami Flixy). Teisė: 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>…" }
}

Norėdami filtruoti pagal savininką, prie sąrašo pridėkite owner=developer arba owner=organization. Susietos organizacijos svetainės taip pat grąžina dashboard_url ir editor_url, kad jas būtų galima atidaryti Flixy Studio.

Redaguoti svetainę

Pritaiko paprasta kalba aprašytą pakeitimą, kaip Flixy redaktoriuje. Kiekvienas pakeitimas sukuria naują versiją. Teisė: 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"}'

Išversti svetainę

Išverčia kiekvieną svetainės puslapį — navigaciją, mygtukus, formas, paveikslėlių aprašymus, pavadinimą ir aprašymą paieškos sistemoms — išlaikydamas dizainą, paveikslėlius, nuorodas, kainas ir kontaktinius duomenis. Teisė: sites:write.

Rašyti interneto turinį

Rašo turinį, skirtą skelbti svetainėje arba verslo siunčiamą savo klientams. Atsako tiesiogiai. Teisė: 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" }
}

Laukelyje html yra tik saugios teksto žymos (antraštės, pastraipos, sąrašai, nuorodos), niekada scenarijų ar stilių.

Perskaityti dokumentą

Perskaito meniu, katalogą, kainoraštį, vizitinę kortelę, skrajutę ar brošiūrą ir grąžina struktūrizuotą turinį, paruoštą svetainei. Grąžinama tik tai, kas iš tikrųjų parašyta. Teisė: 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" }
}

Sukurti paveikslėlį

Sukuria nuotrauką, iliustraciją ar logotipą svetainei. Paveikslėlis talpinamas Flixy ir faile turi standartinį IPTC žymėjimą, skirtą DI sugeneruotai medijai. Teisė: images:write.

Likutis ir paskyra

Grąžina jūsų likutį, vykdomoms užduotims rezervuotą sumą, laisvą sumą, mėnesio išlaidas ir naudojamą raktą. Teisė: 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 }
}

Naudojimas ir kainos

/v1/usage grąžina jūsų iškvietimus ir sumas pagal operaciją per laikotarpį. /v1/pricing grąžina dabartines tipines ir minimalias kainas jūsų valiuta.

Kiekvienas sėkmingas iškvietimas kainuoja tiek, kiek realiai kainavo jam reikalingas DI darbas, padauginus iš Flixy maržos, taikant minimalią kainą už operaciją. Prieš pradedant svetainės užduotį, jūsų likutyje rezervuojama apskaičiuota suma; tiksli kaina nuskaičiuojama pabaigoje, o likusi suma atlaisvinama. Nepavykę ir atmesti iškvietimai niekada neapmokestinami.

Webhook

Savo kūrėjo erdvėje pridėkite savo serverio https adresą ir pasirinkite įvykius: job.succeeded, job.failed, balance.low, topup.succeeded. Flixy siunčia POST su JSON įvykiu; atsakykite 2xx būsena per 10 sekundžių. Nepavykę pristatymai kartojami; nuolat nepavykstantis adresas pristabdomas.

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

Patikrinkite parašą

Antraštėje Flixy-Signature yra laiko žyma t ir v1 — t + "." + raw body HMAC-SHA256, apskaičiuotas su jūsų webhook slaptažodžiu. Atmeskite senesnius nei 5 minučių pranešimus.

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']);
}

Sąskaitos

• Papildykite savo likutį nuo 10 € savo kūrėjo erdvėje kortele. PVM pridedamas pagal jūsų šalį; už kiekvieną papildymą išsiunčiama sąskaita faktūra.
• Įjunkite automatinį papildymą, kad pasirinkta suma būtų papildyta, kai jūsų likutis nukrenta žemiau nustatytos ribos.
• Nustatykite mėnesio išlaidų limitą paskyrai ir dienos limitą kiekvienam raktui.
• Kai jūsų likutis mažėja, gaunate el. laišką ir balance.low webhook.

Visos sąlygos: Flixy API sąlygos ir naudojimo politika.

Saugumo kontrolinis sąrašas

• Laikykite raktus savo serveryje, aplinkos kintamuosiuose arba slaptųjų duomenų tvarkyklėje — niekada ne tinklalapyje, mobiliojoje programėlėje ar kodo saugykloje.
• Kiekvienai programai sukurkite atskirą raktą ir suteikite jam tik reikalingas teises.
• Apribokite live raktus savo serverių IP adresais ir nustatykite dienos limitą.
• Patikrinkite kiekvieno webhook parašą ir laiko žymą.
• Kiekvienam POST naudokite idempotencijos raktą.
• Nedelsdami ištrinkite raktą, jei jis galėjo būti atskleistas, tada sukurkite naują.
• Peržiūrėkite DI sugeneruotą turinį prieš jį paskelbdami ir informuokite savo naudotojus, kai turinys sugeneruotas DI, jei to reikalauja įstatymai.

Naudojimo politika

Flixy API skirta svetainėms ir jų turiniui. Ji be mokesčio atmeta su svetainėmis nesusijusius bendruosius klausimus, kodą kitai programinei įrangai, bandymus pakeisti Flixy instrukcijas ir mūsų politiką pažeidžiantį turinį (neteisėtą, neapykantą kurstantį, seksualinio pobūdžio turinį, susijusį su nepilnamečiais, sukčiavimo ar apsimetinėjimo puslapius, šlamštą, netikrus atsiliepimus). Perskaitykite visas API sąlygas ir naudojimo politiką.

Susieta organizacija

Susiekite savo Flixy Studio organizaciją konsolėje (Organizacija). Flixy Studio paskyros savininkas patvirtina susiejimą prisijungęs prie Flixy Studio, ir bet kuri šalis gali jį bet kada pašalinti. Susiejus:

• API gali pateikti organizacijos svetainių sąrašą, jas skaityti, redaguoti ir versti (sites:read, sites:write);
• galite sukurti svetainę tiesiai organizacijoje su "destination": "organization" arba perkelti API sukurtą svetainę su POST /v1/sites/{id}/transfer (nemokamai), kad paskelbtumėte ją domene iš Flixy Studio;
• visas API darbas apmokestinamas iš jūsų API likučio: organizacijos kreditai niekada nenaudojami.

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

Nesant susietos organizacijos, šie iškvietimai grąžina 409 organization_not_linked.

Pakeitimų žurnalas

• v1 — 2026 m. lapkritis. Pirmoji versija: svetainės, pakeitimai, vertimai, turinys, dokumentų skaitymas, paveikslėliai, užduotys, webhook, išankstinio mokėjimo likutis.

Pakeitimai, galintys sutrikdyti jūsų integraciją, el. paštu paskelbiami ne vėliau kaip prieš 90 dienų.