Documentació de l’API

Introducció

La Flixy API permet al teu programari utilitzar les funcions de Flixy Studio: crear llocs web complets a partir d’una descripció, editar-los i traduir-los, redactar contingut web, llegir menús, catàlegs i PDF, i crear imatges i logotips. Només pagues les crides correctes, amb un saldo prepagat.

Les tasques llargues (crear, editar o traduir un lloc web) s’executen com a tasques asíncrones: l’API respon immediatament i tu segueixes la tasca o reps un webhook. El contingut, la lectura de documents i les imatges responen directament, normalment en pocs segons.

Consola de desenvolupadors

Les claus, el saldo, les recàrregues, els webhooks i el registre de crides es gestionen a la consola de desenvolupadors a dev.flixy.studio.

• Un compte de desenvolupador independent. Com en altres plataformes d’IA, el teu compte de desenvolupador és diferent del teu compte de Flixy Studio: té el seu propi registre, inici de sessió i sessió. Tancar la sessió en un no la tanca mai en l’altre. Pots utilitzar la mateixa adreça electrònica per a tots dos.
• Organització vinculada. Si també utilitzes Flixy Studio, pots vincular la teva organització al teu compte de desenvolupador perquè l’API pugui treballar en els seus llocs web. Consulta Organització vinculada.
• Seguretat del compte. La verificació en dos passos, les sessions actives i l’exportació de dades estan disponibles a la consola, a Compte.

Autenticació

Envia la teva clau a la capçalera Authorization de cada sol·licitud. Les claus comencen per fx_live_ o fx_test_.

Authorization: Bearer fx_live_8sJ2…

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

Cada clau té permisos (scopes). Una crida sense el permís necessari retorna 403 missing_scope.

Claus de prova i live

• Les claus de prova (fx_test_…) són gratuïtes. Retornen respostes d’exemple realistes sense utilitzar IA, perquè puguis construir i provar tota la integració. Les tasques de lloc web acaben al cap de pocs segons amb un lloc d’exemple.
• Les claus live (fx_live_…) retornen resultats reals i es cobren del teu saldo.

Cada resposta conté la capçalera Flixy-Mode: test o Flixy-Mode: live.

Sol·licituds i respostes

Envia cossos JSON amb Content-Type: application/json (16 MB com a màxim). Les respostes són JSON. Les dates fan servir ISO 8601 en UTC. Cada resposta té una capçalera X-Request-Id: facilita-la al nostre suport si necessites ajuda amb una crida.

Defineix Accept-Language per rebre els missatges d’error en el teu idioma (fr, en, es, de, it, pt, nl, ca, el, sv, no, da, fi, is, et, lv, lt, ja; anglès per defecte).

Errors

Els errors fan servir codis d’estat HTTP estàndard i sempre tenen la mateixa forma:

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

Límits d’ús

• 60 sol·licituds per minut per clau (capçalera X-RateLimit-Limit).
• 3 tasques de lloc web alhora per compte. Les crides de contingut, documents i imatges no estan subjectes a aquest límit.
• Quan s’arriba a un límit, l’API respon 429 amb una capçalera Retry-After en segons.

Necessites més? Escriu a contact@flixy.studio explicant el teu cas d’ús.

Idempotència

Els errors de xarxa passen. Afegeix una capçalera Idempotency-Key (de 8 a 100 caràcters, per exemple el teu propi identificador de comanda) a qualsevol POST: si tornes a enviar la mateixa sol·licitud en un termini de 24 hores, l’API retorna la primera resposta — amb la capçalera Idempotent-Replayed: true — i no executa ni cobra mai la feina dues vegades.

Tasques

Crear, editar i traduir un lloc web triga d’uns 30 segons a 3 minuts. Aquests endpoints responen 202 Accepted amb una tasca. Consulta-la cada 5 segons o espera els esdeveniments job.succeeded / job.failed del 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 és queued, running, succeeded o failed. Una tasca fallida no es cobra mai i el seu error n’explica el motiu.

Crear un lloc web

Crea un lloc web complet a partir d’una descripció. Permís: 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']);

Obtenir un lloc web

Retorna el lloc web, el seu estat i les seves pàgines. Afegeix include=html per rebre l’HTML complet de cada pàgina (les imatges les allotja Flixy). Permís: 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>…" }
}

Afegeix owner=developer o owner=organization a la llista per filtrar per propietari. Els llocs web d’una organització vinculada també retornen dashboard_url i editor_url, per obrir-los a Flixy Studio.

Editar un lloc web

Aplica un canvi descrit en llenguatge natural, com a l’editor de Flixy. Cada canvi crea una versió nova. Permís: 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"}'

Traduir un lloc web

Tradueix cada pàgina del lloc web — navegació, botons, formularis, descripcions d’imatges, títol i descripció per als cercadors — mantenint el disseny, les imatges, els enllaços, els preus i les dades de contacte. Permís: sites:write.

Redactar contingut web

Redacta contingut destinat a publicar-se en un lloc web o a ser enviat per un negoci als seus clients. Respon directament. Permís: 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" }
}

El camp html només conté etiquetes de text segures (títols, paràgrafs, llistes, enllaços), mai scripts ni estils.

Llegir un document

Llegeix un menú, un catàleg, una llista de preus, una targeta de visita, un flyer o un fullet i retorna contingut estructurat a punt per a un lloc web. Només es retorna el que hi ha realment escrit. Permís: 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" }
}

Crear una imatge

Crea una foto, una il·lustració o un logotip per a un lloc web. La imatge l’allotja Flixy i porta dins el fitxer el marcatge IPTC estàndard per a contingut multimèdia generat per IA. Permís: images:write.

Saldo i compte

Retorna el teu saldo, l’import reservat per a tasques en curs, l’import disponible, la teva despesa mensual i la clau en ús. Permís: 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 }
}

Ús i preus

/v1/usage retorna les teves crides i imports per operació en un període. /v1/pricing retorna els preus habituals i mínims actuals en la teva moneda.

Cada crida correcta costa el cost real de la feina d’IA que ha requerit multiplicat pel marge de Flixy, amb un mínim per operació. Abans que comenci una tasca de lloc web, es reserva un import estimat al teu saldo; el preu exacte es cobra al final i la resta s’allibera. Les crides fallides i rebutjades no es cobren mai.

Webhooks

Afegeix una adreça https del teu servidor al teu espai de desenvolupador i tria els esdeveniments: job.succeeded, job.failed, balance.low, topup.succeeded. Flixy envia un POST amb un esdeveniment JSON; respon amb un estat 2xx en menys de 10 segons. Els enviaments fallits es reintenten; una adreça que falla repetidament es posa en pausa.

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

Verificar la signatura

La capçalera Flixy-Signature conté una marca de temps t i v1, l’HMAC-SHA256 de t + "." + raw body amb el teu secret de webhook. Rebutja els missatges de més de 5 minuts d’antiguitat.

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

Facturació

• Recarrega el teu saldo des de 10 € al teu espai de desenvolupador, amb targeta. L’IVA s’afegeix segons el teu país; s’envia una factura per cada recàrrega.
• Activa la recàrrega automàtica per recarregar l’import que triïs quan el teu saldo baixi d’un llindar.
• Fixa un límit de despesa mensual per al compte i un límit diari per clau.
• Reps un correu electrònic i un webhook balance.low quan el teu saldo és baix.

Condicions completes: Condicions i política d’ús de la Flixy API.

Llista de seguretat

• Guarda les claus al teu servidor, en variables d’entorn o en un gestor de secrets — mai en una pàgina web, una app mòbil o un repositori de codi.
• Crea una clau per aplicació i dona-li només els permisos que necessita.
• Restringeix les claus live a les adreces IP dels teus servidors i fixa un límit diari.
• Verifica la signatura de cada webhook i la seva marca de temps.
• Utilitza una clau d’idempotència en cada POST.
• Elimina una clau immediatament si pot haver quedat exposada i, després, crea’n una de nova.
• Revisa el contingut generat per IA abans de publicar-lo, i informa els teus usuaris que un contingut està generat per IA quan la llei ho exigeixi.

Política d’ús

La Flixy API està feta per a llocs web i el seu contingut. Rebutja, sense cobrar, preguntes generals sense relació amb llocs web, codi per a altres programes, intents de canviar les instruccions de Flixy i contingut que incompleix la nostra política (contingut il·legal, d’odi, sexual que impliqui menors, pàgines de pesca de dades o de suplantació, spam, ressenyes falses). Llegeix les Condicions i política d’ús de l’API completes.

Organització vinculada

Vincula la teva organització de Flixy Studio des de la consola (Organització). El propietari del compte de Flixy Studio aprova la vinculació amb la sessió iniciada a Flixy Studio, i qualsevol de les parts la pot eliminar en qualsevol moment. Un cop vinculada:

• l’API pot llistar, llegir, editar i traduir els llocs web de l’organització (sites:read, sites:write);
• pots crear un lloc web directament a l’organització amb "destination": "organization", o moure un lloc web creat per l’API amb POST /v1/sites/{id}/transfer (gratuït), per publicar-lo en un domini des de Flixy Studio;
• tota la feina de l’API es cobra del teu saldo de l’API: els crèdits de l’organització no s’utilitzen mai.

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

Sense una organització vinculada, aquestes crides retornen 409 organization_not_linked.

Registre de canvis

• v1 — novembre de 2026. Primera versió: llocs web, edicions, traduccions, contingut, lectura de documents, imatges, tasques, webhooks, saldo prepagat.

Els canvis que puguin trencar la teva integració s’anuncien per correu electrònic amb almenys 90 dies d’antelació.