Reference templates

The analysis produces a workspace template: a free.flow workflow graph plus editable slots. The graph carries the reference’s visual language — camera, lens, lighting, palette, grade — and, for video, one step per shot with the reference’s pacing. Every step prompt is built around a {{subject}} placeholder, so changing the subject changes the video instead of decorating the same person.

• Image references → one text-to-image step (or image-to-image when you bring your own subject photo).
• Video references → one text-to-video step per shot (up to 6), then an assembly step (video production, or join when production is unavailable).
• Optional music bed from the reference’s audio feel, mixed at assembly.
• An editable spec (camera, lighting, palette, shot list) stored on the template for review and re-analysis.

1. The reference is validated and downloaded in the worker (images ≤ 100 MB; videos ≤ 3 minutes).
2. For video, scene changes are detected with ffmpeg, one representative frame is sampled per shot, and a numbered contact sheet is built.
3. A vision model reads the frames and returns a strict JSON contract (look spec, shots, slots). Invalid JSON is repaired once, then the analysis fails cleanly.
4. The graph builder resolves live models, clamps shot durations and aspect ratios to what those models support, and wires the slot tokens.
5. Every step is validated against the catalog and the template is saved as a draft. You review and activate it before it can be adopted or run.

Templates declare text flow inputs. Exactly one is primary: subject, prefilled from the reference with a generic description (age range, build, hair, wardrobe) — never a name, brand, or identity instruction. Every shot prompt references it.

{
  "subject": { "text": "a woman in her late 20s, denim jacket" },
  "location": { "text": "a neon-lit street after rain" },
  "action": { "text": "walks toward the camera" }
}

Media inputs use assetIds (or urls) instead of text. A value carries either media or text, never both.

Prompts may also reference earlier text steps with {{nodeId}}. Tokens are resolved in a single pass: a slot value is inserted verbatim and never re-scanned, so text containing {{…}} cannot pull another step’s output into the prompt.

Analysis is metered on real usage, not a flat fee: the prompt and completion tokens of every vision call (including a repair pass), priced with the analyzer model’s rates and the platform margin. A hold is reserved up front from a token estimate; the actual charge is settled afterwards and the difference refunded. Failed or cancelled analyses are refunded in full.

• Free-tier and subscriber-free models charge 0 credits, like text generations.
• One attempt per analysis — a retry is an explicit, priced action.
• Analysing the same asset bytes again reuses the stored template, free.
• Per-workspace daily cap: 20 analyses; per-reference caps: 2 vision calls, 4 images per call, 12 frames, 180 s, 100 MB.

Quote, start, poll

curl -X POST https://free.ind.in/v1/reference/analyses \
  -H "Authorization: Bearer fi_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "workspaceId": "00000000-0000-4000-8000-000000000000",
    "assetId": "00000000-0000-4000-8000-000000000002",
    "options": {
      "keepLook": true,
      "keepStructure": true,
      "maxShots": 3,
      "includeMusic": false,
      "subjectMode": "text"
    }
  }'

• POST /v1/reference/quote — estimated and maximum credits, plus whether a cached template already exists.
• POST /v1/reference/analyses — reserves the hold, queues the job, returns { workflowId, status: "queued" }.
• GET /v1/reference/analyses/:workflowId — status, warnings, token usage, credits. Poll while queued or running.
• POST /v1/reference/analyses/:workflowId/cancel — cancels and refunds.
• POST /v1/reference/analyses/:workflowId/retry — retries a failed or cancelled analysis at the current price.

Activate and reuse

• POST /v1/workflows/:workflowId/activate — validates models and parameters, screens prompts, and makes the template adoptable.
• GET /v1/workflows/templates?scope=builtin|workspace|all — the public library, your workspace templates, or both.
• POST /v1/workflows with { templateId } — copies a template into an editable flow.

curl -X POST https://free.ind.in/v1/workflows/<workflow-id>/runs \
  -H "Authorization: Bearer fi_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "workspaceId": "00000000-0000-4000-8000-000000000000",
    "input": {
      "subject": { "text": "a man in his 50s with a linen shirt" },
      "location": { "text": "a sunlit rooftop at golden hour" }
    }
  }'

Built-in templates ship with the platform. Admins can also promote a finished workspace template to the public library (it appears under Templates → Built-in for every workspace), and retire it later without deleting the original.