Add ModelAPI Seedance 2.5 with Flatkey URLs and GCS delivery

[think-back]

Summary

• Add channel type ModelAPISeedance (111) for https://api.modelapi.co with fixed upstream model doubao-seedance-2-5-260628.
• Translate Flatkey /v1/videos requests to ModelAPI /v1/tasks submit/polling without exposing supplier task IDs, URLs, billing metadata, keys, or brand names.
• Reuse Flatkey's existing asset library through URL-native inputs. ModelAPI Seedance 2.5 has no documented provider asset-library upload/binding API, so strict coverage records a source-URL target, skips provider materialization, and signs the stored GCS source only when the selected channel submits the request.
• Archive successful ModelAPI output into private Google Cloud Storage before reporting success. Clients still receive Flatkey URLs; GET /v1/videos/{task_id}/content returns a short-lived 302 to the private GCS signed download.
• Reuse existing task billing hooks for the documented Seedance 2.5 price tiers, including submit-time correction from a valid private usage.estimated_usd snapshot.
• Convert deterministic ModelAPI capacity rejection to HTTP 429 and allow existing queued channel fallback only for ModelAPISeedance + 429; other task-provider behavior is unchanged.

Upstream contract and pricing

Verified against ModelAPI public documentation on 2026-08-11:

• API documentation: https://api.modelapi.co/v1/models/doubao-seedance-2-5-260628/api-doc
• Model page: https://api.modelapi.co/models/doubao-seedance-2-5-260628/api
• Pricing page: https://api.modelapi.co/pricing

Video input	Resolution	Documented price
No	480p	USD 0.140 * duration
No	720p	USD 0.314 * duration
Yes	480p	USD 0.084 * total_video_duration
Yes	720p	USD 0.188 * total_video_duration

The implementation uses model_price = 0.14 as the existing fixed-price calculation base:

billable_units = estimated_usd / model_price
quota = model_price * billable_units * group_ratio * quota_per_unit

This does not mean every request costs USD 0.14. Missing values follow the documented defaults (duration=5, resolution=720p). For video input, Flatkey cannot safely derive total_video_duration, so it reserves the documented 30-second maximum at the matching input-video rate. A positive finite usage.estimated_usd from a successful submit response replaces that reservation; invalid or missing estimates retain the bounded reservation.

Asset-library behavior

• The Flatkey asset library remains the source of truth; no undocumented ModelAPI asset upload endpoint is called.
• In strict coverage mode, the ModelAPI target becomes active through source-url:modelapi readiness without uploading provider-native material.
• asset://... references are replaced only after final channel selection and only when the active target/readiness/channel/model fences still match.
• Provider-facing GCS input URLs use a dedicated 12-hour TTL so asynchronous ModelAPI consumption is not limited by the one-hour user-facing asset URL cap.
• Accepted task paths extend source-object retention through the existing asset-retention transaction.

Delivery, concurrency, and security

• Public task/content URLs remain Flatkey-owned; upstream success is withheld until the MP4 is durably archived.
• GCS objects remain private and are downloaded through a short-lived signed URL behind Flatkey's 302 endpoint.
• Archive workers atomically claim a task-scoped lease before external download/upload, renew it with a TTL-derived heartbeat, cancel archive work if the lease is lost, and finalize with the latest owner/expiry fence.
• Proxy download clients are cloned and receive both the configured timeout and redirect-time SSRF validation.
• ModelAPI proxy settings are rejected on admin, submit, polling, and archive paths; TechMobi keeps its existing proxy behavior.
• error.code=rate_limit_exceeded or the observed Selected model is at capacity... semantic failure maps to a white-label 429. Raw provider errors remain private.

Production rollout

Required deployment order:

1. Deploy Console/master first so Task AutoMigrate creates the archive lease columns.
2. Deploy Router/API and task workers.

Required configuration:

• ASSET_MODEL_COVERAGE_STRICT_ENABLED=true
• Channel type: ModelAPISeedance / 111
• Base URL: https://api.modelapi.co
• Model: doubao-seedance-2-5-260628
• Proxy: empty
• Fixed model price: 0.14
• Existing private asset GCS configuration, including ASSET_SERVICE_ACCOUNT_EMAIL where IAM signing is used
• Existing private video-result GCS configuration:
  • VIDEO_RESULT_STORAGE_BUCKET
  • VIDEO_RESULT_SERVICE_ACCOUNT_EMAIL
  • optional VIDEO_RESULT_SIGNED_URL_TTL_SECONDS (default 900, maximum 3600)
  • optional VIDEO_RESULT_RETENTION_SECONDS (default 86400)
  • optional VIDEO_RESULT_FETCH_TIMEOUT_SECONDS (default/maximum 1800)
  • optional VIDEO_RESULT_MAX_BYTES (default/maximum 524288000)

Deployment impact:

• Router/API: required
• Console/master: required
• Standalone website: not required
• Terraform: not required
• Cloudflare: not required

Verification

• Spec review: passed for ModelAPI-only 429 fallback, archive lease fencing/heartbeat, and proxy redirect validation.
• Independent final production review: approved with 0 Critical and 0 Important findings after provider input TTL was corrected from the generic one-hour cap to 12 hours.
• Temporary fake/mock regression tests were run locally with a RED/GREEN cycle and removed before commit.
• Fresh targeted ModelAPI billing, request validation, response mapping, archive failure/CAS-loser, and white-label capacity tests passed.
• Fresh compile checks passed for modelapiseedance, taskcommon, relay, middleware, service, and model.
• Scoped go vet passed for all changed backend packages.
• go build ./... passed.
• git diff --check passed; no test/mock files or C-drive paths are included in the commit.

Validation gaps

• No live ModelAPI request was made, intentionally, to avoid consuming the upstream balance.
• No live GCS/IAM request and no staging/production deployment were performed.
• Staging should verify real submit, polling, source-URL fetch, GCS archive creation, Flatkey task/content URLs, signed-download redirect, IAM SignBlob, retention behavior, fallback behavior, and actual settlement before production promotion.
• The exact capacity message is treated as an observed compatibility signal, not as a documented public contract; the documented-style rate_limit_exceeded code remains the primary classification.

[KingCesc]

🤖 OpenCodeReview · 评审 commit ffa8fac8 · 共 2 条

service/video_result_storage.go

• L167: [阻塞] 代理下载分支直接使用 GetHttpClientWithProxy 返回的客户端，未设置 videoResultCheckRedirect。这样虽然首个 upstreamURL 会经过 videoResultValidateURL，但 3xx 跳转后的 URL 会由默认策略自动跟随，可能绕过 SSRF/域名/IP/端口限制并访问内网地址；视频归档接口处理外部 URL 时这是安全风险。建议像直连分支一样对代理客户端克隆后设置 CheckRedirect（必要时也显式设置超时），不要修改共享客户端实例。

baseClient, err := GetHttpClientWithProxy(proxy)
		if err == nil {
			cloned := *baseClient
			cloned.Timeout = cfg.FetchTimeout
			cloned.CheckRedirect = videoResultCheckRedirect
			client = &cloned
		}

service/task_polling.go

• L507-508: [严重] ModelAPI Seedance 成功轮询时会在任务状态 CAS 更新前先执行归档下载/上传；如果两个轮询 worker 同时处理同一任务，它们都会进入这里触发 GCS 归档，后续虽然只有一个 UpdateWithStatus 会赢得结算，但外部归档副作用已经发生，可能造成重复下载/上传、覆盖同一对象或额外资源消耗。建议将归档做成幂等（例如按 taskID 加锁/先查询已存在对象）或把“抢占终态更新”放到归档前，确保只有赢得状态迁移的 worker 执行归档。

case constant.ChannelTypeModelAPISeedance:
				// TODO: ensure archive is guarded by a per-task idempotency lock or only executed by the CAS winner.
				videoResult, archiveErr = archiveModelAPIVideoResult(ctx, task.TaskID, taskResult.Url, proxy)

[think-back]

已在 4eb5d9344 修复这条评论中的两个阻塞项：

1. service/video_result_storage.go：代理 HTTP client 现在先 clone，再设置归档超时和 videoResultCheckRedirect，重定向链继续执行 URL/SSRF 校验。
2. service/task_polling.go / model/task.go：ModelAPI 归档前先原子 claim task lease；归档期间按 lease TTL 动态 heartbeat 续租，丢 lease 会取消 archive context；最终状态 CAS 使用最新 owner/expiry fence，旧 owner 也无法释放新 owner 的 lease。

补充修正：provider-facing 素材 GCS URL 使用独立 12 小时 TTL，避免异步排队超过通用 1 小时下载上限；容量语义失败只在 ModelAPISeedance + 429 进入现有渠道 fallback，不改变其他 task provider。

验证已在 E 盘缓存和黑洞代理环境完成：定向测试、受影响包编译、scoped go vet、go build ./...、git diff --check 均通过。未调用真实 ModelAPI/GCS，临时 mock/测试文件未提交。