Video Generation, Polling & Atomic Settlement
Two-phase async video pipeline, portrait bridge, browser polling vs. 5-minute Cron sweeper, atomic conditional settlement, and 24-hour signed URL expiry rules.
Video generation takes 30 seconds to several minutes upstream. Slloy processes video tasks via a two-phase asynchronous pipeline (server/src/http/routes/video.ts, server/src/videoSettle.ts, and server/src/videoSweeper.ts).
1. Phase 1: Task Creation (POST /api/video/generate)
- Rate Limit & Parameter Normalization:
- Protected by a dedicated rate limiter (
scope: "video",config.videoRateLimitMax = 6requests per minute per user). - Validates
prompt(<= 1500chars),ratio(16:9,9:16,1:1),model(fromvideoModels.ts),resolution(defaults to720pif supported, elsemodel.resolutions[0]), andduration(clamped toconfig.videoDurationsfiltered bymodel.maxDuration; locked to5sforfixedDuration: truemodels). - Validates optional
firstFrameviacheckRefImage()(imageSniff.ts). Models withrequiresFirstFrame: true(wan-i2v-flash,wan-i2v,kling3-i2v) reject requests missingfirstFramewithHTTP 400 FIRST_FRAME_REQUIREDbefore charging credits.
- Protected by a dedicated rate limiter (
- Daily Spending Caps (
videoDailyGuard):- Checks both daily credit and daily CNY spending caps (see Safeguards & Alerts).
- Pre-Charge &
keepAliveUpstream Submission:- Inserts a
generationsrow (kind = 'video',status = 'pending',est_tokens) and deducts credits viarepo.chargeCredit. - Wraps the upstream
provider.createVideoTask()call and DBtaskIdupdate inkeepAlive(c, submit)(ctx.waitUntil) so a client disconnecting mid-submission does not leave an orphan charged row without atask_id. - For per-second priced providers (DashScope and Kling),
costCnyis locked and written to the DB immediately upon task creation (model.provider !== "ark"). For token-billed Ark Seedance,costCnyremainsnulluntil settlement returnsusageTokens.
- Inserts a
- Portrait Bridge for Ark Real-Face Rejection (
portraitBridge.ts):- Volcengine Ark Seedance 2.x rejects first-frame photos containing real human faces with
InputImageSensitiveContentDetected.PrivacyInformation(failCode === "INPUT_PRIVACY"). - When
config.portraitBridgeis enabled and an Ark Seedance 2.x task fails creation withINPUT_PRIVACY,/api/video/generateautomatically invokesbridgePortrait()once: it redraws the first frame into an AI-stylized portrait viaSeedreamimage-to-image (which Ark trusts) and retriescreateVideoTaskwith the bridged frame, returningbridged: truein the response.
- Volcengine Ark Seedance 2.x rejects first-frame photos containing real human faces with
2. Phase 2: Dual-Source Settlement (videoSettle.ts)
Once a video task is created, two independent drivers can settle it:
- Foreground Browser Polling (
GET /api/video/status/:id): Polled every2seconds while the user has the page open (allowTrueUp: true). - Background 5-Minute Cron Sweeper (
server/src/videoSweeper.ts): Scans pending video tasks older thanconfig.videoSweep.minAgeMin(default5minutes) every5minutes (allowTrueUp: false), rescuing videos where the user closed the browser tab before completion.
Both drivers call the exact same functions in server/src/videoSettle.ts (settleVideoGeneration, forceFailVideoGeneration, decideVideoAction) so financial accounting, R2 persistence, and refunds never diverge.
Atomic Conditional Settlement & Row Locking
- Success Path:
- Downloads and persists the video to R2 (
persistImage(t.videoUrl, { genId: gen.id })) before claiming the DB status—because R2 persistence is idempotent, whereas claimingsuccessbefore persisting would make a persistence failure irreversible. - Atomically transitions
generations.statususingrepo.finishGeneration(gen.id, ..., { onlyIfStatus: "pending" }). - Only the caller that receives
claim.changed === trueproceeds to apply any post-settlementsurchargedtrue-up (repo.chargeCredit). If a concurrent driver already settled the row (claim.changed === false),settleVideoGenerationreturns{ handled: false, status: "success", reason: "already_settled" }and the HTTP route reads the freshvideo_urlfrom the DB.
- Downloads and persists the video to R2 (
- Failure & Refund Path (
claimAndRefund/forceFailVideoGeneration):- Calls
repo.failGeneration(gen.id, ...), which acquires a PostgreSQL row lock on thependinggeneration row, setsstatus = 'failed'andfail_code, restores the charged credits tocredit_buckets, and writes a refund ledger entry (GB...) in a single atomic transaction.
- Calls
3. 24-Hour Signed URL Expiry & R2 Persistence Fallback Rules
Upstream video URLs (such as Volcengine Ark TOS URLs containing X-Tos-Expires=86400) are temporary signed links valid for 24 hours. Critically, querying the upstream task API after 24 hours returns the exact same expired signature (it does not re-sign the URL), causing downloads to fail with HTTP 403.
Therefore, settleVideoGeneration() and decideVideoAction() split R2 persistence failures into two distinct outcomes based on task age (waited = Date.now() - created_at) vs. linkTtlHours = 24:
| Upstream Status | R2 Persistence (persisted) | Task Age (waited) | Settlement Outcome | Reason |
|---|---|---|---|---|
succeeded (with videoUrl) | true | Any | success (videoUrl = /uploads/<yyyy>/<mm>/<id>_<rand>.mp4) | Permanent self-hosted R2 object delivered. |
succeeded (with videoUrl) | false (download failed) | < 24 hours (linkTtlHours) | success (Silent Degradation) (videoUrl = t.videoUrl) | Upstream signed link is still valid; user can watch and download immediately while [video] event=persist_failed is logged. |
succeeded (with videoUrl) | false ( or sweeper ageH >= 24h) | >= 24 hours (linkTtlHours) | failed + Full Credit Refund (reason = "artifact_expired", failCode = "ARTIFACT_EXPIRED") | Upstream signed link has expired (403); delivering a dead link is unacceptable. Platform books the upstream costCny and refunds the user's credits. |
succeeded (without videoUrl) | N/A | < 24 hours (urlWaitHours) | wait (reason = "awaiting_url") | Upstream marked task succeeded before populating artifact URL; wait rather than prematurely refunding a billed video. |
succeeded (without videoUrl) | N/A | >= 24 hours (urlWaitHours) | failed + Full Credit Refund (reason = "succeeded_without_url", failCode = "UPSTREAM_ERROR") | Artifact never materialized within the 24h TTL window. |
queued / running | N/A | >= 6 hours (maxAgeHours) | failed + Full Credit Refund (reason = "exceeded_max_age", failCode = "TIMEOUT") | Zombie task stuck upstream beyond the 6-hour hard limit (forceFailVideoGeneration). |
Missing task_id | N/A | >= 6 hours (maxAgeHours) | failed + Full Credit Refund (reason = "no_task_id", failCode = "UPSTREAM_ERROR") | Task creation crashed before recording task_id. |
4. Upstream Cost & Resolution Drift Auditing
During video settlement, settleVideoGeneration performs three financial integrity checks:
- Failed Video Cost Accounting:
- Alibaba DashScope (
DASHSCOPE_VIDEO_PRICE): Explicitly does not bill failed tasks -> failed DashScope tasks recordcostCny = 0(unless locked at creation, in which caseforceFailVideoGenerationsetsisDs ? 0 : ...so failed tasks do not artificially trip the daily CNY spending cap). - Volcengine Ark & Kling: Conservatively book
costCnybased on measured/estimated tokens or locked creation cost even on failure.
- Alibaba DashScope (
- Resolution Mismatch Detection (
res_mismatch):- If the upstream response reports an actual output resolution (
t.actualRes) different fromgen.resolution(e.g., DashScopewan2.2-i2v-flashignoringsizeand defaulting to720pwhen480pwas requested), logs[video] event=res_mismatch level=errorfor billing reconciliation.
- If the upstream response reports an actual output resolution (
- Kling Credit Deduction Drift (
credit_drift):- Kling returns
final_balance_deduction(t.actualCredits). If|actualCredits - costCny| / costCny > 0.15(15%drift, at1 Kling credit ≈ ¥1), logs[video] event=credit_drift level=errorto catch upstream price-table changes or ignored parameter defaults.
- Kling returns
Image Generation Pipeline, Queues & R2 Persistence
Accept-and-queue architecture via Cloudflare Queues, R2 temporary reference image offloading, pure-white product framing, magic-byte R2 persistence, and 10-minute zombie sweepers.
Error Classification & Channel Fault Attribution
How Slloy maps raw upstream errors from Ark, DashScope, and Kling into 11 localized user-facing failCodes and 3 operator fault categories.