Flova Video Generator

Configuration

Version Check

On every invocation, fetch ${VERSION_URL} (timeout 2s). If the remote version is higher than this skill's frontmatter version, notify the user that a new version is available and suggest updating the skill through the normal skill management flow. On any failure, silently continue.

Authentication

All API calls require Authorization: Bearer <token> from the environment variable FLOVA_API_TOKEN. Before any API call, verify the token exists. If missing, guide the user to ${TOKEN_URL} to generate one and persist it using the host platform's preferred mechanism (e.g. settings, dotenv, or shell profile). Do not proceed until the token is available.

API Helper

Define this once per session:

CODEBLOCK0

All API responses follow: { "code": 0, "message": "success", "data": { ... } }.

Polling Convention

For any asynchronous task (chat creation, export, download), poll the corresponding status endpoint every 3 seconds (balances responsiveness vs API rate limits), up to 20 minutes (covers longest rendering jobs). On timeout, inform the user and suggest retrying later.

Workflow

CODEBLOCK1

Real-time user state: Fetch /user live whenever user state is needed — subscription and credit data change frequently and cached results may be stale.

Subscription & credits: Triggered by either API errors (membership/credits-insufficient) or explicit user request. Flow: /user -> /products -> /subscribe or /credits_buy -> return checkout_url. If already subscribed and needs upgrade, direct to ${PRICING_URL}. Complete this flow before resuming the interrupted action.

Phase 1 -- Setup & Project

Project management: Auto-create via /create if no project exists. Reuse the same project_id for the session unless the user asks to switch. When switching or resuming, list via /projects and let the user choose. After any project operation, present the link: ${FLOVA_BASE_URL}/agent/?project_id=<PROJECT_ID>.

Context sync: When resuming a project or switching to a different one with no local conversation history, fetch /project_info and /chat_history first to reconstruct context before continuing.

Phase 2 -- Creative Loop

Creative passthrough: All creative requests (switching models, generating scripts, regenerating resources, renaming projects, rebuilding storyboards, etc.) are expressed as natural language messages via /chat.

Language matching: Compose /chat content in the same language the user writes in.

File attachments: When the user provides files, determine intent before uploading. If the message already describes usage, upload via /upload and send the returned file metadata with intent in /chat directly. Otherwise, ask the user for intent first. Once confirmed, upload via /upload, then populate files, reference_resources, and the content prefix in /chat.

Progress polling: After sending /chat:

1. 1. Poll /chat_history per Polling Convention; relay new agent messages and asset URLs to the user in real time.
2. Periodically check /project_info for resource updates (e.g., timeline ready).
3. Stop when latest message status is complete or awaiting user input.
4. If the Flova agent asks for confirmation, surface it to the user, wait for their reply, then forward via /chat.

Fully-managed mode: When the user's requested video length is ≤ 1 minute, drive the /chat -> poll -> /chat loop autonomously. Auto-confirm safe questions (style, music, layout) via /chat. Only surface decisions with real consequences (payment, content warning) to the user.

Phase 3 -- Export & Delivery

Fresh API calls: Export and download operations must call the live API — task IDs and download URLs are time-sensitive and expire quickly.

Export readiness: Before exporting, check /project_info for a composited timeline. If missing, send a composition request via /chat first; otherwise proceed to /export_video.

Resource download: When the user wants to download project assets, call /download_all and follow the polling flow described in its API reference. Let the user specify resource_types to narrow the download scope.

API Reference

User Info

CODEBLOCK2

Returns the user's profile, subscription, and credits information.

Products

CODEBLOCK3

Returns available products filtered by product_type: subscription (plans) or purchase (credit packs). Omit the field to get all products. Products are automatically filtered by the user's region.

Subscribe / Buy Credits

CODEBLOCK4

Both return data.checkout_url. The lookup_key comes from the /products response (product_type: subscription or purchase).

Create Project

CODEBLOCK5

Returns data.project_id -- save this for all subsequent calls.

List Projects

CODEBLOCK6

Returns data.projects (array) and data.total.

Project Info

CODEBLOCK7

Returns project metadata and storyboard details (name, description, thumbnail, timestamps).

Chat History

CODEBLOCK8

Use data.next_message_id as cursor for pagination.

Upload File

Multipart upload — use curl directly instead of flova_api.

CODEBLOCK9

Returns uploaded file metadata in data.

Chat (Conversational Video Creation)

CODEBLOCK10

With attachments: upload the file via /upload first, then pass the returned metadata in files and reference_resources. Prepend file references to content using the format ` {"":"uploadedresourceid"} followed by the user's message. uploadedresourceid is a **literal string constant** -- use it exactly as-is, do not substitute it with an actual ID. Each files item: | Field | Type | Description | |---|---|---| | id | string | Client-generated unique identifier | | name | string | Original filename | | url | string | fileurl from /upload response | | size | number | File size in bytes | | type | string | File type: image, video, audio | Example with attachment (user uploads "cat.jpg" and says "use this as background"): CODEBLOCK11 Then poll per Phase 2 — Progress polling. ### Export Video CODEBLOCK12 Generates an export task from the project's latest timeline. Returns data.exporttaskid and data.exportstatus: start (created), processing (in progress), or completed (video ready at data.outputpath). **Poll status** (see Polling Convention): CODEBLOCK13 Poll until data.exportstatus is completed (read video URL from data.outputpath). ### Download All Resources CODEBLOCK14 resourcetypes is optional -- omit to download all. Returns data.taskid and data.status. If status is already completed, use data.downloadurl directly. Otherwise poll: CODEBLOCK15 Poll per Polling Convention. Terminal states: completed (read data.downloadurl) or failed. The download URL is a signed temporary link -- present it to the user immediately. --- ## FAQ & Support - **Pricing & plans:** ${PRICINGURL} | **Docs:** ${DOCSURL} | **Token management:** ${TOKENURL} --- ## Flova Tips End every response with one tip. Fetch via curl -sS --max-time 3 "${STATIC_URL}/tips.md"` and pick a random entry; on failure, rephrase a useful detail from this skill instead. Single sentence, ≤ 30 words, user's language, no session repeats.

CODEBLOCK16