Documentazione dell’API

Introduzione

La Flixy API permette al tuo software di usare le funzionalità di Flixy Studio: creare siti web completi a partire da una descrizione, modificarli e tradurli, scrivere contenuti per siti web, leggere menu, cataloghi e PDF, e creare immagini e loghi. Paghi solo le chiamate riuscite, da un saldo prepagato.

Le attività lunghe (creare, modificare o tradurre un sito web) vengono eseguite come job: l’API risponde subito e tu segui il job oppure ricevi un webhook. Contenuti, lettura di documenti e immagini rispondono direttamente, di solito in pochi secondi.

Console sviluppatori

Chiavi, saldo, ricariche, webhook e registro delle chiamate si gestiscono nella console sviluppatori su dev.flixy.studio.

• Un account sviluppatore separato. Come su altre piattaforme di IA, il tuo account sviluppatore è distinto dal tuo account Flixy Studio: ha registrazione, accesso e sessione propri. Uscire da uno non ti fa mai uscire dall’altro. Puoi usare lo stesso indirizzo email per entrambi.
• Organizzazione collegata. Se usi anche Flixy Studio, puoi collegare la tua organizzazione al tuo account sviluppatore, così l’API può lavorare sui suoi siti web. Vedi Organizzazione collegata.
• Sicurezza dell’account. Verifica in due passaggi, sessioni attive ed esportazione dei dati sono disponibili nella console, alla voce Account.

Autenticazione

Invia la tua chiave nell’header Authorization di ogni richiesta. Le chiavi iniziano con fx_live_ o fx_test_.

Authorization: Bearer fx_live_8sJ2…

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

Ogni chiave ha dei diritti (scope). Una chiamata senza lo scope corretto restituisce 403 missing_scope.

Chiavi di test e live

• Le chiavi di test (fx_test_…) sono gratuite. Restituiscono risposte di esempio realistiche senza usare l’IA, così puoi costruire e testare l’intera integrazione. I job dei siti web si completano dopo pochi secondi con un sito di esempio.
• Le chiavi live (fx_live_…) restituiscono risultati reali e vengono addebitate sul tuo saldo.

Ogni risposta contiene l’header Flixy-Mode: test o Flixy-Mode: live.

Richieste e risposte

Invia corpi JSON con Content-Type: application/json (16 MB al massimo). Le risposte sono in JSON. Le date usano ISO 8601 in UTC. Ogni risposta ha un header X-Request-Id: comunicalo al nostro supporto se hai bisogno di aiuto con una chiamata.

Imposta Accept-Language per ricevere i messaggi di errore nella tua lingua (fr, en, es, de, it, pt, nl, ca, el, sv, no, da, fi, is, et, lv, lt, ja; inglese per impostazione predefinita).

Errori

Gli errori usano i codici di stato HTTP standard e hanno sempre la stessa forma:

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

Limiti di frequenza

• 60 richieste al minuto per chiave (header X-RateLimit-Limit).
• 3 job di siti web contemporaneamente per account. Le chiamate per contenuti, documenti e immagini non sono soggette a questo limite.
• Quando viene raggiunto un limite, l’API risponde 429 con un header Retry-After in secondi.

Ti serve di più? Scrivi a contact@flixy.studio descrivendo il tuo caso d’uso.

Idempotenza

Gli errori di rete capitano. Aggiungi un header Idempotency-Key (da 8 a 100 caratteri, ad esempio il tuo ID ordine) a qualsiasi POST: se invii di nuovo la stessa richiesta entro 24 ore, l’API restituisce la prima risposta — con l’header Idempotent-Replayed: true — e non esegue né addebita mai il lavoro due volte.

Job

Creare, modificare e tradurre un sito web richiede da circa 30 secondi a 3 minuti. Questi endpoint rispondono 202 Accepted con un job. Seguilo ogni 5 secondi o attendi l’evento job.succeeded / job.failed via 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 è queued, running, succeeded o failed. Un job non riuscito non viene mai addebitato e il suo error ne spiega il motivo.

Creare un sito web

Crea un sito web completo a partire da una descrizione. Scope: 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']);

Recuperare un sito web

Restituisce il sito web, il suo stato e le sue pagine. Aggiungi include=html per ricevere l’HTML completo di ogni pagina (le immagini sono ospitate da Flixy). Scope: 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>…" }
}

Aggiungi owner=developer o owner=organization all’elenco per filtrare per proprietario. I siti web di un’organizzazione collegata restituiscono anche dashboard_url e editor_url, per aprirli in Flixy Studio.

Modificare un sito web

Applica una modifica descritta in linguaggio naturale, come nell’editor di Flixy. Ogni modifica crea una nuova versione. Scope: 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"}'

Tradurre un sito web

Traduce ogni pagina del sito web — navigazione, pulsanti, moduli, descrizioni delle immagini, titolo e descrizione per i motori di ricerca — mantenendo design, immagini, link, prezzi e recapiti. Scope: sites:write.

Scrivere contenuti web

Scrive contenuti destinati a essere pubblicati su un sito web o inviati da un’attività ai propri clienti. Risponde direttamente. Scope: 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" }
}

Il campo html contiene solo tag di testo sicuri (titoli, paragrafi, elenchi, link), mai script o stili.

Leggere un documento

Legge un menu, un catalogo, un listino prezzi, un biglietto da visita, un volantino o una brochure e restituisce contenuti strutturati pronti per un sito web. Viene restituito solo ciò che è realmente scritto. Scope: 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" }
}

Creare un’immagine

Crea una foto, un’illustrazione o un logo per un sito web. L’immagine è ospitata da Flixy e riporta all’interno del file la marcatura IPTC standard per i contenuti multimediali generati dall’IA. Scope: images:write.

Saldo e account

Restituisce il tuo saldo, l’importo riservato per i job in corso, l’importo disponibile, la spesa mensile e la chiave in uso. Scope: 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 }
}

Utilizzo e prezzi

/v1/usage restituisce le tue chiamate e gli importi per operazione in un periodo. /v1/pricing restituisce i prezzi tipici e minimi attuali nella tua valuta.

Ogni chiamata riuscita costa il costo reale del lavoro di IA che ha richiesto moltiplicato per il margine di Flixy, con un minimo per operazione. Prima dell’avvio di un job di sito web, un importo stimato viene riservato sul tuo saldo; il prezzo esatto viene addebitato alla fine e il resto viene sbloccato. Le chiamate non riuscite e rifiutate non vengono mai addebitate.

Webhook

Aggiungi un indirizzo https del tuo server nel tuo spazio sviluppatore e scegli gli eventi: job.succeeded, job.failed, balance.low, topup.succeeded. Flixy invia una POST con un evento JSON; rispondi con uno stato 2xx entro 10 secondi. Le consegne non riuscite vengono ritentate; un indirizzo che continua a fallire viene sospeso.

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

Verificare la firma

L’header Flixy-Signature contiene un timestamp t e v1, l’HMAC-SHA256 di t + "." + raw body con il tuo segreto webhook. Rifiuta i messaggi più vecchi di 5 minuti.

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

Fatturazione

• Ricarica il tuo saldo da 10 € nel tuo spazio sviluppatore, con carta. L’IVA viene aggiunta in base al tuo paese; per ogni ricarica viene inviata una fattura.
• Attiva la ricarica automatica per ricaricare un importo scelto quando il saldo scende sotto una soglia.
• Imposta un tetto di spesa mensile per l’account e un tetto giornaliero per chiave.
• Ricevi un’email e un webhook balance.low quando il saldo si sta esaurendo.

Condizioni complete: Condizioni e politica d’uso della Flixy API.

Checklist di sicurezza

• Conserva le chiavi sul tuo server, in variabili d’ambiente o in un gestore di segreti — mai in una pagina web, in un’app mobile o in un repository di codice.
• Crea una chiave per ogni applicazione e assegnale solo gli scope di cui ha bisogno.
• Limita le chiavi live agli indirizzi IP dei tuoi server e imposta un tetto giornaliero.
• Verifica la firma e il timestamp di ogni webhook.
• Usa una chiave di idempotenza per ogni POST.
• Elimina subito una chiave se potrebbe essere stata esposta, poi creane una nuova.
• Verifica i contenuti generati dall’IA prima di pubblicarli e informa i tuoi utenti quando un contenuto è generato dall’IA, ove la legge lo richieda.

Politica d’uso

La Flixy API è pensata per i siti web e i loro contenuti. Rifiuta, senza addebito, domande generiche non legate ai siti web, codice per altri software, tentativi di modificare le istruzioni di Flixy e contenuti che violano la nostra politica (illegali, d’odio, sessuali che coinvolgono minori, pagine di phishing o di impersonificazione, spam, recensioni false). Leggi le Condizioni e politica d’uso dell’API complete.

Organizzazione collegata

Collega la tua organizzazione Flixy Studio dalla console (Organizzazione). Il titolare dell’account Flixy Studio approva il collegamento dopo aver effettuato l’accesso a Flixy Studio, e ciascuna delle parti può rimuoverlo in qualsiasi momento. Una volta collegata:

• l’API può elencare, leggere, modificare e tradurre i siti web dell’organizzazione (sites:read, sites:write);
• puoi creare un sito web direttamente nell’organizzazione con "destination": "organization", oppure spostare un sito web creato dall’API con POST /v1/sites/{id}/transfer (gratuito), per pubblicarlo su un dominio da Flixy Studio;
• tutto il lavoro dell’API viene addebitato sul tuo saldo API: i crediti dell’organizzazione non vengono mai usati.

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

Senza un’organizzazione collegata, queste chiamate restituiscono 409 organization_not_linked.

Registro delle modifiche

• v1 — novembre 2026. Prima versione: siti web, modifiche, traduzioni, contenuti, lettura di documenti, immagini, job, webhook, saldo prepagato.

Le modifiche che potrebbero compromettere la tua integrazione vengono annunciate via email con almeno 90 giorni di anticipo.