Architecture
How the platform is built
A generation request crosses five systems before it becomes a billable asset. This page documents each one, the guarantees around it, and where the operational risk actually sits.
Request lifecycle
Every request is a task, and every task is durable. The platform acknowledges immediately, persists state, and reports progress through polling or webhooks — so a dropped connection never costs a render.
- Submit. Client sends a generation request with an idempotency key. Duplicate submissions return the original task rather than a second render.
- Validate. Schema, quota and entitlement checks run before any paid work is scheduled. Moderation pre-checks reject disallowed prompts at the edge.
- Route. The orchestrator selects a capability tier and a specific model adapter based on the requested quality, resolution and duration.
- Render. The adapter submits to the model provider, tracks the upstream task, and retries or fails over under a defined policy.
- Settle. Outputs are written to object storage, a signed URL is issued, usage is metered, and the final state is emitted as a webhook event.
API gateway
The gateway is the only public surface. It terminates TLS, authenticates bearer credentials, enforces per-account and per-project quotas, and applies request-level idempotency.
- Credential scopes separate production from test traffic
- Rate limits are applied per key, not per IP, so back-office egress NAT does not cause collisions
- Oversized or malformed payloads are rejected before reaching the orchestrator
Orchestration
Video generation is slow and bursty. The orchestrator exists to absorb that: it holds the queue, enforces concurrency ceilings per account, and decides what happens when an upstream provider degrades.
| Mechanism | Behaviour |
|---|---|
| Priority queues | Quality-tier work is scheduled ahead of volume work; a burst of drafts cannot starve a hero render |
| Concurrency ceilings | Per-account caps protect both the provider and the account's own throughput |
| Retry policy | Transient upstream errors are retried with exponential backoff and jitter; deterministic errors are not retried |
| Failover | On sustained upstream failure, the task can re-route to an equivalent model within the same tier |
| Dead-letter | Exhausted tasks are parked with full context for inspection rather than silently dropped |
Routing
Routing is a policy layer, not a model catalogue. Callers ask for a capability envelope — quality tier, resolution, duration, input modalities — and the platform decides which provider fulfils it.
- Tier selection is per request, so cost and quality can differ inside one pipeline
- Regional routing keeps traffic in an appropriate jurisdiction where the provider supports it
- Model-level pinning is available for teams that need reproducible output characteristics
Output pipeline
Rendered assets are written to object storage and served through signed URLs with a TTL. Retention is a policy you set per project; optional replication to your own bucket means assets survive contract changes.
- Signed URLs expire; assets do not, until retention says so
- Optional push to customer-owned storage (S3-compatible) on completion
- Every asset carries a task id, model reference and prompt hash for traceability
Reliability
Availability is easy to promise and hard to evidence. What we can commit to is the mechanism: defined severity levels, named responders, and a written post-incident review for anything above a threshold.
| Area | Target | How it is measured |
|---|---|---|
| API availability | 99.9% monthly | Successful 2xx/4xx responses on the gateway, excluding customer-caused 4xx |
| Task durability | No loss after acceptance | Accepted tasks reach a terminal state or dead-letter, never disappear |
| Incident acknowledgement | Severity 1 within 15 minutes | Time from detection to named owner assigned |
| Status communication | First notice under 30 minutes | Customer-facing update on S1/S2 events |
Enterprise agreements can carry reserved capacity and contractual response targets. The terms live in the order form, not in marketing copy.
Capacity
Generation load follows campaign calendars: quiet for three weeks, then ten times baseline for four days. Capacity planning therefore models peak concurrency per account rather than average monthly volume.
- Baseline concurrency is provisioned per account at onboarding
- Spikes are handled by reserved slots agreed in advance, or by tier degradation with explicit consent
- Our operations team's GPU fleet experience informs hardware-level failure planning upstream
Security posture
The platform is built for procurement review: least-privilege credentials, encrypted transport, separated environments, and an audit trail that can be produced on request.
- TLS 1.2+ in transit; encryption at rest in object storage
- Scoped API keys with rotation and immediate revocation
- Environment separation between test and production credentials
- Access to customer assets restricted to named operational roles, logged
- Security questionnaire, architecture summary and DPA available during onboarding
Data handling
Prompts and outputs are customer content. We do not use customer content to train models, and we do not resell it. Sub-processors are disclosed per region, and deletion requests are honoured on a documented schedule.
Where an engagement requires regional processing, routing is configured so requests are served in that jurisdiction where the upstream provider supports it. Where it does not, we say so before signature rather than after.