API documentation

Introduction

The Flixy API lets your software use the features of Flixy Studio: create complete websites from a description, edit and translate them, write website content, read menus, catalogues and PDFs, and create images and logos. You pay only for successful calls, from a prepaid balance.

Long tasks (creating, editing or translating a website) run as jobs: the API answers immediately and you follow the job or receive a webhook. Content, document reading and images answer directly, usually in a few seconds.

Developer console

Keys, balance, top-ups, webhooks and call logs are managed in the developer console at dev.flixy.studio.

• A separate developer account. Like other AI platforms, your developer account is distinct from your Flixy Studio account: it has its own sign-up, sign-in and session. Signing out of one never signs you out of the other. You can use the same email address for both.
• Linked organization. If you also use Flixy Studio, you can link your organization to your developer account, so the API can work on its websites. See Linked organization.
• Account security. Two-step verification, active sessions and data export are available in the console, under Account.

Authentication

Send your key in the Authorization header of every request. Keys start with fx_live_ or fx_test_.

Authorization: Bearer fx_live_8sJ2…

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

Each key has rights (scopes). A call without the right scope returns 403 missing_scope.

Test and live keys

• Test keys (fx_test_…) are free. They return realistic sample responses without using AI, so you can build and test your whole integration. Website jobs complete after a few seconds with a sample website.
• Live keys (fx_live_…) return real results and are charged on your balance.

Every response contains the header Flixy-Mode: test or Flixy-Mode: live.

Requests and responses

Send JSON bodies with Content-Type: application/json (16 MB maximum). Responses are JSON. Dates use ISO 8601 in UTC. Every response has an X-Request-Id header: give it to our support if you need help with a call.

Set Accept-Language to receive error messages in your language (fr, en, es, de, it, pt, nl, ca, el, sv, no, da, fi, is, et, lv, lt, ja; English by default).

Errors

Errors use standard HTTP status codes and always have the same shape:

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

Rate limits

• 60 requests per minute per key (header X-RateLimit-Limit).
• 3 website jobs at the same time per account. Content, document and image calls are not limited by this.
• When a limit is reached, the API answers 429 with a Retry-After header in seconds.

Need more? Write to contact@flixy.studio with your use case.

Idempotency

Network errors happen. Add an Idempotency-Key header (8 to 100 characters, for example your own order ID) to any POST: if you send the same request again within 24 hours, the API returns the first response — with the header Idempotent-Replayed: true — and never runs or charges the work twice.

Jobs

Creating, editing and translating a website take from about 30 seconds to 3 minutes. These endpoints answer 202 Accepted with a job. Follow it every 5 seconds or wait for the 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 is queued, running, succeeded or failed. A failed job is never charged and its error explains why.

Create a website

Creates a complete website from a description. 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']);

Retrieve a website

Returns the website, its status and its pages. Add include=html to receive the complete HTML of every page (images are hosted by 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>…" }
}

Add owner=developer or owner=organization to the list to filter by owner. Websites of a linked organization also return dashboard_url and editor_url, to open them in Flixy Studio.

Edit a website

Applies a change described in plain language, like in the Flixy editor. Every change creates a new version. 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"}'

Translate a website

Translates every page of the website — navigation, buttons, forms, image descriptions, title and description for search engines — while keeping the design, images, links, prices and contact details. Scope: sites:write.

Write web content

Writes content meant to be published on a website or sent by a business to its customers. Answers directly. 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" }
}

The html field only contains safe text tags (headings, paragraphs, lists, links), never scripts or styles.

Read a document

Reads a menu, a catalogue, a price list, a business card, a flyer or a brochure and returns structured content ready for a website. Only what is really written is returned. 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" }
}

Create an image

Creates a photo, an illustration or a logo for a website. The image is hosted by Flixy and carries the standard IPTC marking for AI-generated media inside the file. Scope: images:write.

Balance and account

Returns your balance, the amount reserved for running jobs, the available amount, your monthly spending and the key in use. 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 }
}

Usage and pricing

/v1/usage returns your calls and amounts per operation over a period. /v1/pricing returns the current typical and minimum prices in your currency.

Each successful call costs the real cost of the AI work it required multiplied by Flixy’s margin, with a minimum per operation. Before a website job starts, an estimated amount is reserved on your balance; the exact price is charged at the end and the rest is released. Failed and refused calls are never charged.

Webhooks

Add an https address of your server in your developer space and choose the events: job.succeeded, job.failed, balance.low, topup.succeeded. Flixy sends a POST with a JSON event; answer with a 2xx status within 10 seconds. Failed deliveries are retried; an address that keeps failing is paused.

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

Verify the signature

The Flixy-Signature header contains a timestamp t and v1, the HMAC-SHA256 of t + "." + raw body with your webhook secret. Reject messages older than 5 minutes.

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

Billing

• Top up your balance from 10 € in your developer space, by card. VAT is added according to your country; an invoice is sent for every top-up.
• Turn on automatic top-up to recharge a chosen amount when your balance falls below a threshold.
• Set a monthly spending cap for the account and a daily cap per key.
• You receive an email and a balance.low webhook when your balance runs low.

Full conditions: Flixy API Terms & Usage Policy.

Security checklist

• Keep keys on your server, in environment variables or a secrets manager — never in a web page, a mobile app or a code repository.
• Create one key per application and give it only the scopes it needs.
• Restrict live keys to your servers’ IP addresses and set a daily cap.
• Verify every webhook signature and its timestamp.
• Use an idempotency key for every POST.
• Delete a key immediately if it may have been exposed, then create a new one.
• Review AI-generated content before publishing it, and tell your users when content is AI-generated where the law requires it.

Usage policy

The Flixy API is made for websites and their content. It refuses, without charging, general questions unrelated to websites, code for other software, attempts to change Flixy’s instructions and content that breaks our policy (illegal, hateful, sexual content involving minors, phishing or impersonation pages, spam, fake reviews). Read the full API Terms & Usage Policy.

Linked organization

Link your Flixy Studio organization from the console (Organization). The owner of the Flixy Studio account approves the link while signed in to Flixy Studio, and either side can remove it at any time. Once linked:

• the API can list, read, edit and translate the organization’s websites (sites:read, sites:write);
• you can create a website directly in the organization with "destination": "organization", or move a website created by the API with POST /v1/sites/{id}/transfer (free), to publish it on a domain from Flixy Studio;
• all API work is charged to your API balance: the organization’s credits are never used.

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

Without a linked organization, these calls return 409 organization_not_linked.

Changelog

• v1 — November 2026. First version: websites, edits, translations, content, document reading, images, jobs, webhooks, prepaid balance.

Changes that could break your integration are announced at least 90 days in advance by email.