patbond-ai/app/providers/seedance.py

"""火山方舟 Seedance 视频生成客户端。

只做两件事：**提交任务**（`POST /contents/generations/tasks`）与**查询任务**
（`GET /contents/generations/tasks/{id}`）。产物的转存不在这里——见
`SeedanceTask.video_url` 的说明。

## 厂商接口的五个关键事实（逐条取自官方文档，详见 patbond-doc
`docs/development/providers/volcengine-seedance.md`）

1. **没有幂等键。** 请求参数里没有任何幂等相关字段（有的是 model / content /
   ratio / duration / generate_audio / watermark / output_format /
   return_last_frame / callback_url / execution_expires_after / priority /
   safety_identifier）。因此「提交超时后不知道有没有扣费」这个窗口**无法靠厂商
   的幂等头消除**，只能由 `max_attempts` 兜住。这与原先的乐观假设不同，已如实
   登记而非假装解决。
   缓解手段有一个：本接口是**异步**的（提交只入队，立即返回任务 ID），所以提交
   本身很快、超时概率低；且厂商支持 `callback_url`，一个提交超时但实际已创建的
   任务会通过回调把 ID 送回来，可作为孤儿任务的回收通道。
2. **提交是异步的**：返回 `{"id": ...}`，随后靠查询接口拿状态。这正好与
   「Java↔Python 边界一律异步」的既定设计吻合，无需在本服务内部做后台任务承载。
3. **产物是有效期 24 小时的 URL**（Seedance 2.5 另有 100 次下载上限）。
   **因此产物必须转存**——把厂商 URL 直接存进 `media.assets.external_url`
   会在 24 小时后变成死链。这一条对「本地存储还是云存储」的决策是硬约束：
   无论选哪个，都必须在 24 小时内把文件复制到我们自己的存储。
4. **任务记录只保留 7 天**，`execution_expires_after` 取值范围 `[3600, 259200]`
   秒（默认 48 小时）。超时任务被标记为 `expired`。
5. **限流与配额是两族不同的 429**，映射见 `errors.py`。

## 一个文档自身的矛盾，必须按宽的那份实现

查询接口文档列的状态是 queued / running / cancelled / succeeded / failed 五个，
但创建接口的 `callback_url` 一节额外列了 **`expired`**。只按查询文档实现，线上
遇到超时任务会掉进未知分支。这里按六个状态实现，并把 `expired` 当作**可重试的
失败**（是超时而非内容问题）。
"""

from __future__ import annotations

import logging
from dataclasses import dataclass
from enum import Enum
from typing import Any

import httpx

from .errors import Classification, Retry, UserFacing, classify

log = logging.getLogger(__name__)

#: 官方 base URL（北京区）。
DEFAULT_BASE_URL = "https://ark.cn-beijing.volces.com/api/v3"

_TASKS_PATH = "/contents/generations/tasks"


class TaskStatus(Enum):
    """厂商任务状态。

    六个取值：查询文档给了五个，`expired` 来自创建文档的回调说明一节。
    """

    QUEUED = "queued"
    RUNNING = "running"
    SUCCEEDED = "succeeded"
    FAILED = "failed"
    CANCELLED = "cancelled"
    #: 任务在排队或运行中超过 `execution_expires_after` 被自动终止。
    #: **查询接口文档未列出此值**，仅见于创建接口的回调状态说明。
    EXPIRED = "expired"

    @classmethod
    def parse(cls, value: str | None) -> TaskStatus | None:
        """未知状态返回 None 而不是抛异常。

        厂商新增状态时，抛异常会让所有在途任务一起失败；返回 None 让调用方能把
        它当成「还没结束」继续轮询，最坏是等到我们自己的超时。
        """
        for status in cls:
            if status.value == value:
                return status
        return None

    @property
    def is_terminal(self) -> bool:
        return self in {
            TaskStatus.SUCCEEDED,
            TaskStatus.FAILED,
            TaskStatus.CANCELLED,
            TaskStatus.EXPIRED,
        }


@dataclass(frozen=True)
class SeedanceTask:
    """查询接口返回的任务。

    :param video_url: 生成视频的 URL，**有效期仅 24 小时**。本服务不负责转存，
        但调用方必须在有效期内完成转存——把它长期存为 `external_url` 会变死链。
    :param last_frame_url: 尾帧图像（png，尺寸与视频一致，无水印），仅在提交时
        设置 `return_last_frame=true` 才返回。可直接用作**视频封面图**，省掉
        我们自己抽帧。
    :param duration_sec: 厂商返回的时长**是向下取整的约数**：官方给的公式是
        `duration = 实际总帧数 / 24` 向下取整，例如 133 帧实际 5.54 秒会返回 5。
        因此据此换算出的 `duration_ms` 最多可能短 1 秒左右，不可当精确值用。
    :param frames: 与 `duration_sec` **只会返回其中一个**（提交时指定了 frames
        才返回 frames）。两者都在时以 frames 为准。
    """

    id: str
    status: TaskStatus | None
    raw_status: str | None
    video_url: str | None = None
    last_frame_url: str | None = None
    duration_sec: int | None = None
    frames: int | None = None
    fps: int | None = None
    ratio: str | None = None
    resolution: str | None = None
    output_format: str | None = None
    error_code: str | None = None
    error_message: str | None = None
    completion_tokens: int | None = None
    created_at: int | None = None
    updated_at: int | None = None

    @property
    def duration_ms(self) -> int | None:
        """尽可能精确的时长毫秒数。

        有 `frames` + `fps` 时按帧算（精确）；否则退回厂商返回的整数秒
        （**向下取整的约数**，见类 docstring）。两者都缺则返回 None，而不是
        编一个 0 出来。
        """
        if self.frames is not None and self.fps:
            return round(self.frames / self.fps * 1000)
        if self.duration_sec is not None:
            return self.duration_sec * 1000
        return None

    @property
    def failure(self) -> Classification | None:
        """失败任务的分类；非失败返回 None。

        `expired` 单独处理：它是超时，不是内容或参数问题，因此可重试——而厂商
        在 expired 时不一定给 `error.code`，若走通用分类会被当成「无码」处理。
        """
        if self.status is TaskStatus.EXPIRED:
            return Classification(
                Retry.BACKOFF, UserFacing.UPSTREAM_UNAVAILABLE, "TaskExpired"
            )
        if self.status is TaskStatus.FAILED:
            return classify(self.error_code, self.error_message)
        return None


@dataclass
class SeedanceSubmission:
    """一次提交所需的全部参数。

    刻意不把厂商的全部参数都暴露出来——只暴露 Patbond 会用到的。多暴露一个参数
    就多一处需要在契约、客户端、文档三处同步维护的地方。
    """

    model: str
    prompt: str | None = None
    #: 首帧图片 URL。给了即为图生视频，不给即为文生视频（参考图选填，决策 A2）。
    first_frame_url: str | None = None
    #: 宽高比。`adaptive` 让模型自适应；图生视频时 Seedance 2.5 只支持 adaptive。
    ratio: str = "adaptive"
    resolution: str = "720p"
    #: 时长（秒）。`-1` 交给模型在有效范围内自选。
    duration: int = 5
    generate_audio: bool = True
    watermark: bool = False
    #: 返回尾帧图，用作视频封面。默认开启——成本为零，省掉我们自己抽帧。
    return_last_frame: bool = True
    #: 任务超时阈值（秒）。取值范围 [3600, 259200]。**默认 48 小时对交互式应用
    #: 过长**，故这里取下限 1 小时，避免被放弃的任务在厂商侧挂两天。
    execution_expires_after: int = 3600
    #: 终端用户哈希标识，助厂商做滥用检测。**必须是哈希值，不可传明文用户 ID**。
    safety_identifier: str | None = None
    callback_url: str | None = None

    def to_body(self) -> dict[str, Any]:
        content: list[dict[str, Any]] = []
        if self.prompt:
            content.append({"type": "text", "text": self.prompt})
        if self.first_frame_url:
            # role 省略时厂商按 first_frame 处理；显式写出以免依赖默认行为。
            content.append(
                {
                    "type": "image_url",
                    "image_url": {"url": self.first_frame_url},
                    "role": "first_frame",
                }
            )
        if not content:
            raise ValueError("提交内容为空：prompt 与 first_frame_url 至少要有一个")

        body: dict[str, Any] = {
            "model": self.model,
            "content": content,
            "ratio": self.ratio,
            "resolution": self.resolution,
            "duration": self.duration,
            "generate_audio": self.generate_audio,
            "watermark": self.watermark,
            "return_last_frame": self.return_last_frame,
            "execution_expires_after": self.execution_expires_after,
        }
        if self.safety_identifier:
            body["safety_identifier"] = self.safety_identifier
        if self.callback_url:
            body["callback_url"] = self.callback_url
        return body


class SeedanceError(RuntimeError):
    """厂商返回的错误，带分类。"""

    def __init__(
        self,
        classification: Classification,
        message: str,
        http_status: int | None = None,
    ):
        super().__init__(message)
        self.classification = classification
        self.http_status = http_status


class SeedanceClient:
    """Seedance 的同步 HTTP 客户端。

    **超时设置的含义**：这里的 timeout 是「提交/查询这一次 HTTP 往返」的超时，
    **不是生成耗时**。提交接口是异步的（只入队），所以几秒足够；把它调大成
    「等出图」是错的，会重新引入长连接占用与计费歧义。
    """

    def __init__(
        self,
        api_key: str,
        base_url: str = DEFAULT_BASE_URL,
        timeout: float = 10.0,
        client: httpx.Client | None = None,
    ):
        if not api_key:
            raise ValueError("ARK_API_KEY 未配置")
        self._api_key = api_key
        self._base_url = base_url.rstrip("/")
        self._client = client or httpx.Client(timeout=timeout)

    def submit(self, submission: SeedanceSubmission) -> str:
        """提交任务，返回厂商任务 ID。

        调用方必须在**上游产生任何计费动作之前**把这个 ID 落库——那是超时后
        唯一能判断「是否已提交」的依据。本接口异步，返回即代表已入队。
        """
        response = self._post(_TASKS_PATH, submission.to_body())
        task_id = response.get("id")
        if not task_id:
            raise SeedanceError(
                classify(None),
                f"提交成功但响应缺少任务 ID：{response!r}",
            )
        return str(task_id)

    def get(self, task_id: str) -> SeedanceTask:
        """查询任务。

        注意厂商只保留最近 7 天的任务记录；更早的任务查询会 404。
        """
        payload = self._get(f"{_TASKS_PATH}/{task_id}")
        return self._parse_task(payload)

    # ---------------------------------------------------------------- 内部

    def _headers(self) -> dict[str, str]:
        return {
            "Authorization": f"Bearer {self._api_key}",
            "Content-Type": "application/json",
        }

    def _post(self, path: str, body: dict[str, Any]) -> dict[str, Any]:
        try:
            response = self._client.post(
                f"{self._base_url}{path}", json=body, headers=self._headers()
            )
        except httpx.HTTPError as exc:
            # 网络层失败：可重试。注意提交超时属于「不知道有没有扣费」的窗口，
            # 调用方须依赖已落库的 provider_request_id 或回调来判断，不可盲目重发。
            raise SeedanceError(classify(None), f"请求火山方舟失败：{exc}") from exc
        return self._unwrap(response)

    def _get(self, path: str) -> dict[str, Any]:
        try:
            response = self._client.get(
                f"{self._base_url}{path}", headers=self._headers()
            )
        except httpx.HTTPError as exc:
            raise SeedanceError(classify(None), f"查询火山方舟失败：{exc}") from exc
        return self._unwrap(response)

    @staticmethod
    def _unwrap(response: httpx.Response) -> dict[str, Any]:
        """把 HTTP 响应转成 dict，非 2xx 转成带分类的 SeedanceError。

        错误体形态取自官方错误码表：`{"error": {"code": ..., "message": ...}}`。
        响应体解析失败时不静默——那通常意味着我们打到了错误的地址（比如把
        网关的 HTML 错误页当成了 JSON）。
        """
        if response.is_success:
            try:
                return response.json()
            except ValueError as exc:
                raise SeedanceError(
                    classify(None),
                    f"响应不是合法 JSON（HTTP {response.status_code}）：{response.text[:200]}",
                    response.status_code,
                ) from exc

        code: str | None = None
        message = response.text[:500]
        try:
            error = response.json().get("error") or {}
            code = error.get("code")
            message = error.get("message") or message
        except ValueError:
            pass

        classification = classify(code, message)
        log.warning(
            "火山方舟返回错误 http=%s code=%s retry=%s",
            response.status_code,
            code,
            classification.retry.value,
        )
        raise SeedanceError(classification, message, response.status_code)

    @staticmethod
    def _parse_task(payload: dict[str, Any]) -> SeedanceTask:
        content = payload.get("content") or {}
        error = payload.get("error") or {}
        usage = payload.get("usage") or {}
        raw_status = payload.get("status")
        status = TaskStatus.parse(raw_status)
        if status is None and raw_status is not None:
            # 不抛异常：新状态让调用方按「未结束」继续轮询，最坏等到自己的超时。
            log.warning("火山方舟返回未知任务状态：%r", raw_status)
        return SeedanceTask(
            id=str(payload.get("id") or ""),
            status=status,
            raw_status=raw_status,
            video_url=content.get("video_url"),
            last_frame_url=content.get("last_frame_url"),
            duration_sec=payload.get("duration"),
            frames=payload.get("frames"),
            fps=payload.get("framespersecond"),
            ratio=payload.get("ratio"),
            resolution=payload.get("resolution"),
            output_format=payload.get("output_format"),
            error_code=error.get("code"),
            error_message=error.get("message"),
            completion_tokens=usage.get("completion_tokens"),
            created_at=payload.get("created_at"),
            updated_at=payload.get("updated_at"),
        )

    def close(self) -> None:
        self._client.close()