Documentación de la API

Introducción

La Flixy API permite a tu software usar las funciones de Flixy Studio: crear sitios web completos a partir de una descripción, editarlos y traducirlos, redactar contenido web, leer menús, catálogos y PDF, y crear imágenes y logotipos. Solo pagas por las llamadas correctas, con un saldo prepago.

Las tareas largas (crear, editar o traducir un sitio web) se ejecutan como trabajos: la API responde de inmediato y tú sigues el trabajo o recibes un webhook. El contenido, la lectura de documentos y las imágenes responden directamente, normalmente en pocos segundos.

Consola de desarrolladores

Las claves, el saldo, las recargas, los webhooks y el registro de llamadas se gestionan en la consola de desarrolladores en dev.flixy.studio.

• Una cuenta de desarrollador independiente. Como en otras plataformas de IA, tu cuenta de desarrollador es distinta de tu cuenta de Flixy Studio: tiene su propio registro, inicio de sesión y sesión. Cerrar sesión en una nunca cierra tu sesión en la otra. Puedes usar la misma dirección de correo electrónico para ambas.
• Organización vinculada. Si también usas Flixy Studio, puedes vincular tu organización a tu cuenta de desarrollador para que la API pueda trabajar en sus sitios web. Consulta Organización vinculada.
• Seguridad de la cuenta. La verificación en dos pasos, las sesiones activas y la exportación de datos están disponibles en la consola, en Cuenta.

Autenticación

Envía tu clave en la cabecera Authorization de cada solicitud. Las claves empiezan por fx_live_ o fx_test_.

Authorization: Bearer fx_live_8sJ2…

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

Cada clave tiene permisos (scopes). Una llamada sin el permiso necesario devuelve 403 missing_scope.

Claves de prueba y live

• Las claves de prueba (fx_test_…) son gratuitas. Devuelven respuestas de ejemplo realistas sin usar IA, para que puedas construir y probar toda tu integración. Los trabajos de sitio web terminan tras unos segundos con un sitio de ejemplo.
• Las claves live (fx_live_…) devuelven resultados reales y se cobran de tu saldo.

Cada respuesta contiene la cabecera Flixy-Mode: test o Flixy-Mode: live.

Solicitudes y respuestas

Envía cuerpos JSON con Content-Type: application/json (16 MB como máximo). Las respuestas son JSON. Las fechas usan ISO 8601 en UTC. Cada respuesta tiene una cabecera X-Request-Id: facilítala a nuestro soporte si necesitas ayuda con una llamada.

Define Accept-Language para recibir los mensajes de error en tu idioma (fr, en, es, de, it, pt, nl, ca, el, sv, no, da, fi, is, et, lv, lt, ja; inglés por defecto).

Errores

Los errores usan códigos de estado HTTP estándar y siempre tienen la misma forma:

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

Límites de uso

• 60 solicitudes por minuto por clave (cabecera X-RateLimit-Limit).
• 3 trabajos de sitio web a la vez por cuenta. Las llamadas de contenido, documentos e imágenes no están sujetas a este límite.
• Cuando se alcanza un límite, la API responde 429 con una cabecera Retry-After en segundos.

¿Necesitas más? Escribe a contact@flixy.studio contándonos tu caso de uso.

Idempotencia

Los errores de red ocurren. Añade una cabecera Idempotency-Key (de 8 a 100 caracteres, por ejemplo tu propio ID de pedido) a cualquier POST: si vuelves a enviar la misma solicitud en un plazo de 24 horas, la API devuelve la primera respuesta — con la cabecera Idempotent-Replayed: true — y nunca ejecuta ni cobra el trabajo dos veces.

Trabajos

Crear, editar y traducir un sitio web lleva de unos 30 segundos a 3 minutos. Estos endpoints responden 202 Accepted con un trabajo. Consúltalo cada 5 segundos o espera los eventos 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 es queued, running, succeeded o failed. Un trabajo fallido nunca se cobra y su error explica el motivo.

Crear un sitio web

Crea un sitio web completo a partir de una descripción. Permiso: 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']);

Obtener un sitio web

Devuelve el sitio web, su estado y sus páginas. Añade include=html para recibir el HTML completo de cada página (las imágenes las aloja Flixy). Permiso: 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>…" }
}

Añade owner=developer o owner=organization a la lista para filtrar por propietario. Los sitios web de una organización vinculada también devuelven dashboard_url y editor_url, para abrirlos en Flixy Studio.

Editar un sitio web

Aplica un cambio descrito en lenguaje natural, como en el editor de Flixy. Cada cambio crea una nueva versión. Permiso: 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"}'

Traducir un sitio web

Traduce cada página del sitio web — navegación, botones, formularios, descripciones de imágenes, título y descripción para buscadores — manteniendo el diseño, las imágenes, los enlaces, los precios y los datos de contacto. Permiso: sites:write.

Redactar contenido web

Redacta contenido destinado a publicarse en un sitio web o a que un negocio lo envíe a sus clientes. Responde directamente. Permiso: 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 campo html solo contiene etiquetas de texto seguras (títulos, párrafos, listas, enlaces), nunca scripts ni estilos.

Leer un documento

Lee un menú, un catálogo, una lista de precios, una tarjeta de visita, un flyer o un folleto y devuelve contenido estructurado listo para un sitio web. Solo se devuelve lo que está realmente escrito. Permiso: 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 imagen

Crea una foto, una ilustración o un logotipo para un sitio web. La imagen la aloja Flixy y lleva dentro del archivo el marcado IPTC estándar para contenido multimedia generado por IA. Permiso: images:write.

Saldo y cuenta

Devuelve tu saldo, el importe reservado para trabajos en curso, el importe disponible, tu gasto mensual y la clave en uso. Permiso: 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 }
}

Uso y precios

/v1/usage devuelve tus llamadas e importes por operación en un periodo. /v1/pricing devuelve los precios habituales y mínimos actuales en tu moneda.

Cada llamada correcta cuesta el coste real del trabajo de IA que ha requerido multiplicado por el margen de Flixy, con un mínimo por operación. Antes de que empiece un trabajo de sitio web, se reserva un importe estimado en tu saldo; el precio exacto se cobra al final y el resto se libera. Las llamadas fallidas y rechazadas nunca se cobran.

Webhooks

Añade una dirección https de tu servidor en tu espacio de desarrollador y elige los eventos: job.succeeded, job.failed, balance.low, topup.succeeded. Flixy envía un POST con un evento JSON; responde con un estado 2xx en menos de 10 segundos. Los envíos fallidos se reintentan; una dirección que falla repetidamente se pone 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 firma

La cabecera Flixy-Signature contiene una marca de tiempo t y v1, el HMAC-SHA256 de t + "." + raw body con tu secreto de webhook. Rechaza los mensajes de más de 5 minutos de antigüedad.

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ón

• Recarga tu saldo desde 10 € en tu espacio de desarrollador, con tarjeta. El IVA se añade según tu país; se envía una factura por cada recarga.
• Activa la recarga automática para recargar el importe que elijas cuando tu saldo baje de un umbral.
• Fija un límite de gasto mensual para la cuenta y un límite diario por clave.
• Recibes un email y un webhook balance.low cuando tu saldo está bajo.

Condiciones completas: Condiciones y política de uso de la Flixy API.

Lista de seguridad

• Guarda las claves en tu servidor, en variables de entorno o en un gestor de secretos — nunca en una página web, una app móvil o un repositorio de código.
• Crea una clave por aplicación y dale solo los permisos que necesita.
• Restringe las claves live a las direcciones IP de tus servidores y fija un límite diario.
• Verifica la firma de cada webhook y su marca de tiempo.
• Usa una clave de idempotencia en cada POST.
• Elimina una clave de inmediato si ha podido quedar expuesta y crea una nueva.
• Revisa el contenido generado por IA antes de publicarlo, e informa a tus usuarios de que un contenido está generado por IA cuando la ley lo exija.

Política de uso

La Flixy API está hecha para sitios web y su contenido. Rechaza, sin cobrar, preguntas generales sin relación con sitios web, código para otro software, intentos de cambiar las instrucciones de Flixy y contenido que incumple nuestra política (contenido ilegal, de odio, sexual que involucre a menores, páginas de phishing o de suplantación, spam, reseñas falsas). Lee las Condiciones y política de uso de la API completas.

Organización vinculada

Vincula tu organización de Flixy Studio desde la consola (Organización). El propietario de la cuenta de Flixy Studio aprueba la vinculación con la sesión iniciada en Flixy Studio, y cualquiera de las partes puede eliminarla en cualquier momento. Una vez vinculada:

• la API puede listar, leer, editar y traducir los sitios web de la organización (sites:read, sites:write);
• puedes crear un sitio web directamente en la organización con "destination": "organization", o mover un sitio web creado por la API con POST /v1/sites/{id}/transfer (gratis), para publicarlo en un dominio desde Flixy Studio;
• todo el trabajo de la API se cobra de tu saldo de la API: nunca se usan los créditos de la organización.

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

Sin una organización vinculada, estas llamadas devuelven 409 organization_not_linked.

Registro de cambios

• v1 — noviembre de 2026. Primera versión: sitios web, ediciones, traducciones, contenido, lectura de documentos, imágenes, trabajos, webhooks, saldo prepago.

Los cambios que puedan romper tu integración se anuncian por email con al menos 90 días de antelación.