API reference

Overview

Every generation is a task. You submit a task with a prompt, input assets and an output envelope; the API returns a task identifier immediately. You then poll the task, or receive a webhook, until it reaches a terminal state and returns asset URLs.

• Transport: HTTPS, JSON request and response bodies
• Model: asynchronous tasks with durable state — a dropped connection never loses a render
• Outputs: MP4 delivered over time-limited signed URLs
• Retries: pass an idempotency_key so a retried request does not create a second billable task

Authentication

Authenticate with a bearer token. Keys are scoped to an account and an environment; production and test keys are separate and non-interchangeable.

Authorization: Bearer $TSC_API_KEY

• Store keys in a secret manager, never in client-side code
• Rotate on a schedule; old keys remain valid for a short grace window
• Missing, revoked or wrong-environment keys return 401

Quickstart

Submit a ten-second clip at quality tier, then read the task until it succeeds.

{
  "prompt": "Dolly-in on a rain-slick alley, neon reflections, 35mm",
  "quality": "flagship",
  "aspect_ratio": "16:9",
  "resolution": "1080p",
  "duration": 10,
  "idempotency_key": "ord_8f21"
}

Response:

{
  "id": "gen_5c1e94a7",
  "status": "queued",
  "tier": "quality",
  "created_at": 1762905600
}

Create a generation

Required fields are prompt and the output envelope. Everything else has a documented default.

Field	Type	Description
prompt	string	Natural-language instruction; long prompts are supported
quality	string	flagship, balanced, throughput
resolution	string	480p, 720p, 1080p, 4k (tier dependent)
duration	integer	Seconds; supported range depends on tier
aspect_ratio	string	16:9, 9:16, 1:1, 4:3
input_images	array	Reference and first/last-frame images by URL
input_video	string	Motion or continuation reference
seed	integer	Reuse a seed for comparable output across runs
webhook_url	string	Destination for terminal-state events
idempotency_key	string	Deduplicates retries for 24 hours

Supplying a video input changes the metering basis and may change the eligible tier — the platform validates the combination before scheduling work, so an unsupported combination fails fast instead of after a long queue wait.

Poll status

Status values: queued, running, succeeded, failed, cancelled. On success the response includes asset URLs; on failure a machine-readable error.code and the stage at which it failed.

• Poll with exponential backoff starting around 2 seconds
• Prefer webhooks for long-running or high-volume pipelines
• Asset URLs are time-limited — copy to your own storage on receipt

Webhooks

Register a webhook_url per request or per project. Events are signed with an HMAC header over the raw body; verify the signature before acting on it.

• Delivered at least once — deduplicate on event_id
• Retried with backoff for up to 24 hours on non-2xx responses
• Include the terminal state and asset URLs so no follow-up call is needed

Routing tiers

Tier	Optimised for	Typical duration	Typical resolution
flagship	Fidelity and instruction following	up to 30 s	1080p
balanced	Cost per finished asset	4 – 15 s	480p – 4K
throughput	Iteration speed and volume	4 – 15 s	480p – 720p

Pin a specific model only when you need reproducible characteristics: pinning trades routing flexibility for determinism. The current model set and its identifiers are listed in your access package.

Errors

HTTP	Code	Meaning
400	invalid_request	Malformed body or unsupported parameter combination
401	unauthorized	Missing, revoked or wrong-environment key
402	quota_exhausted	Prepaid balance or monthly cap reached
404	not_found	Unknown task or project
429	rate_limited	Concurrency or request-rate ceiling reached
451	content_policy	Input or output rejected by moderation
5xx	upstream_error	Provider-side failure; retried automatically, not billed

Metering

Usage is metered per successful task and depends on tier, resolution, duration and whether a video input is included. Failed or policy-rejected tasks are not billed. Usage events are queryable per project, which is what makes cost attribution possible without building your own ledger.

Limits

Concurrency is the primary control, not requests per minute: each account has a number of simultaneous render slots per tier. Reserved capacity is available under committed-volume agreements. If you need to burst, describe the workload shape — a campaign launch and steady-state catalog work need different provisioning.

Support

Integration questions go to [email protected]; commercial terms to [email protected]. Include the task id, timestamp and, where relevant, the idempotency_key — it shortens the loop considerably.