API-Dokumentation

Einführung

Mit der Flixy API kann Ihre Software die Funktionen von Flixy Studio nutzen: komplette Websites aus einer Beschreibung erstellen, sie bearbeiten und übersetzen, Website-Inhalte schreiben, Speisekarten, Kataloge und PDFs auslesen sowie Bilder und Logos erstellen. Sie zahlen nur für erfolgreiche Aufrufe, aus einem Prepaid-Guthaben.

Lange Aufgaben (Erstellen, Bearbeiten oder Übersetzen einer Website) laufen als Jobs: Die API antwortet sofort, und Sie verfolgen den Job oder erhalten einen Webhook. Inhalte, das Auslesen von Dokumenten und Bilder antworten direkt, meist in wenigen Sekunden.

Entwicklerkonsole

Schlüssel, Guthaben, Aufladungen, Webhooks und Aufrufprotokolle verwalten Sie in der Entwicklerkonsole unter dev.flixy.studio.

• Ein separates Entwicklerkonto. Wie bei anderen KI-Plattformen ist Ihr Entwicklerkonto von Ihrem Flixy Studio-Konto getrennt: Es hat eine eigene Registrierung, eine eigene Anmeldung und eine eigene Sitzung. Wenn Sie sich bei einem abmelden, werden Sie nie beim anderen abgemeldet. Sie können für beide dieselbe E-Mail-Adresse verwenden.
• Verknüpfte Organisation. Wenn Sie auch Flixy Studio nutzen, können Sie Ihre Organisation mit Ihrem Entwicklerkonto verknüpfen, damit die API an deren Websites arbeiten kann. Siehe Verknüpfte Organisation.
• Kontosicherheit. Zwei-Schritt-Verifizierung, aktive Sitzungen und Datenexport finden Sie in der Konsole unter Konto.

Authentifizierung

Senden Sie Ihren Schlüssel im Header Authorization jeder Anfrage. Schlüssel beginnen mit fx_live_ oder fx_test_.

Authorization: Bearer fx_live_8sJ2…

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

Jeder Schlüssel hat Berechtigungen (Scopes). Ein Aufruf ohne die passende Berechtigung liefert 403 missing_scope.

Test- und Live-Schlüssel

• Testschlüssel (fx_test_…) sind kostenlos. Sie liefern realistische Beispielantworten ohne KI-Nutzung, sodass Sie Ihre gesamte Integration entwickeln und testen können. Website-Jobs werden nach wenigen Sekunden mit einer Beispiel-Website abgeschlossen.
• Live-Schlüssel (fx_live_…) liefern echte Ergebnisse und werden von Ihrem Guthaben abgebucht.

Jede Antwort enthält den Header Flixy-Mode: test oder Flixy-Mode: live.

Anfragen und Antworten

Senden Sie JSON-Bodys mit Content-Type: application/json (maximal 16 MB). Antworten sind JSON. Datumsangaben verwenden ISO 8601 in UTC. Jede Antwort hat einen Header X-Request-Id: Geben Sie ihn unserem Support, wenn Sie Hilfe zu einem Aufruf benötigen.

Setzen Sie Accept-Language, um Fehlermeldungen in Ihrer Sprache zu erhalten (fr, en, es, de, it, pt, nl, ca, el, sv, no, da, fi, is, et, lv, lt, ja; standardmäßig Englisch).

Fehler

Fehler verwenden Standard-HTTP-Statuscodes und haben immer dieselbe Form:

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

Rate Limits

• 60 Anfragen pro Minute pro Schlüssel (Header X-RateLimit-Limit).
• 3 Website-Jobs gleichzeitig pro Konto. Aufrufe für Inhalte, Dokumente und Bilder sind davon nicht betroffen.
• Wenn ein Limit erreicht ist, antwortet die API mit 429 und einem Header Retry-After in Sekunden.

Mehr nötig? Schreiben Sie an contact@flixy.studio und beschreiben Sie Ihren Anwendungsfall.

Idempotenz

Netzwerkfehler kommen vor. Fügen Sie einen Header Idempotency-Key (8 bis 100 Zeichen, zum Beispiel Ihre eigene Bestellnummer) zu jedem POST hinzu: Wenn Sie dieselbe Anfrage innerhalb von 24 Stunden erneut senden, liefert die API die erste Antwort – mit dem Header Idempotent-Replayed: true – und führt die Arbeit nie doppelt aus oder berechnet sie doppelt.

Jobs

Das Erstellen, Bearbeiten und Übersetzen einer Website dauert etwa 30 Sekunden bis 3 Minuten. Diese Endpunkte antworten mit 202 Accepted und einem Job. Fragen Sie ihn alle 5 Sekunden ab oder warten Sie auf das Ereignis job.succeeded / job.failed per 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 ist queued, running, succeeded oder failed. Ein fehlgeschlagener Job wird nie berechnet, und sein error erklärt den Grund.

Website erstellen

Erstellt eine komplette Website aus einer Beschreibung. Berechtigung: 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']);

Website abrufen

Liefert die Website, ihren Status und ihre Seiten. Fügen Sie include=html hinzu, um das vollständige HTML jeder Seite zu erhalten (Bilder werden von Flixy gehostet). Berechtigung: 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>…" }
}

Fügen Sie der Liste owner=developer oder owner=organization hinzu, um nach Eigentümer zu filtern. Websites einer verknüpften Organisation liefern außerdem dashboard_url und editor_url, um sie in Flixy Studio zu öffnen.

Website bearbeiten

Wendet eine in Alltagssprache beschriebene Änderung an, wie im Flixy-Editor. Jede Änderung erzeugt eine neue Version. Berechtigung: 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"}'

Website übersetzen

Übersetzt jede Seite der Website – Navigation, Buttons, Formulare, Bildbeschreibungen, Titel und Beschreibung für Suchmaschinen – und behält Design, Bilder, Links, Preise und Kontaktdaten bei. Berechtigung: sites:write.

Webinhalte schreiben

Schreibt Inhalte, die auf einer Website veröffentlicht oder von einem Unternehmen an seine Kunden gesendet werden sollen. Antwortet direkt. Berechtigung: 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" }
}

Das Feld html enthält nur sichere Text-Tags (Überschriften, Absätze, Listen, Links), nie Skripte oder Styles.

Dokument auslesen

Liest eine Speisekarte, einen Katalog, eine Preisliste, eine Visitenkarte, einen Flyer oder eine Broschüre aus und liefert strukturierte Inhalte, bereit für eine Website. Es wird nur zurückgegeben, was tatsächlich geschrieben steht. Berechtigung: 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" }
}

Bild erstellen

Erstellt ein Foto, eine Illustration oder ein Logo für eine Website. Das Bild wird von Flixy gehostet und trägt in der Datei die standardisierte IPTC-Kennzeichnung für KI-generierte Medien. Berechtigung: images:write.

Guthaben und Konto

Liefert Ihr Guthaben, den für laufende Jobs reservierten Betrag, den verfügbaren Betrag, Ihre monatlichen Ausgaben und den verwendeten Schlüssel. Berechtigung: 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 }
}

Nutzung und Preise

/v1/usage liefert Ihre Aufrufe und Beträge pro Vorgang über einen Zeitraum. /v1/pricing liefert die aktuellen typischen und Mindestpreise in Ihrer Währung.

Jeder erfolgreiche Aufruf kostet die tatsächlichen Kosten der dafür nötigen KI-Arbeit, multipliziert mit der Marge von Flixy, mit einem Mindestpreis pro Vorgang. Bevor ein Website-Job startet, wird ein geschätzter Betrag auf Ihrem Guthaben reserviert; der exakte Preis wird am Ende abgebucht und der Rest freigegeben. Fehlgeschlagene und abgelehnte Aufrufe werden nie berechnet.

Webhooks

Fügen Sie in Ihrem Entwicklerbereich eine https-Adresse Ihres Servers hinzu und wählen Sie die Ereignisse: job.succeeded, job.failed, balance.low, topup.succeeded. Flixy sendet einen POST mit einem JSON-Ereignis; antworten Sie innerhalb von 10 Sekunden mit einem 2xx-Status. Fehlgeschlagene Zustellungen werden wiederholt; eine Adresse, die dauerhaft fehlschlägt, wird pausiert.

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

Signatur prüfen

Der Header Flixy-Signature enthält einen Zeitstempel t und v1, den HMAC-SHA256 von t + "." + raw body mit Ihrem Webhook-Secret. Lehnen Sie Nachrichten ab, die älter als 5 Minuten sind.

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

Abrechnung

• Laden Sie Ihr Guthaben ab 10 € in Ihrem Entwicklerbereich per Karte auf. Die MwSt. wird je nach Land hinzugefügt; für jede Aufladung wird eine Rechnung gesendet.
• Aktivieren Sie die automatische Aufladung, um einen gewählten Betrag aufzuladen, wenn Ihr Guthaben unter einen Schwellenwert fällt.
• Legen Sie ein monatliches Ausgabenlimit für das Konto und ein Tageslimit pro Schlüssel fest.
• Sie erhalten eine E-Mail und einen Webhook balance.low, wenn Ihr Guthaben knapp wird.

Vollständige Bedingungen: Flixy API-Bedingungen & Nutzungsrichtlinie.

Sicherheits-Checkliste

• Bewahren Sie Schlüssel auf Ihrem Server auf, in Umgebungsvariablen oder einem Secrets-Manager – nie in einer Webseite, einer mobilen App oder einem Code-Repository.
• Erstellen Sie einen Schlüssel pro Anwendung und geben Sie ihm nur die Berechtigungen, die er braucht.
• Beschränken Sie Live-Schlüssel auf die IP-Adressen Ihrer Server und legen Sie ein Tageslimit fest.
• Prüfen Sie die Signatur und den Zeitstempel jedes Webhooks.
• Verwenden Sie für jeden POST einen Idempotenzschlüssel.
• Löschen Sie einen Schlüssel sofort, wenn er offengelegt worden sein könnte, und erstellen Sie dann einen neuen.
• Prüfen Sie KI-generierte Inhalte vor der Veröffentlichung und informieren Sie Ihre Nutzer, wenn Inhalte KI-generiert sind, sofern das Gesetz dies verlangt.

Nutzungsrichtlinie

Die Flixy API ist für Websites und deren Inhalte gemacht. Sie lehnt kostenlos allgemeine Fragen ohne Website-Bezug, Code für andere Software, Versuche, die Anweisungen von Flixy zu ändern, und Inhalte ab, die gegen unsere Richtlinie verstoßen (illegale, hasserfüllte, sexuelle Inhalte mit Minderjährigen, Phishing- oder Identitätsbetrugsseiten, Spam, gefälschte Bewertungen). Lesen Sie die vollständigen API-Bedingungen & Nutzungsrichtlinie.

Verknüpfte Organisation

Verknüpfen Sie Ihre Flixy Studio-Organisation in der Konsole (Organisation). Der Inhaber des Flixy Studio-Kontos genehmigt die Verknüpfung, während er bei Flixy Studio angemeldet ist, und beide Seiten können sie jederzeit aufheben. Nach der Verknüpfung gilt:

• die API kann die Websites der Organisation auflisten, lesen, bearbeiten und übersetzen (sites:read, sites:write);
• Sie können mit "destination": "organization" eine Website direkt in der Organisation erstellen oder eine über die API erstellte Website mit POST /v1/sites/{id}/transfer (kostenlos) verschieben, um sie über Flixy Studio auf einer Domain zu veröffentlichen;
• die gesamte API-Arbeit wird Ihrem API-Guthaben belastet: Die Credits der Organisation werden nie verwendet.

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

Ohne verknüpfte Organisation geben diese Aufrufe 409 organization_not_linked zurück.

Änderungsprotokoll

• v1 — November 2026. Erste Version: Websites, Änderungen, Übersetzungen, Inhalte, Dokumente auslesen, Bilder, Jobs, Webhooks, Prepaid-Guthaben.

Änderungen, die Ihre Integration beeinträchtigen könnten, werden mindestens 90 Tage im Voraus per E-Mail angekündigt.