Documentação da API

Introdução

A Flixy API permite ao seu software utilizar as funcionalidades do Flixy Studio: criar sites completos a partir de uma descrição, editá-los e traduzi-los, redigir conteúdos para sites, ler menus, catálogos e PDF, e criar imagens e logótipos. Paga apenas as chamadas bem-sucedidas, a partir de um saldo pré-pago.

As tarefas longas (criar, editar ou traduzir um site) são executadas como jobs: a API responde de imediato e o utilizador acompanha o job ou recebe um webhook. Os conteúdos, a leitura de documentos e as imagens respondem diretamente, normalmente em poucos segundos.

Consola de programador

As chaves, o saldo, os carregamentos, os webhooks e o registo de chamadas são geridos na consola de programador em dev.flixy.studio.

• Uma conta de programador separada. Tal como noutras plataformas de IA, a sua conta de programador é distinta da sua conta Flixy Studio: tem registo, início de sessão e sessão próprios. Terminar sessão numa nunca termina a sessão na outra. Pode utilizar o mesmo endereço de e-mail para ambas.
• Organização associada. Se também utiliza o Flixy Studio, pode associar a sua organização à sua conta de programador, para que a API possa trabalhar nos respetivos sites. Consulte Organização associada.
• Segurança da conta. A verificação em dois passos, as sessões ativas e a exportação de dados estão disponíveis na consola, em Conta.

Autenticação

Envie a sua chave no cabeçalho Authorization de cada pedido. As chaves começam por fx_live_ ou fx_test_.

Authorization: Bearer fx_live_8sJ2…

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

Cada chave tem direitos (scopes). Uma chamada sem o scope adequado devolve 403 missing_scope.

Chaves de teste e live

• As chaves de teste (fx_test_…) são gratuitas. Devolvem respostas de exemplo realistas sem utilizar IA, para que possa criar e testar toda a sua integração. Os jobs de sites terminam após alguns segundos com um site de exemplo.
• As chaves live (fx_live_…) devolvem resultados reais e são cobradas no seu saldo.

Cada resposta contém o cabeçalho Flixy-Mode: test ou Flixy-Mode: live.

Pedidos e respostas

Envie corpos JSON com Content-Type: application/json (16 MB no máximo). As respostas são em JSON. As datas utilizam ISO 8601 em UTC. Cada resposta tem um cabeçalho X-Request-Id: indique-o ao nosso suporte se precisar de ajuda com uma chamada.

Defina Accept-Language para receber as mensagens de erro na sua língua (fr, en, es, de, it, pt, nl, ca, el, sv, no, da, fi, is, et, lv, lt, ja; inglês por predefinição).

Erros

Os erros utilizam os códigos de estado HTTP padrão e têm sempre a mesma forma:

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

Limites de pedidos

• 60 pedidos por minuto por chave (cabeçalho X-RateLimit-Limit).
• 3 jobs de sites em simultâneo por conta. As chamadas de conteúdos, documentos e imagens não estão sujeitas a este limite.
• Quando um limite é atingido, a API responde 429 com um cabeçalho Retry-After em segundos.

Precisa de mais? Escreva para contact@flixy.studio com o seu caso de utilização.

Idempotência

Os erros de rede acontecem. Adicione um cabeçalho Idempotency-Key (8 a 100 caracteres, por exemplo o seu próprio ID de encomenda) a qualquer POST: se enviar novamente o mesmo pedido no prazo de 24 horas, a API devolve a primeira resposta — com o cabeçalho Idempotent-Replayed: true — e nunca executa nem cobra o trabalho duas vezes.

Jobs

Criar, editar e traduzir um site demora entre cerca de 30 segundos e 3 minutos. Estes endpoints respondem 202 Accepted com um job. Acompanhe-o a cada 5 segundos ou aguarde o evento job.succeeded / job.failed por 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 ou failed. Um job falhado nunca é cobrado e o respetivo error explica o motivo.

Criar um site

Cria um site completo a partir de uma descrição. 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']);

Obter um site

Devolve o site, o respetivo estado e as suas páginas. Adicione include=html para receber o HTML completo de cada página (as imagens são alojadas pela 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>…" }
}

Adicione owner=developer ou owner=organization à listagem para filtrar por proprietário. Os sites de uma organização associada devolvem também dashboard_url e editor_url, para os abrir no Flixy Studio.

Editar um site

Aplica uma alteração descrita em linguagem simples, como no editor da Flixy. Cada alteração cria uma nova versão. 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"}'

Traduzir um site

Traduz todas as páginas do site — navegação, botões, formulários, descrições das imagens, título e descrição para os motores de pesquisa — mantendo o design, as imagens, as ligações, os preços e os contactos. Scope: sites:write.

Redigir conteúdos web

Redige conteúdos destinados a ser publicados num site ou enviados por um negócio aos seus clientes. Responde diretamente. 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" }
}

O campo html contém apenas etiquetas de texto seguras (títulos, parágrafos, listas, ligações), nunca scripts nem estilos.

Ler um documento

Lê um menu, um catálogo, uma tabela de preços, um cartão de visita, um folheto ou uma brochura e devolve conteúdos estruturados prontos para um site. Só é devolvido o que está realmente escrito. 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" }
}

Criar uma imagem

Cria uma fotografia, uma ilustração ou um logótipo para um site. A imagem é alojada pela Flixy e contém, dentro do ficheiro, a marcação IPTC padrão para conteúdos multimédia gerados por IA. Scope: images:write.

Saldo e conta

Devolve o seu saldo, o montante reservado para os jobs em curso, o montante disponível, a sua despesa mensal e a chave em utilização. 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 }
}

Utilização e preços

/v1/usage devolve as suas chamadas e os montantes por operação num período. /v1/pricing devolve os preços típicos e mínimos atuais na sua moeda.

Cada chamada bem-sucedida custa o custo real do trabalho de IA de que precisou, multiplicado pela margem da Flixy, com um mínimo por operação. Antes de um job de site começar, é reservado no seu saldo um montante estimado; o preço exato é cobrado no fim e o restante é libertado. As chamadas falhadas e recusadas nunca são cobradas.

Webhooks

Adicione um endereço https do seu servidor no seu espaço de programador e escolha os eventos: job.succeeded, job.failed, balance.low, topup.succeeded. A Flixy envia um POST com um evento JSON; responda com um estado 2xx no prazo de 10 segundos. As entregas falhadas são repetidas; um endereço que continue a falhar é colocado em 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 a assinatura

O cabeçalho Flixy-Signature contém um carimbo temporal t e v1, o HMAC-SHA256 de t + "." + raw body com o seu segredo de webhook. Rejeite mensagens com mais de 5 minutos.

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

Faturação

• Carregue o seu saldo a partir de 10 € no seu espaço de programador, com cartão. O IVA é acrescido consoante o seu país; é enviada uma fatura por cada carregamento.
• Ative o carregamento automático para carregar um montante escolhido quando o seu saldo descer abaixo de um limiar.
• Defina um limite de despesa mensal para a conta e um limite diário por chave.
• Recebe um email e um webhook balance.low quando o seu saldo está a ficar baixo.

Condições completas: Condições e Política de Utilização da Flixy API.

Lista de verificação de segurança

• Guarde as chaves no seu servidor, em variáveis de ambiente ou num gestor de segredos — nunca numa página web, numa app móvel ou num repositório de código.
• Crie uma chave por aplicação e atribua-lhe apenas os scopes de que necessita.
• Restrinja as chaves live aos endereços IP dos seus servidores e defina um limite diário.
• Verifique a assinatura e o carimbo temporal de cada webhook.
• Utilize uma chave de idempotência em cada POST.
• Elimine imediatamente uma chave se puder ter sido exposta e, em seguida, crie uma nova.
• Reveja os conteúdos gerados por IA antes de os publicar e informe os seus utilizadores de que um conteúdo foi gerado por IA quando a lei o exigir.

Política de utilização

A Flixy API foi concebida para sites e os respetivos conteúdos. Recusa, sem cobrar, perguntas genéricas não relacionadas com sites, código para outro software, tentativas de alterar as instruções da Flixy e conteúdos que violem a nossa política (ilegais, de ódio, sexuais envolvendo menores, páginas de phishing ou de usurpação de identidade, spam, avaliações falsas). Leia as Condições e Política de Utilização da API completas.

Organização associada

Associe a sua organização Flixy Studio a partir da consola (Organização). O titular da conta Flixy Studio aprova a associação com sessão iniciada no Flixy Studio, e qualquer uma das partes pode removê-la a qualquer momento. Depois de associada:

• a API pode listar, ler, editar e traduzir os sites da organização (sites:read, sites:write);
• pode criar um site diretamente na organização com "destination": "organization", ou transferir um site criado pela API com POST /v1/sites/{id}/transfer (gratuito), para o publicar num domínio a partir do Flixy Studio;
• todo o trabalho da API é cobrado no seu saldo da API: os créditos da organização nunca são utilizados.

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

Sem uma organização associada, estas chamadas devolvem 409 organization_not_linked.

Registo de alterações

• v1 — novembro de 2026. Primeira versão: sites, edições, traduções, conteúdos, leitura de documentos, imagens, jobs, webhooks, saldo pré-pago.

As alterações que possam afetar a sua integração são anunciadas por email com, pelo menos, 90 dias de antecedência.