From fd23dfc0b9cece4d6682273fbf0391d4aada6090 Mon Sep 17 00:00:00 2001 From: Lixi20 Date: Sun, 20 Sep 2026 16:26:49 +0800 Subject: [PATCH] =?UTF-8?q?feat(ai):=20=E5=86=85=E9=83=A8=E5=A5=91?= =?UTF-8?q?=E7=BA=A6=20openapi-internal.yaml=20+=20=E5=83=8F=E7=B4=A0?= =?UTF-8?q?=E5=AF=B9=E7=85=A7=E8=A1=A8=EF=BC=88127=20=E6=B5=8B=E8=AF=95?= =?UTF-8?q?=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 按用户拍板的四点定型 Java↔Python 的 JSON 契约。 **① 字段命名 snake_case**（与对客户端的 camelCase 契约不同，有意为之）：本服务是 Python，snake_case 使 JSON 与领域 dataclass 字段逐一对应、无需转换层；Java 侧只需 在这一个 Feign 客户端上配置命名策略。用 camelCase 反而要在两端都加转换。 **② 两类失败分开**，判别字段是 `error.kind` 而非 HTTP 状态码： - `service`（Java↔Python）：unauthenticated / invalid_request / task_not_found / provider_unavailable / internal_error。属我方 bug 或配置问题。 - `provider`（Python↔服务商）：非 2xx + 完整分类（retry / user_facing / provider_code / message），字段与 Failure 一致，故 Java 侧可复用同一段处置 逻辑，不必为「提交时被限流」和「任务失败于限流」写两套分支。 - **任务失败是第三类，走 200 + state=failed + failure**：查询一个失败的任务， HTTP 调用本身是成功的。做成非 2xx 会让「查不到任务」与「任务失败了」难以区分。 **③ 像素对照表已实现**——此处需更正一个理解：该表**不需要查询任何东西、也不依赖 存储方案**。它是纯静态数据（官方文档「不同宽高比对应的宽高像素值」一节），厂商 查询响应已返回 ratio 与 resolution，查表即可，无需下载产物或解码。故 widthPx/heightPx 在 AI 视频产物上可零成本填真值（ADR-023 §11）。 实现上一个关键观察：**2.5 与 2.0 的 24 格里只有两格不同**（480p 的 16:9 与 9:16），其余完全一致。故写成「共享表 + 两格覆盖」，而非抄两份 24 行——后者每次 改动要改两处，迟早只改一处。另 4k 六格仅 2.0 有。 查不到时返回 None 而不猜（ratio=adaptive、未知模型族、该模型不支持的组合三种 情形）：一个错的尺寸会让客户端按错误比例渲染，且看不出是错的。 连带给 SeedanceTask 补解析响应里的 model 字段——同一适配器实例可能同时处理两个 模型族的任务，按响应里的实际模型定族才对。 **④ 路径参数用服务商任务 ID**，并在契约里写明原因：本服务不持有状态，唯一能用来 问服务商的就是这个 ID；用 job_id 就得存一份映射，「无状态」不再成立，且会多出 一个「Java 有 ID 但查不到任何东西」的中间态。你指出的那点完全对——submit 会阻塞 一次到服务商的短往返才能拿到 ID，但服务商的提交接口本身是异步的（只入队即返回）， 所以这一跳很快。契约里也如实登记了那个**无法消除的窗口**：该调用超时时 Java 拿 不到 ID 而服务商可能已创建任务，无幂等键可用，只能由 max_attempts 兜住。 测试 123 → 127：旧的「像素刻意留空」断言已作废，换成断言真实换算，并覆盖两族 差异的那两格、4k 仅 2.0、adaptive 与未知模型族的留空回退。 Co-Authored-By: Claude Opus 5 (1M context) --- app/providers/volcengine/dimensions.py | 85 +++++ app/providers/volcengine/models.py | 4 + app/providers/volcengine/video.py | 23 +- openapi-internal.yaml | 383 +++++++++++++++++++++++ tests/providers/volcengine/test_video.py | 102 +++++- 5 files changed, 586 insertions(+), 11 deletions(-) create mode 100644 app/providers/volcengine/dimensions.py create mode 100644 openapi-internal.yaml diff --git a/app/providers/volcengine/dimensions.py b/app/providers/volcengine/dimensions.py new file mode 100644 index 0000000..4da6f31 --- /dev/null +++ b/app/providers/volcengine/dimensions.py @@ -0,0 +1,85 @@ +"""`resolution` × `ratio` → 像素宽高的对照表。 + +**这是纯静态数据，不需要查询任何东西、也不依赖存储方案。** 厂商的查询接口会返回 +`ratio` 与 `resolution`（但不返回像素值），查本表即可换算——无需下载产物、无需 +探测文件。数值逐格取自官方文档「不同宽高比对应的宽高像素值」一节。 + +有了它，`widthPx`/`heightPx` 在 AI 视频产物上就能填真实值，而不必等到把文件 +下载下来解码——这也正是 ADR-023 §11 所说「AI 输出路径不需要解码」的落地方式。 + +**实现上的一个关键观察**：Seedance 2.5 与 2.0 系列的 24 格里**只有两格不同** +（480p 的 `16:9` 与 `9:16`），其余完全一致。故实现为「共享表 + 两格覆盖」， +而不是抄两份 24 行——后者每次改动都要改两处，迟早只改一处。 +""" + +from __future__ import annotations + +from .capabilities import SEEDANCE_2_0, SEEDANCE_2_5, ModelLimits + +#: (resolution, ratio) → (width, height)。两个模型族共用的 22 格。 +_SHARED: dict[tuple[str, str], tuple[int, int]] = { + ("480p", "4:3"): (752, 560), + ("480p", "1:1"): (640, 640), + ("480p", "3:4"): (560, 752), + ("480p", "21:9"): (992, 432), + ("720p", "16:9"): (1280, 720), + ("720p", "4:3"): (1112, 834), + ("720p", "1:1"): (960, 960), + ("720p", "3:4"): (834, 1112), + ("720p", "9:16"): (720, 1280), + ("720p", "21:9"): (1470, 630), + ("1080p", "16:9"): (1920, 1080), + ("1080p", "4:3"): (1664, 1248), + ("1080p", "1:1"): (1440, 1440), + ("1080p", "3:4"): (1248, 1664), + ("1080p", "9:16"): (1080, 1920), + ("1080p", "21:9"): (2206, 946), +} + +#: 2.5 与 2.0 系列**唯一**不同的两格：480p 的 16:9 与 9:16。 +_OVERRIDES_2_5: dict[tuple[str, str], tuple[int, int]] = { + ("480p", "16:9"): (854, 480), + ("480p", "9:16"): (480, 854), +} + +_OVERRIDES_2_0: dict[tuple[str, str], tuple[int, int]] = { + ("480p", "16:9"): (864, 496), + ("480p", "9:16"): (496, 864), + # 4k 仅 2.0 系列支持。 + ("4k", "16:9"): (3840, 2160), + ("4k", "4:3"): (3326, 2494), + ("4k", "1:1"): (2880, 2880), + ("4k", "3:4"): (2494, 3326), + ("4k", "9:16"): (2160, 3840), + ("4k", "21:9"): (4398, 1886), +} + +_BY_FAMILY: dict[int, dict[tuple[str, str], tuple[int, int]]] = { + id(SEEDANCE_2_5): {**_SHARED, **_OVERRIDES_2_5}, + id(SEEDANCE_2_0): {**_SHARED, **_OVERRIDES_2_0}, +} + + +def pixels_for( + limits: ModelLimits | None, resolution: str | None, ratio: str | None +) -> tuple[int | None, int | None]: + """查像素宽高；查不到返回 `(None, None)`。 + + 查不到的三种情形都**返回 None 而不猜**——一个错的尺寸比留空更糟，它会让 + 客户端按错误的比例渲染，而且看不出是错的： + + 1. **`ratio` 为 `adaptive`**：厂商在图生视频时自动适配首帧图片的比例。查询 + 响应是否把它解析成具体比例、抑或原样返回 `adaptive`，文档未明确说明； + 原样返回时本表无从查起。 + 2. **未知模型族**：能力表放行了未知模型（见 `capabilities.py`），但像素值 + 无法凭空推断。 + 3. **该模型不支持的组合**：如 2.5 的 4k——本不该发生（提交前已预校验）， + 出现即说明厂商行为与文档不符，留空并让上层看到缺值。 + """ + if limits is None or not resolution or not ratio: + return (None, None) + table = _BY_FAMILY.get(id(limits)) + if table is None: + return (None, None) + found = table.get((resolution, ratio)) + return found if found else (None, None) diff --git a/app/providers/volcengine/models.py b/app/providers/volcengine/models.py index ab3d001..d598d6b 100644 --- a/app/providers/volcengine/models.py +++ b/app/providers/volcengine/models.py @@ -132,6 +132,9 @@ class SeedanceTask: id: str status: SeedanceStatus | None raw_status: str | None + #: 任务实际使用的模型（形如 `doubao-seedance-2-0-260128`）。用于按模型族 + #: 换算像素宽高——同一适配器实例可能同时处理两个模型族的任务。 + model: str | None = None video_url: str | None = None last_frame_url: str | None = None duration_sec: int | None = None @@ -169,6 +172,7 @@ class SeedanceTask: id=str(payload.get("id") or ""), status=SeedanceStatus.parse(raw_status), raw_status=raw_status, + model=payload.get("model"), video_url=content.get("video_url"), last_frame_url=content.get("last_frame_url"), duration_sec=payload.get("duration"), diff --git a/app/providers/volcengine/video.py b/app/providers/volcengine/video.py index 24a5cb4..a84a62d 100644 --- a/app/providers/volcengine/video.py +++ b/app/providers/volcengine/video.py @@ -24,8 +24,10 @@ from app.domain.generation import ( ) from app.providers.base import GenerationProvider +from .capabilities import limits_for from .capabilities import validate as validate_limits from .client import ArkClient +from .dimensions import pixels_for from .models import ( ASSET_URL_TTL_SEC, TASKS_PATH, @@ -149,6 +151,14 @@ class SeedanceVideoProvider(GenerationProvider): ), ) + # 像素宽高由 (模型族, resolution, ratio) 查静态对照表得到——厂商只返回后两者， + # 不返回像素值。查表不需要下载产物也不需要解码，故 widthPx/heightPx 在 AI + # 视频产物上可零成本填真值（ADR-023 §11）。查不到时留空而不猜：一个错的 + # 尺寸会让客户端按错误比例渲染，且看不出是错的。 + width_px, height_px = pixels_for( + limits_for(self._model_of(task)), task.resolution, task.ratio + ) + return GenerationResult( provider_request_id=request_id, state=state, @@ -160,14 +170,23 @@ class SeedanceVideoProvider(GenerationProvider): cover_url=task.last_frame_url, ratio=task.ratio, resolution=task.resolution, - # 像素尺寸留空：火山只返回 ratio 与 resolution，换算需要一张随模型族 - # 变化的对照表。在 V7 目录种子定下模型族之前不编造尺寸。 + width_px=width_px, + height_px=height_px, duration_ms=task.duration_ms, output_format=task.output_format, failure=failure, billing_tokens=task.completion_tokens, ) + def _model_of(self, task: SeedanceTask) -> str: + """任务所用的模型。 + + 查询响应带 `model` 字段（形如 `doubao-seedance-2-0-260128`），优先用它—— + 这样同一个适配器实例处理不同模型的任务时，像素换算也能各按其族。缺失时 + 才回落到配置的默认模型。 + """ + return task.model or self._default_model + @staticmethod def _map_state(task: SeedanceTask) -> TaskState: match task.status: diff --git a/openapi-internal.yaml b/openapi-internal.yaml new file mode 100644 index 0000000..09c184f --- /dev/null +++ b/openapi-internal.yaml @@ -0,0 +1,383 @@ +openapi: 3.1.0 + +info: + title: patbond-ai 内部接口 + version: 0.1.0 + description: | + `patbond-creation`（Java）调用 `patbond-ai`（Python）执行 AI 生成的内部契约。 + + **这份契约不对客户端暴露**，与 `patbond-doc/docs/api/openapi.yaml` 是两份独立 + 文档、独立版本号（ADR-023 §4）。刻意不合并：内部适配端点若进入公开契约，会污染 + 其路径/操作计数，也会让「对客户端的承诺」与「对内部实现的约定」混为一谈。 + 本文档也**不进** patbond-api 的四模块快照锁。 + + ## 字段命名为 snake_case + + 与项目对客户端的 camelCase 契约不同。这是有意的：本服务是 Python，snake_case + 使 JSON 与领域 dataclass 字段逐一对应、无需转换层；Java 侧只需在这一个 Feign + 客户端上配置命名策略。**用 camelCase 反而要在两端都加转换。** + + ## 两类失败必须分开（本契约的核心设计） + + | 类别 | 含义 | 形态 | + | --- | --- | --- | + | **service** | Java↔Python 之间的问题：鉴权失败、请求体非法、任务不存在、本服务内部错误、适配器未装配 | 非 2xx + `error.kind = "service"` | + | **provider** | Python↔AI 服务商之间的问题：限流、配额耗尽、内容被拒、厂商内部错误 | 非 2xx + `error.kind = "provider"`，**并携带完整分类** | + | **任务失败** | HTTP 调用本身成功，但生成任务最终失败 | **200** + `state = "failed"` + `failure` | + + 第三类刻意不走错误通道：查询一个失败的任务，**HTTP 请求是成功的**，失败的是 + 任务。把它做成非 2xx 会让「查不到任务」与「任务失败了」难以区分。 + + 判别字段是 `error.kind`，**不是 HTTP 状态码**。Java 侧据此分流： + `service` 类属我方 bug 或配置问题（除 `internal_error`/`provider_unavailable` + 外均不可重试）；`provider` 类一律以 `retry` 字段为准，不要自己解读厂商码。 + + ## 鉴权 + + 所有端点要求服务身份 JWT：`Authorization: Bearer `。本服务强制校验 + `aud = patbond-ai` 与 `typ = service`（ADR-023 §5）。用户 token 一律拒绝—— + 该密钥对与用户 token 的密钥对是独立的两套。 + +servers: + - url: http://127.0.0.1:8000 + description: 本机开发 + - url: http://patbond-ai:8000 + description: 容器网络内 + +security: + - serviceJwt: [] + +paths: + /internal/generation/tasks: + post: + summary: 提交生成任务 + operationId: submitGenerationTask + description: | + 把任务交给上游服务商，返回**服务商的任务 ID**。 + + **不阻塞等待生成完成。** 但会阻塞一次到服务商的短往返——服务商的提交接口 + 本身是异步的（只入队即返回任务 ID），所以这一跳很快。 + + 调用方**必须在上游产生任何计费动作之前**把返回的 `provider_request_id` + 落库：火山不支持幂等键，这是提交超时后唯一能判断「是否已提交」的依据。 + + **一个无法消除的窗口**：若本服务到服务商的调用超时，调用方会收到 + `provider` 类错误且拿不到 ID，而服务商**可能已经创建了任务**。无幂等键可用， + 该窗口只能由 `max_attempts` 兜住（ADR-023 §4 已如实登记）。服务商支持 + 回调，将来启用回调可作为孤儿任务的回收通道。 + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/SubmitRequest' + responses: + '200': + description: 已提交 + content: + application/json: + schema: + $ref: '#/components/schemas/SubmitResponse' + '400': + $ref: '#/components/responses/ServiceError' + '401': + $ref: '#/components/responses/ServiceError' + '502': + $ref: '#/components/responses/ProviderError' + '503': + $ref: '#/components/responses/ServiceError' + + /internal/generation/tasks/{provider_request_id}: + get: + summary: 查询生成任务 + operationId: getGenerationTask + description: | + 路径参数是**服务商的任务 ID**，不是我方 `job_id`。 + + 这是刻意的：本服务不持有任何状态，唯一能用来问服务商的就是这个 ID。若用 + `job_id`，本服务就得存一份 `job_id → 厂商 ID` 的映射，「无状态」不再成立， + 且会多出一个「Java 有 ID 但查不到任何东西」的中间态。 + + 注意火山**只保留最近 7 天**的任务记录，更早的任务会以 `provider` 类错误 + 返回。 + parameters: + - name: provider_request_id + in: path + required: true + schema: + type: string + example: cgt-20260920-abc123 + responses: + '200': + description: | + 任务当前状态。**任务失败也是 200** —— HTTP 调用成功了，失败的是任务。 + content: + application/json: + schema: + $ref: '#/components/schemas/TaskResponse' + '401': + $ref: '#/components/responses/ServiceError' + '404': + $ref: '#/components/responses/ServiceError' + '502': + $ref: '#/components/responses/ProviderError' + '503': + $ref: '#/components/responses/ServiceError' + +components: + securitySchemes: + serviceJwt: + type: http + scheme: bearer + bearerFormat: JWT + description: | + 由 `patbond-creation` 用**独立于用户 token 的**密钥对签发。claim 约定： + `iss=patbond-api`、`aud=patbond-ai`、`sub=service:creation-worker`、 + `typ=service`、短 `exp`（5 分钟）、带 `jti`。 + + responses: + ServiceError: + description: Java↔Python 之间的问题 + content: + application/json: + schema: + $ref: '#/components/schemas/ServiceErrorEnvelope' + ProviderError: + description: Python↔服务商之间的问题，携带完整分类 + content: + application/json: + schema: + $ref: '#/components/schemas/ProviderErrorEnvelope' + + schemas: + SubmitRequest: + type: object + required: [job_id, media_kind, model] + description: | + **刻意不含 `user_id`**（数据最小化，ADR-023 §5）：本服务干活只需要任务参数。 + 需要给服务商做滥用检测时传的是 `safety_identifier`——一个哈希，不是明文 ID。 + properties: + job_id: + type: string + format: uuid + description: | + 我方任务 ID。**本服务不用它查任何东西**，仅用于日志关联，使一条报错能 + 对应回 `creation.generation_jobs` 的行。 + media_kind: + type: string + enum: [image, video] + description: 决定路由到哪个适配器。 + model: + type: string + description: | + 服务商侧的模型标识，取自任务行冻结的 `provider_model_snapshot`。 + **本服务不自行选模型**：选型是目录的职责，且任务行里的快照必须与实际 + 调用的模型一致，否则事后无法对账。 + example: doubao-seedance-2-5-260628 + prompt: + type: [string, 'null'] + maxLength: 10000 + description: 与 `input_url` **至少要有一个**，都为空则本地即拒。 + input_url: + type: [string, 'null'] + description: | + 参考图/首帧的**公网可达** URL。给了即图生视频，不给即文生视频 + （参考图选填，决策 A2）。 + ratio: + type: [string, 'null'] + description: | + 缺省 `adaptive`。**会按模型限制本地预校验**：Seedance 2.5 在图生视频时 + 只支持 `adaptive`，指定具体比例会被本服务直接拒（省掉一次往返）。 + example: adaptive + resolution: + type: [string, 'null'] + description: | + 缺省 `720p`。按模型预校验：2.5 无 4k，2.0 系列有。 + example: 720p + duration_sec: + type: [integer, 'null'] + description: | + 缺省 5。按模型预校验：2.5 为 `[4,30]`，2.0 系列为 `[4,15]`； + `-1` 表示由模型自选，不参与范围校验。 + generate_audio: + type: boolean + default: true + watermark: + type: boolean + default: false + safety_identifier: + type: [string, 'null'] + maxLength: 64 + description: | + 终端用户标识，供服务商做滥用检测。**必须是哈希值，不可传明文用户 ID**。 + callback_url: + type: [string, 'null'] + description: | + 预留，当前不启用（ADR-023 §4：轮询为保证，回调为优化）。留此字段使 + 将来启用无需改契约。 + upload_target: + type: [string, 'null'] + description: | + 产物的预签名 PUT 地址。**当前不启用**——转存阻塞于对象存储决策 + （ADR-023 §7）。启用后本服务会把产物直传该地址，从而无需持有任何 + 对象存储凭证。 + + SubmitResponse: + type: object + required: [provider_request_id] + properties: + provider_request_id: + type: string + description: 服务商任务 ID。调用方须在上游计费前落库。 + example: cgt-20260920-abc123 + + TaskResponse: + type: object + required: [provider_request_id, state, progress] + properties: + provider_request_id: + type: string + state: + type: string + enum: [pending, running, succeeded, failed, cancelled] + description: | + **刻意比服务商的状态集更小。** 火山有 queued/running/cancelled/ + succeeded/failed/expired 六个：`queued` 映射为 `pending`，`expired` + 归入 `failed`（它是超时，属失败的一种，重试策略由 `failure` 表达， + 不需要独立状态）。 + progress: + type: integer + minimum: 0 + maximum: 100 + description: | + 火山不返回百分比，故成功前恒 0、成功即 100。**这不是缺陷**：客户端 + 契约本就不承诺平滑进度（ADR-023 §10），一个诚实的 0 不该被读成「卡住」。 + asset_url: + type: [string, 'null'] + description: | + 产物 URL。**可能是有时效的服务商地址**——火山为 24 小时。调用方必须在 + 时效内转存，**不可长期保存此值**（存进 `media.assets.external_url` + 会在 24 小时后变死链）。 + asset_url_expires_in_sec: + type: [integer, 'null'] + description: | + `asset_url` 的剩余有效期。与 URL 一起给出，使调用方没有理由把它当 + 永久地址。火山为 86400。 + cover_url: + type: [string, 'null'] + description: | + 封面图 URL。火山的尾帧图（png、尺寸与视频一致、无水印）可免费充当此 + 用途，省掉抽帧。 + ratio: + type: [string, 'null'] + resolution: + type: [string, 'null'] + width_px: + type: [integer, 'null'] + description: | + 由 (模型族, resolution, ratio) 查静态对照表得到，**不需要下载产物或 + 解码**。`ratio` 为 `adaptive` 或模型族未知时为 `null`——留空而不猜， + 一个错的尺寸会让客户端按错误比例渲染且看不出是错的。 + height_px: + type: [integer, 'null'] + duration_ms: + type: [integer, 'null'] + description: | + 有 `frames`+`fps` 时按帧精确换算；只有服务商的整数秒时退回它，而那是 + 「帧数/24 向下取整」的**约数**（最多可能短 1 秒）。两者都缺时为 null， + 不编 0。 + output_format: + type: [string, 'null'] + example: mp4 + billing_tokens: + type: [integer, 'null'] + description: 计费对账依据（火山为 `usage.completion_tokens`）。 + failure: + oneOf: + - $ref: '#/components/schemas/Failure' + - type: 'null' + description: | + 仅 `state = failed` 时非空。**`failed` 必然携带它**——否则调用方无法 + 决定重试策略，只能盲目重试或盲目放弃，两者都错。 + + Failure: + type: object + required: [retry, user_facing, provider_code] + properties: + retry: + type: string + enum: [never, backoff, quota] + description: | + **Worker 据此决定重试，不必解读服务商码。** + `never`：同样输入必然同样结果（参数错、内容被拒、鉴权失败）。 + `backoff`：限流、突发流量保护、服务过载，退避几秒到几十秒。 + `quota`：额度耗尽，要等到下一个计费周期或充值——不该把重试预算花在 + 这上面，应直接终态失败并让用户看到出口。 + user_facing: + type: string + enum: + [quota_exhausted, rate_limited, content_rejected, server_error, upstream_unavailable] + description: | + 映射到客户端呈现。`quota_exhausted` 与 `rate_limited` **必须分开**： + 前者等的是明天或充值（弹 sheet 给出口），后者等的是几秒（弹 SnackBar + 可自动重试）。合成一类必然有一半场景的文案和出口是错的（ADR-023 §9）。 + provider_code: + type: string + description: | + 原始服务商错误码，**原样保留、绝不丢弃**——排查时往往是唯一线索。 + 上层不应据此分支判断（那是适配层的职责），只记录与展示给开发者。 + example: OutputVideoSensitiveContentDetected + message: + type: string + description: 服务商原始错误描述，仅供排查与开发者可见的日志。 + + ServiceErrorEnvelope: + type: object + required: [error] + properties: + error: + type: object + required: [kind, code, message] + properties: + kind: + type: string + const: service + code: + type: string + enum: + - unauthenticated # 服务票缺失/过期/aud 或 typ 不符 + - invalid_request # 请求体不合契约，或参数超出模型限制 + - task_not_found # 路径里的服务商任务 ID 不存在 + - provider_unavailable # 适配器未装配（如缺凭证）或 provider_code 未知 + - internal_error # 本服务 bug + message: + type: string + + ProviderErrorEnvelope: + type: object + required: [error] + description: | + 服务商调用失败。**与任务失败（200 + state=failed）是两回事**：这里是调用 + 没成功，那里是调用成功但任务最终失败。 + properties: + error: + type: object + required: [kind, retry, user_facing, provider_code, message] + description: | + 字段与 `Failure` 一致，故 Java 侧可复用同一段分类处置逻辑，无需为 + 「提交时被限流」和「任务失败于限流」写两套分支。 + properties: + kind: + type: string + const: provider + retry: + type: string + enum: [never, backoff, quota] + user_facing: + type: string + enum: + [quota_exhausted, rate_limited, content_rejected, server_error, upstream_unavailable] + provider_code: + type: string + message: + type: string diff --git a/tests/providers/volcengine/test_video.py b/tests/providers/volcengine/test_video.py index 029d9ba..dc38a60 100644 --- a/tests/providers/volcengine/test_video.py +++ b/tests/providers/volcengine/test_video.py @@ -382,21 +382,105 @@ class TestCoverImage: assert provider_with(handler).fetch("x").cover_url == "https://f.png" -class TestPixelDimensionsAreLeftBlankOnPurpose: - def test_no_invented_dimensions(self): - """火山只返回 ratio 与 resolution，不返回像素值。 +class TestPixelDimensions: + """厂商只返回 ratio 与 resolution，像素值由静态对照表换算。 - 换算需要一张随模型族变化的对照表；在 V7 目录种子定下模型族之前， - 留空比编一个可能错的尺寸好。 - """ + 不需要下载产物、不需要解码、不依赖存储方案——这是 widthPx/heightPx 在 AI + 视频产物上能零成本填真值的依据（ADR-023 §11）。 + """ + + def test_derived_from_ratio_and_resolution(self): + # 官方表：2.0 系列 720p + 16:9 = 1280×720。 result = provider_with( lambda r: httpx.Response(200, json=OFFICIAL_SUCCESS_PAYLOAD) ).fetch("x") - assert result.width_px is None - assert result.height_px is None - # 但原始信息要透出，供上层或后续实现换算。 + assert (result.width_px, result.height_px) == (1280, 720) + # 原始信息同时透出，便于排查与将来复核。 assert (result.ratio, result.resolution) == ("16:9", "720p") + def test_the_two_cells_where_the_families_differ(self): + """2.5 与 2.0 的 24 格里只有两格不同：480p 的 16:9 与 9:16。 + + 这两格若搞错，客户端会按错误比例渲染 480p 视频且看不出是错的。 + """ + + def payload(model: str) -> dict: + return { + "id": "x", + "model": model, + "status": "succeeded", + "resolution": "480p", + "ratio": "16:9", + "content": {"video_url": "https://v"}, + } + + result_2_5 = provider_with( + lambda r: httpx.Response(200, json=payload("doubao-seedance-2-5-260628")) + ).fetch("x") + result_2_0 = provider_with( + lambda r: httpx.Response(200, json=payload("doubao-seedance-2-0-260128")) + ).fetch("x") + assert (result_2_5.width_px, result_2_5.height_px) == (854, 480) + assert (result_2_0.width_px, result_2_0.height_px) == (864, 496) + + def test_4k_resolves_only_on_2_0(self): + def handler(request): + return httpx.Response( + 200, + json={ + "id": "x", + "model": "doubao-seedance-2-0-260128", + "status": "succeeded", + "resolution": "4k", + "ratio": "16:9", + "content": {"video_url": "https://v"}, + }, + ) + + result = provider_with(handler).fetch("x") + assert (result.width_px, result.height_px) == (3840, 2160) + + def test_adaptive_ratio_yields_none_rather_than_a_guess(self): + """`adaptive` 时厂商自动适配首帧比例，本表无从查起。 + + 留空而不猜：一个错的尺寸会让客户端按错误比例渲染，而且看不出是错的。 + """ + + def handler(request): + return httpx.Response( + 200, + json={ + "id": "x", + "model": "doubao-seedance-2-5-260628", + "status": "succeeded", + "resolution": "720p", + "ratio": "adaptive", + "content": {"video_url": "https://v"}, + }, + ) + + result = provider_with(handler).fetch("x") + assert (result.width_px, result.height_px) == (None, None) + # 但原始值仍透出，上层至少知道厂商说了什么。 + assert result.ratio == "adaptive" + + def test_unknown_model_family_yields_none(self): + def handler(request): + return httpx.Response( + 200, + json={ + "id": "x", + "model": "some-future-model", + "status": "succeeded", + "resolution": "720p", + "ratio": "16:9", + "content": {"video_url": "https://v"}, + }, + ) + + result = provider_with(handler).fetch("x") + assert (result.width_px, result.height_px) == (None, None) + class TestPerModelLimitsAreEnforcedBeforeCallingTheVendor: """超范围的请求本地就拦下，不花一次往返去换一个厂商 400。