Riferimento dell’API di Fluos

La descrizione canonica e leggibile da macchina dell’API di Fluos è https://www.fluos.io/openapi.json. Ogni operazione ha un operationId univoco, una descrizione, parametri tipizzati e schemi di risposta, così gli agenti possono registrare strumenti di function calling a partire dalla specifica.

URL di base

https://www.fluos.io

Prefisso pubblico canonico dell’API: /api/v1/. Invia API-Version: 1. Vedi Versioning e deprecazione dell’API di Fluos.

Discovery

operationId	Metodo	Percorso	Scopo
`getFluosOpenApiSpec`	GET	`/openapi.json`	Questa specifica
`getFluosOpenApiSpecV1`	GET	`/api/v1/openapi.json`	Alias versionato di questa specifica
`getFluosMcpServerCard`	GET	`/api/v1/mcp`	Scheda del server MCP di Fluos
`callFluosMcp`	POST	`/api/v1/mcp`	JSON-RPC del MCP di Fluos
`getFluosLlmsTxt`	GET	`/llms.txt`	Indice curato degli URL
`getFluosLlmsFullTxt`	GET	`/llms-full.txt`	Dump completo della documentazione in testo
`getFluosAiTxt`	GET	`/ai.txt`	Policy per i crawler di IA
`getFluosSitemap`	GET	`/sitemap.xml`	Tutti gli URL pubblici
`getFluosRobotsTxt`	GET	`/robots.txt`	Regole per i crawler
`getFluosRssFeed`	GET	`/feed.xml`	Feed RSS del blog

Questi endpoint sono pubblici e memorizzabili in cache. Nessuna autenticazione.

Contenuti (negoziazione con Accept)

operationId	Metodo	Percorso
`getFluosHome`	GET	`/`
`getFluosCli`	GET	`/cli`
`getFluosMcp`	GET	`/mcp`
`getFluosDocsIndex`	GET	`/docs`
`getFluosDocPage`	GET	`/docs/{slug}`
`getFluosAbout`	GET	`/about`
`getFluosPricing`	GET	`/pricing`
`getFluosBlogPost`	GET	`/blog/{slug}`

Invia Accept: text/markdown per ottenere Markdown. Senza Accept la risposta è in HTML. I valori di Accept incompatibili restituiscono 406.

Ricerca

operationId	Metodo	Percorso	Parametri
`searchFluosDocs`	GET	`/api/search`	`query` (o l’alias `q`)
`searchFluosDocsV1`	GET	`/api/v1/search`	`query` (o l’alias `q`)

Pubblico. Restituisce risultati ordinati per rilevanza su questa documentazione. Preferisci /api/v1/search. Le risposte includono gli header IETF RateLimit; 429 include Retry-After.

Video

Solo piani a pagamento. Autenticati con OAuth o con un token API; il piano Gratuito riceve 402 PLAN_REQUIRED. Le stesse attività sono disponibili come strumenti del MCP video.

operationId	Metodo	Percorso	Scopo
`listFluosWorkspaces`	GET	`/api/v1/workspaces`	Spazi di lavoro a cui hai accesso
`listFluosProjects`	GET	`/api/v1/projects`	Progetti di uno spazio di lavoro
`createFluosProject`	POST	`/api/v1/projects`	Crea un progetto
`listFluosTemplates`	GET	`/api/v1/templates`	Modelli salvati in uno spazio di lavoro (parametro `workspaceId`)
`listFluosAssets`	GET	`/api/v1/assets`	Elementi della libreria
`startFluosAssetUpload`	POST	`/api/v1/assets/uploads`	Avvia un caricamento nella libreria
`completeFluosAssetUpload`	POST	`/api/v1/assets`	Completa un caricamento nella libreria
`createFluosVideo`	POST	`/api/v1/videos`	Avvia un job video
`getFluosVideoJob`	GET	`/api/v1/videos/{jobId}`	Controlla lo stato di un job
`reviseFluosVideo`	POST	`/api/v1/videos/{jobId}/revise`	Avvia un job di follow-up a partire da uno pronto
`cancelFluosVideo`	POST	`/api/v1/videos/{jobId}/cancel`	Annulla un job in coda, in corso o in pausa
`exportFluosVideo`	POST	`/api/v1/exports`	Esporta un job pronto
`getFluosVideoExport`	GET	`/api/v1/exports/{exportId}`	Controlla lo stato di un’esportazione

Creare un video

createFluosVideo richiede projectId e brief. Campi facoltativi:

Campo	Scopo
`recipe`	`generate` \| `edit` \| `compose` \| `mix`. Vedi Ricette
`assetIds`	Elementi della libreria da usare
`format`	`aspectRatio`, `durationHintSeconds`, `resolution`
`templateId`	Un modello preso da `listFluosTemplates`. Il brief viene creato in un nuovo progetto copiato da quel modello, con la stessa struttura, lo stesso ritmo e le stesse animazioni, senza passaggio di storyboard
`brandKitId`, `designSystem`, `designMd`	Il brand kit, il preset di design o il `DESIGN.md` inline con cui dare lo stile al video. Se non ne indichi nessuno, vale il kit del progetto o quello predefinito dello spazio di lavoro
`style_reference_url`	Un link YouTube o un file diretto `.mp4`, `.mov` o `.webm` di cui il video deve riprendere ritmo, tagli, palette e tipografia, senza mai copiarli. I link di Instagram, X e TikTok vengono rifiutati con `UPLOAD_REQUIRED`: carica invece il file

Stato del job

Controlla getFluosVideoJob ogni pochi secondi. status può essere:

Stato	Significato
`queued`	In attesa di partire
`running`	Creazione in corso
`awaiting_credits`	La creazione ha esaurito i crediti ed è in pausa. Non è né terminata né fallita
`ready`	Completato. Esportalo
`failed`	Vedi `error.code`
`cancelled`	Annullato

Finché lo stato è awaiting_credits, il job ha un oggetto pause:

{
  "status": "awaiting_credits",
  "pause": {
    "reason": "credits_exhausted",
    "topUpUrl": "https://www.fluos.io/dashboard/billing?src=credit_pause",
    "expiresAt": 1761696000000
  }
}

Tratta awaiting_credits come non terminato. Mostra pause.topUpUrl all’utente. Quando aggiunge crediti, lo stesso job torna da solo a running: continua a controllare, circa una volta al minuto, invece di creare un nuovo job. Se non arrivano crediti entro pause.expiresAt (millisecondi epoch), il job fallisce. pause è assente o null in tutti gli altri stati.

Quando una versione viene salvata, il job restituisce anche sources[]: ogni elemento usato dal video, con sourceKind, rightsStatus (licensed, cc, user_attested, owned, generated o unverified), provider, license, author, attribution e usages (scena, elemento, traccia, inizio e fine).

Esportare

exportFluosVideo accetta jobId, un format facoltativo (mp4 per impostazione predefinita, gif, webm, mov, png-sequence), opzioni advanced facoltative e require_licensed. Con require_licensed: true, l’esportazione viene rifiutata con 422 UNLICENSED_SOURCES finché una voce di sources[] ha diritti unverified. Senza questa opzione, le fonti non verificate non bloccano l’esportazione.

Errori

Stato	Quando
`404`	Percorso sconosciuto. Il corpo Markdown elenca `/sitemap.xml`, `/llms.txt`, `/docs`, `/docs/developers`, `/openapi.json`.
`406`	`Accept` ha rifiutato sia HTML sia Markdown.
`401`	API autenticata senza sessione né token. JSON `{ "error", "code": "unauthorized" }`.
`402`	API video sul piano Gratuito (`PLAN_REQUIRED`, con `upgradeUrl`), oppure nessun credito per avviare un job (`CREDITS_EXHAUSTED`, con `topUpUrl`).
`422`	`UNLICENSED_SOURCES`: un’esportazione con `require_licensed: true` mentre una fonte non è verificata.

Function calling

Importa /openapi.json e registra ogni operationId come strumento. Prima di rispondere a domande sul prodotto, dai la precedenza alla discovery, poi a searchFluosDocs e a getFluosDocPage in Markdown.

In questa pagina