capturable-generate

Capturable Generate

Fast single-shot generation against https://api.capturable.ai. Every call needs the header X-Api-Key: $CAPTURABLE_API_KEY. If the env var is unset, stop and point the user to https://capturable.ai/settings/api-keys. Never print the key.

Pick the right operation

User intent	Operation
"Make me an image of …"	Text-to-image job
"Animate this image / make it move"	Image-to-video job
"Make a quick video of …" (single idea, no scene review)	POST /v1/integrations/videos/quick
"A full ad / multi-scene video"	Hand off to capturable-video-director
"What will this cost?"	POST /v1/integrations/quote
"What models can I use?"	GET /v1/integrations/models
"How many credits do I have?"	GET /v1/credits/balance

Discover models first

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

apiAccessMode: "gen2_only" → only provider: capturable-gen2 works (capturable-gen2-image, capturable-gen2-video). "full" → any listed model. Modality-specific lists: GET /v1/generation/available-models?modality=text_to_image (also image_to_video, text_to_video, image_edit).

Text-to-image

Jobs attach to a project. Create one once and reuse its id:

curl -sS -X POST https://api.capturable.ai/v1/projects \
  -H "X-Api-Key: $CAPTURABLE_API_KEY" -H "Content-Type: application/json" \
  -d '{ "title": "Agent generations" }'

Estimate, then submit:

# 1. Estimate (also confirms affordability)
curl -sS -X POST "https://api.capturable.ai/v1/projects/$PROJECT_ID/generation-cost-estimate" \
  -H "X-Api-Key: $CAPTURABLE_API_KEY" -H "Content-Type: application/json" \
  -d '{ "provider": "capturable-gen2", "model": "capturable-gen2-image",
        "request": { "prompt": "…", "aspectRatio": "1:1", "imageCount": 1 } }'

# 2. Submit (202)
curl -sS -X POST "https://api.capturable.ai/v1/projects/$PROJECT_ID/generation-jobs" \
  -H "X-Api-Key: $CAPTURABLE_API_KEY" -H "Content-Type: application/json" \
  -d '{ "provider": "capturable-gen2", "model": "capturable-gen2-image",
        "request": { "prompt": "…", "aspectRatio": "1:1", "imageCount": 1 },
        "idempotencyKey": "<random-uuid>" }'

Aspect ratios: 16:9 | 9:16 | 1:1 | 4:5. Always send a fresh idempotencyKey (UUID) per logical job; reuse it only when retrying the same submit after a network failure.

If canAfford: false on the estimate, report the shortfall and stop.

Image-to-video (animate a still)

Source image options:

• Remote URL: ingest it — POST /v1/integrations/assets/ingest-url { "imageUrl": "https://…" } → { assetId, projectId }.
• Local file: POST /v1/projects/$PROJECT_ID/assets/upload-url { "filename", "mimeType" } → upload the bytes to the returned URL with PUT, then POST /v1/projects/$PROJECT_ID/assets/$ASSET_ID/confirm-upload.

Then submit with the asset as the first frame:

curl -sS -X POST "https://api.capturable.ai/v1/projects/$PROJECT_ID/generation-jobs" \
  -H "X-Api-Key: $CAPTURABLE_API_KEY" -H "Content-Type: application/json" \
  -d '{ "provider": "capturable-gen2", "model": "capturable-gen2-video",
        "firstFrameAssetId": "'$ASSET_ID'",
        "request": { "prompt": "slow cinematic push-in, gentle parallax, soft wind in hair",
                     "durationSeconds": 5, "aspectRatio": "9:16" },
        "idempotencyKey": "<random-uuid>" }'

Motion prompts describe camera + motion + mood, not the image content (the frame already defines it).

Quick video (one call, no review)

curl -sS -X POST https://api.capturable.ai/v1/integrations/videos/quick \
  -H "X-Api-Key: $CAPTURABLE_API_KEY" -H "Content-Type: application/json" \
  -d '{ "prompt": "<full description of the video>", "aspectRatio": "16:9",
        "targetDurationMs": 12000 }'

202 → { pipelineId, projectId, plan, estimatedCost, totalScenes, ... }. This spends credits immediately; for anything over a trivial budget prefer the plan/review flow in capturable-video-director. Poll GET /v1/integrations/pipelines/{pipelineId}.

Quote (free, authoritative)

curl -sS -X POST https://api.capturable.ai/v1/integrations/quote \
  -H "X-Api-Key: $CAPTURABLE_API_KEY" -H "Content-Type: application/json" \
  -d '{ "provider": "capturable-gen2", "model": "capturable-gen2-video", "durationSeconds": 10 }'

Fields: units | durationSeconds (video) | imageCount (images). Quote before any non-trivial spend.

Poll & download

GET /v1/jobs/{jobId}

→ { jobId, status, assetId, assetUrl, errorCode, ... }. Poll every 5–10 s for images, 15–30 s for video until status is succeeded (or failed/cancelled). assetUrl is a signed download URL — if it is relative, resolve it against https://api.capturable.ai. Download with plain curl -o <file> "<assetUrl>" (no auth header needed). Save to capturable/outputs/ in the workspace and report the path.

status: failed → report errorCode; do not blind-retry content-policy failures — rephrase the prompt instead.

Errors

• 401 → key missing/invalid.
• 402 / canAfford: false → insufficient credits; report shortfall.
• 403 plan_upgrade_required → model not on plan; retry with capturable-gen2 defaults, mention upgrade only if the user wanted that specific model.
• 429 → rate limit or free weekly allowance (20 images / 3 video batches per rolling 7 days on free); report and wait.
• 5xx → retry once with backoff, then report.