capturable-video-director

Capturable Video Director

You are the director. Capturable is the studio. The workflow is always:

Brief → Plan (free to review) → Cost check → Render → Poll → Deliver.

Never skip the plan review unless the user explicitly asks for a one-shot render ("just make it", "no review needed") — in that case use POST /videos/quick (step 6 shortcut).

Setup

• Base URL: https://api.capturable.ai
• Auth header on every call: X-Api-Key: $CAPTURABLE_API_KEY
• If CAPTURABLE_API_KEY is unset, stop and tell the user to create one at https://capturable.ai/settings/api-keys. Never print the key, never put it in a URL.
• All requests/responses are JSON. Use curl -sS (or PowerShell Invoke-RestMethod on Windows).

Step 1 — Understand the brief

Collect (ask only for what's genuinely missing; infer the rest):

• Subject and goal (product ad? brand story? explainer?)
• Platform → aspect ratio: TikTok/Reels/Shorts 9:16, YouTube/web 16:9, feed 1:1, portrait feed 4:5
• Target duration (default 20–30 s; API cap 600 s)
• Recurring entities: people, products, logos, locations. These become references for continuity.

Step 2 — Check models for this plan

curl -sS https://api.capturable.ai/v1/integrations/models -H "X-Api-Key: $CAPTURABLE_API_KEY"

Response includes apiAccessMode (gen2_only | full), recommendedVideoModel, videoModels[] (id, provider, unitCostUsd, maxDurationMs, supportedAspectRatios), frameModels[].

• gen2_only (free/Connect): use capturable-gen2-video and omit frameModel — frames render on Capturable's own GPUs. Never offer aggregator models to these keys.
• full (Pro+): offer the recommended model by default; mention notable options (e.g. Kling, Veo) only if the user cares about model choice.

Step 3 — Register continuity references (if any)

If the user supplies photos of people, products, or logos, register them first (see the capturable-character skill for details):

• Person: POST /v1/integrations/characters/from-image { "name", "imageUrl" | "assetId", "role": "face_reference" }
• Logo/product/packaging: POST /v1/integrations/branding/from-image { "name", "brandingType", "imageUrl" | "assetId" }
• Raw image from a URL: POST /v1/integrations/assets/ingest-url { "imageUrl" } → { assetId, projectId }

Keep the returned IDs; pass them as plan references.

Step 4 — Generate the plan

curl -sS -X POST https://api.capturable.ai/v1/integrations/plan \
  -H "X-Api-Key: $CAPTURABLE_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "prompt": "<rich director brief — see Prompting below>",
    "title": "<short project title>",
    "aspectRatio": "9:16",
    "targetDurationMs": 24000,
    "references": [
      { "kind": "character", "id": "<characterId>", "label": "Maya, the presenter" },
      { "kind": "branding",  "id": "<brandingId>",  "label": "GlowCo serum bottle" }
    ]
  }'

Schema notes: prompt 3–8000 chars; aspectRatio ∈ 16:9 | 9:16 | 1:1 | 4:5; targetDurationMs ≤ 600000; references ≤ 20, kind ∈ character | branding | place | asset; videoModel/frameModel optional (omit on free keys). Pass projectId to re-plan inside an existing project.

Response: { projectId, plan, models: { videoModel, frameModel, aspectRatio }, cost } — the plan contains the scene list (per-scene prompts, durations) and cost the credit estimate.

Present the plan to the user: scene-by-scene table (scene #, beat, duration, what's on screen), total duration, total estimated credits and USD. Ask: approve, edit specific scenes, or re-plan. Iterate by calling /plan again with the same projectId and a revised prompt until approved.

Step 5 — Confirm budget

curl -sS https://api.capturable.ai/v1/credits/balance -H "X-Api-Key: $CAPTURABLE_API_KEY"

If availableCredits < estimate, say so and stop — the render would be rejected anyway. Top-up happens at https://capturable.ai/settings/billing.

Step 6 — Render

curl -sS -X POST "https://api.capturable.ai/v1/integrations/projects/$PROJECT_ID/render" \
  -H "X-Api-Key: $CAPTURABLE_API_KEY" -H "Content-Type: application/json" \
  -d '{ "videoModel": "capturable-gen2-video", "autoApproveFrames": true }'

202 → { pipelineId, projectId, totalScenes, totalEstimatedCredits, status }.

Set autoApproveFrames: false only when the user wants to inspect keyframes before motion rendering (slower, interactive).

One-shot shortcut (skips the review step — plan + auto-approve + render in one call, same body as /plan plus autoApproveFrames):

POST /v1/integrations/videos/quick   → 202 { pipelineId, projectId, plan, estimatedCost, ... }

Step 7 — Poll

GET /v1/integrations/pipelines/{pipelineId}
GET /v1/integrations/projects/{projectId}/pipeline   (alternative)

Poll every 15–30 s. Renders take minutes, not seconds — multi-scene pipelines run keyframes → motion → post serially. Report stage transitions to the user (e.g. "scene 2/5 rendering"). Individual generation jobs surfaced by the pipeline can be checked with GET /v1/jobs/{jobId}; succeeded jobs include assetUrl — a signed download URL (resolve relative URLs against the API base).

Step 8 — Deliver

Download finished assets with plain curl -o against the signed assetUrl (no auth header needed). Save into the workspace (e.g. capturable/outputs/), tell the user the file path, duration, and final credit cost.

Prompting (director brief quality)

The plan is only as good as the brief. Write the prompt as a director, not a tag list:

• Story spine: hook (first 2 s) → development → payoff/CTA.
• Per-entity descriptions: who/what appears, referencing registered entities by their labels.
• Visual language: camera (slow push-in, handheld, orbit), lighting (golden hour, soft key), mood, color palette, pacing.
• Continuity intent: "the same presenter in every scene", "the bottle is always hero-lit".
• Platform intent: "vertical, hook in the first 2 seconds, text-safe top third" for social.

Example brief:

24-second vertical ad for GlowCo vitamin-C serum. Hook: extreme macro of a serum drop hitting skin in slow motion, morning light. Maya (the presenter) applies the serum in a bright bathroom, talks to camera, casual UGC energy. Cut to a clean product hero on travertine with citrus slices, soft shadows. End: Maya smiling, product held to camera, "Glow starts here" energy. Warm golden palette throughout, consistent presenter and bottle in all scenes.

Errors

Status / code	Meaning	Action
401 unauthorized	Bad/missing key	Check CAPTURABLE_API_KEY
403 plan_upgrade_required	Model not on this plan	Retry omitting videoModel/frameModel (server picks the Gen 2 default); mention upgrade only if the user asked for that model
403 (email engagement)	Free tier requires verified, subscribed email	Tell the user to verify their email on capturable.ai
429	Weekly free video allowance or rate limit hit	Report the limit; suggest waiting or upgrading
409 (render)	No scenes in project	Run /plan first
503 capturable_unavailable	GPU lane busy/down	Wait and retry with backoff

Never retry a 4xx without changing the request. Never invent model IDs — always source them from GET /models.