Configure an image-to-video pipeline

What does this module do?

The optional pipeline edits uploaded reference images, then animates the first frame into a video. Each step records its provider request before recovery can proceed. Website, API and Skill calls use the same credit reservation and private files.

The ioy.ai catalog describes a configurable reference. This website does not run paid video generation, and it has no generated example media. A configured independent product must verify its real fal results and costs before launch.

How do I enable it in my own product?

Use the standard layout and set trendsEnabled: true in your requirements before running the project generator. The default is false; one-page products do not include this separate catalog. In an existing standard product, set product.trends.enabled = true in app/core/product.ts.

Review app/core/trends/smalltown-boy-ai.ts and register your own config through app/core/trends/index.ts. Inputs have names, MIME and size limits. Step references point to named inputs or an earlier step. Drafts and archived entries are excluded from public catalogs, API listings and sitemap. Adding an active entry automatically registers its page; run content:build and sitemap:check before release.

Which models and keys do I configure?

Set FAL_API_KEY through Cloudflare Secrets. The reference uses fal-ai/nano-banana-2/edit for two images and fal-ai/wan/v2.2-a14b/image-to-video for a five-second video, with 480p or 720p variants. That adapter supports five or ten seconds. Changing models requires updating the adapter's input contract, supported options and tests.

Configure MODEL_COSTS_JSON for the actual model ID used by each step. Image rates use perImage; video rates use perSecond, optionally keyed by resolution. Each rate needs an attributable source and updatedAt; zero rates require freeProvider: true. Enter rates from your provider account rather than copying example prices. Recorded costs are estimates, not provider invoices.

FAL_EDIT_MODEL and FAL_VIDEO_MODEL are fallbacks when a step has no explicit model. The reference's explicit models take precedence. Bind TrendPipelineWorkflow as TREND_JOBS, apply database migrations, and enable AI_MODE=live only after isolated acceptance. Local generic AI simulation does not simulate this video pipeline.

How are callbacks verified?

fal callbacks use official Ed25519 public keys, four X-Fal-Webhook-* headers and the raw request-body hash. They do not use a custom FAL_WEBHOOK_SECRET. The callback is a durable signal to query the recorded request; its body does not directly grant credits or complete a task. Repeated callbacks are idempotent. Scheduled polling also recovers saved request IDs.

See the official webhook protocol and queue API. fal must reach your independent HTTPS /api/webhooks/fal endpoint. Keep callback payloads and credentials out of analytics and logs.

How do I create and retrieve a video?

1. Upload both images through POST /api/v1/files. Use a key with files:write; retain returned asset IDs. Images must belong to the caller and remain unexpired.
2. Send POST /api/v1/trends/{slug}/jobs with jobs:write, a stable Idempotency-Key, and JSON containing variantId and named inputs asset IDs.
3. Poll GET /api/v1/trends/{slug}/jobs/{id} with jobs:read. Reuse the original key only for identical input. Stop automatic retries when the outcome is unknown.
4. When status is succeeded, download GET /api/v1/trends/{slug}/jobs/{id}/result with jobs:read. Results are private, size-limited MP4 downloads subject to the product's retention period.

Exact request and response schemas are in OpenAPI and the API reference. The generated TypeScript client and product Skill include the enabled operations. Never paste an API key into a conversation or request URL.

What happens after failure or a timeout?

Credit reservation and provider cost limits are checked before creating a job. A known failure settles once according to the template's refund policy. An uncertain submission or incomplete result retains its reservation; recovery polls the saved request and does not blindly submit another paid request. A submission that timed out before returning an ID needs operator reconciliation.

Changing a template later does not rewrite an existing job's snapshotted config and rates. The dashboard includes trend usage and estimated costs; account export and deletion include the new records. Files used by active pipelines cannot be manually deleted.

What must I verify before going live?

Run npm run check, npm run test:ui:isolated and npm run doctor -- --release in the independent product. Verify both inputs are used, actual duration and resolution, received callbacks, delayed and duplicate callbacks, interrupted submissions, cross-user file isolation, concurrent reservations, failure settlement and a downloaded video that plays. Contract tests use isolated mocked provider responses and do not prove a real provider transaction.

Use your own images and appropriate rights for inputs, outputs and any audio added later. This reference adds no music and makes no copyright or commercial-use guarantee.