World's first open-source, agentic video production system. 12 production pipelines, 100+ tools, 700+ agent skill and production-knowledge files. Turn your AI coding assistant into a full video production studio.
Python agentagentic-aiaiclaudecopilotcursorelevenlabsffmpegfluximage-generationopen-sourceopenaipythonremotionstable-diffusiontext-to-speechtext-to-videovideo-generationvideo-production
feat(video): add direct Volcengine Ark Seedance 2.0 provider
zzzxtntb71f9b1f3ef0
diff --git a/.env.example b/.env.exampleindex d60f8987..e81ac640 100644--- a/.env.example+++ b/.env.example@@ -48,6 +48,13 @@ DASHSCOPE_API_KEY= # Qwen image gen (qwen-image-2.0-pro), TTS (qwen3-tSUNO_API_KEY= # Suno AI music generation (full songs, instrumentals, any genre)# --- Video Generation ---+# Volcengine Ark direct Seedance 2.0 API key body (without the "Bearer " prefix).+# Get one at https://console.volcengine.com/ark/region:cn-beijing/apiKey+ARK_API_KEY=+# Optional overrides; uncomment only when needed.+# ARK_SEEDANCE_MODEL=doubao-seedance-2-0-260128+# ARK_BASE_URL=https://ark.cn-beijing.volces.com/api/v3+# ARK_CNY_PER_USD=7.2HEYGEN_API_KEY= # HeyGen API (VEO, Sora, Runway, Kling, Seedance via single key)RUNWAY_API_KEY= # Runway Gen-4 (direct API, alternative to fal.ai routing)VOLC_ACCESSKEY= # Volcengine Jimeng (即梦 AI) video generation via official API (HMAC-SHA256 V4 signing)diff --git a/README.md b/README.mdindex 6dd89ecd..999e98f8 100644--- a/README.md+++ b/README.md@@ -253,6 +253,7 @@ XAI_API_KEY=your-key # xAI Grok image edits/generation + Grok video geGOOGLE_API_KEY=your-key # Google Imagen images, Google TTS (700+ voices)# More video providers:+ARK_API_KEY=your-key # Volcengine Ark direct — Seedance 2.0 Standard/Fast/MiniHEYGEN_API_KEY=your-key # HeyGen — VEO, Sora, Runway, Kling via single gatewayRUNWAY_API_KEY=your-key # Runway Gen-4 direct```@@ -483,12 +484,13 @@ Each tool declares which Layer 3 skills it relies on. The agent reads Layer 1 to> **Full setup guide with pricing and free tiers:** [`docs/PROVIDERS.md`](docs/PROVIDERS.md)<details>-<summary><strong>Video Generation — 15 providers</strong></summary>+<summary><strong>Video Generation — 16 providers</strong></summary>| Provider | Type | Notes ||----------|------|-------|| **Kling (fal.ai)** | Cloud API | High quality, fast via fal.ai gateway || **Kling Official** | Cloud API | Official direct API with separate `kling_official` provider |+| **Seedance 2.0 (Volcengine Ark)** | Cloud API | Official direct API with separate `seedance_ark` provider || **Runway Gen-4** | Cloud API | Cinematic quality, Gen-3 Alpha Turbo / Gen-4 Turbo / Gen-4 Aleph || **Google Veo 3** | Cloud API | Long-form, cinematic. Via fal.ai or HeyGen. || **Grok Imagine Video** | Cloud API | Strong reference-image video and xAI-native short-form generation |diff --git a/README_zh-CN.md b/README_zh-CN.mdindex b8e3b7f2..9c6d27e9 100644--- a/README_zh-CN.md+++ b/README_zh-CN.md@@ -187,6 +187,7 @@ XAI_API_KEY=your-key # xAI Grok 图像编辑/生成 + Grok 视频生GOOGLE_API_KEY=your-key # Google Imagen 图像、Google TTS(700+ 种声音)# 更多视频提供商:+ARK_API_KEY=your-key # 火山方舟直连 — Seedance 2.0 Standard/Fast/MiniHEYGEN_API_KEY=your-key # HeyGen — 汇集 VEO、Sora、Runway、Kling 的统一网关RUNWAY_API_KEY=your-key # Runway Gen-4 直连```@@ -417,11 +418,12 @@ OpenMontage/> **包含定价与免费额度的完整设置指南:** [`docs/PROVIDERS.md`](docs/PROVIDERS.md)<details>-<summary><strong>视频生成 — 14 家提供商</strong></summary>+<summary><strong>视频生成 — 15 家提供商</strong></summary>| 提供商 | 类型 | 备注 ||----------|------|-------|| **Kling** | 云端 API | 高质量,速度快 |+| **Seedance 2.0(火山方舟)** | 云端 API | 独立的 `seedance_ark` 官方直连接口 || **Runway Gen-4** | 云端 API | 电影级质量,Gen-3 Alpha Turbo / Gen-4 Turbo / Gen-4 Aleph || **Google Veo 3** | 云端 API | 长篇幅,电影级。通过 fal.ai 或 HeyGen 接入。 || **Grok Imagine Video** | 云端 API | 强大的基于参考图的视频和 xAI 原生短视频生成 |diff --git a/docs/PROVIDERS.md b/docs/PROVIDERS.mdindex 7ad51bad..f43d5040 100644--- a/docs/PROVIDERS.md+++ b/docs/PROVIDERS.md@@ -18,11 +18,12 @@ Everything you need to know about every provider in OpenMontage — setup instru| 6 | **~$0.05/image** | OpenAI | GPT Image 2 images + OpenAI TTS || 7 | **~$0.04/image** | Google Imagen | Imagen 4 images (shares the Google API key) || 8 | **pay-as-you-go** | Kling Official | Official direct Kling video, image, TTS, avatar, and lip-sync API, separate from fal.ai Kling |-| 9 | **$12/month** | Runway | Gen-4 video — highest quality AI video |-| 10 | **pay-as-you-go** | HeyGen | Avatar videos, multi-model video gateway |-| 11 | **pay-as-you-go** | Suno | Full song generation with vocals and lyrics |-| 12 | **$0 + GPU** | Local video gen | WAN 2.1, Hunyuan, CogVideo, LTX — free, offline |-| 13 | **$0 + GPU** | Local Diffusion | Stable Diffusion images — free, offline |+| 9 | **pay-as-you-go** | Volcengine Ark | Official direct Seedance 2.0 Standard/Fast/Mini API |+| 10 | **$12/month** | Runway | Gen-4 video — highest quality AI video |+| 11 | **pay-as-you-go** | HeyGen | Avatar videos, multi-model video gateway |+| 12 | **pay-as-you-go** | Suno | Full song generation with vocals and lyrics |+| 13 | **$0 + GPU** | Local video gen | WAN 2.1, Hunyuan, CogVideo, LTX — free, offline |+| 14 | **$0 + GPU** | Local Diffusion | Stable Diffusion images — free, offline |### Environment Variable Summary@@ -55,6 +56,9 @@ FAL_KEY= # FLUX, Recraft, Kling, Veo, MiniMax videoKLING_API_KEY= # Official Kling video, image, TTS, avatar, lip syncKLING_API_BASE_URL= # Optional; default https://api-singapore.klingai.com+# VOLCENGINE ARK DIRECT SEEDANCE 2.0 API+ARK_API_KEY= # API key body only; do not include the "Bearer " prefix+# VIDEOHEYGEN_API_KEY= # HeyGen avatar video gatewayRUNWAY_API_KEY= # Runway Gen-4 video (direct)@@ -151,6 +155,64 @@ The `req_key` for video is `jimeng_ti2v_v30_pro`. Success code is `10000`. Task---+### Volcengine Ark — Direct Seedance 2.0 Video Generation++> **Official direct Seedance API.** Calls Volcengine Ark without routing through fal.ai or Replicate, while keeping those existing provider paths available as independent fallbacks.++**Tool unlocked:** `seedance_ark`++**Env var:** `ARK_API_KEY`++#### Setup++1. Open the [Volcengine Ark API key console](https://console.volcengine.com/ark/region:cn-beijing/apiKey)+2. Enable the Seedance 2.0 model family and confirm that the account has balance or a valid resource package+3. Create a long-lived API key+4. Add the key body to `.env`: `ARK_API_KEY=...`++Do not include the `Bearer ` prefix in the environment value. The tool adds the authorization scheme when it sends a request.++Optional overrides:++```bash+ARK_SEEDANCE_MODEL=doubao-seedance-2-0-260128+ARK_BASE_URL=https://ark.cn-beijing.volces.com/api/v3+ARK_CNY_PER_USD=7.2+```++#### Models and capabilities++| Variant | Default model ID | Output |+|---------|------------------|--------|+| Standard | `doubao-seedance-2-0-260128` | 480p, 720p, 1080p, or 4K |+| Fast | `doubao-seedance-2-0-fast-260128` | 480p or 720p |+| Mini | `doubao-seedance-2-0-mini-260615` | 480p or 720p |++The adapter supports:++- text-to-video, first-frame image-to-video, and multimodal reference-to-video+- local image and audio inputs encoded as validated Data URIs+- remote reference image, video, and audio URLs+- task create, query, cancel, and bounded polling+- synchronized audio, optional last-frame return, web search for text-only requests, and output download+- pre-submit dry-run and token-based cost estimates++Local reference videos are intentionally rejected because the public API does not document video Data URI support. Use a provider-accessible HTTPS URL or an Ark asset reference instead.++#### API and billing notes++The asynchronous API flow is:++`POST /contents/generations/tasks` → `GET /contents/generations/tasks/{id}` → download the successful result URL.++Queued tasks can be cancelled with `DELETE /contents/generations/tasks/{id}`. Task records are retained for a limited period, and successful result URLs are short-lived, so the tool downloads outputs promptly.++Ark bills Seedance 2.0 by completion tokens. Rates vary by model, resolution, and whether the request includes reference video. OpenMontage estimates cost before submission and reconciles against provider-returned usage when available. Check the Ark console for current rates before a paid run; custom endpoint IDs require an explicit custom price so unknown pricing is never treated as free.++Official references: [model list](https://www.volcengine.com/docs/82379/1330310?lang=zh), [create task](https://www.volcengine.com/docs/82379/1520757?lang=zh), [query task](https://www.volcengine.com/docs/82379/1521309?lang=zh).++---+### Alibaba DashScope — Qwen Image + TTS + ASR> **Best for Chinese-language production.** One key unlocks Qwen-Image generation, Qwen-TTS Mandarin narration, and Qwen-ASR with word-level timestamps — the only DashScope path that provides word-level granularity for subtitle alignment.@@ -930,6 +992,7 @@ These tools require only FFmpeg or Python packages — no GPU, no API key.| **ElevenLabs** | `ELEVENLABS_API_KEY` | `elevenlabs_tts`, `music_gen` | Free tier + paid || **fal.ai** | `FAL_KEY` | `flux_image`, `recraft_image`, `kling_video`, `veo_video`, `minimax_video` | Pay-as-you-go || **Kling Official** | `KLING_API_KEY` | `kling_official_video`, `kling_official_image`, `kling_tts`, `kling_avatar`, `kling_lip_sync` | Pay-as-you-go |+| **Volcengine Ark** | `ARK_API_KEY` | `seedance_ark` | Pay-as-you-go || **OpenAI** | `OPENAI_API_KEY` | `openai_tts`, `openai_image` | Paid only || **xAI** | `XAI_API_KEY` | `grok_image`, `grok_video` | Paid only || **Runway** | `RUNWAY_API_KEY` | `runway_video` | Free trial + paid |@@ -949,7 +1012,7 @@ How many providers cover each capability:| Capability | Cloud Providers | Local Providers | Free Options ||-----------|----------------|-----------------|--------------|| **Image Generation** | FLUX, Kling Official, Grok, Google Imagen, GPT Image 2, Recraft | Local Diffusion | Pexels, Pixabay (stock) |-| **Video Generation** | Grok, Kling Official, Kling via fal.ai, Runway, Veo, Gemini Omni, Higgsfield, MiniMax, HeyGen | WAN, Hunyuan, CogVideo, LTX | Pexels, Pixabay (stock) |+| **Video Generation** | Grok, Kling Official, Kling via fal.ai, Seedance via Volcengine Ark, Runway, Veo, Gemini Omni, Higgsfield, MiniMax, HeyGen | WAN, Hunyuan, CogVideo, LTX | Pexels, Pixabay (stock) || **Text-to-Speech** | ElevenLabs, Google TTS, Kling Official, OpenAI | Piper | Piper, Google free tier, ElevenLabs free tier || **Music Generation** | ElevenLabs, Suno, Google Lyria | — | ElevenLabs free tier || **Post-Production** | — | FFmpeg (compose, stitch, trim, mix, enhance, grade) | All free |diff --git a/tests/contracts/test_seedance_ark_video.py b/tests/contracts/test_seedance_ark_video.pynew file mode 100644index 00000000..884211ce--- /dev/null+++ b/tests/contracts/test_seedance_ark_video.py@@ -0,0 +1,875 @@+"""Contract tests for direct Volcengine Ark Seedance 2.0 video generation.++All HTTP calls are mocked. This suite must never create a paid task.+"""++from __future__ import annotations++import base64+import wave++import pytest++from tools.base_tool import BaseTool, ToolRuntime, ToolStatus+from tools.video.seedance_ark import SeedanceArkVideo+++class _FakeResponse:+ def __init__(+ self,+ payload: dict | None = None,+ *,+ content: bytes = b"",+ status_code: int = 200,+ ) -> None:+ self._payload = payload if payload is not None else {}+ self.content = content+ self.status_code = status_code++ def json(self) -> dict:+ return self._payload++ def raise_for_status(self) -> None:+ if self.status_code >= 400:+ raise RuntimeError(f"HTTP {self.status_code}: {self._payload}")+++class TestContract:+ def test_identity_and_capabilities(self):+ assert issubclass(SeedanceArkVideo, BaseTool)+ tool = SeedanceArkVideo()+ assert tool.name == "seedance_ark"+ assert tool.provider == "ark"+ assert tool.capability == "video_generation"+ assert tool.runtime == ToolRuntime.API+ assert tool.supports["text_to_video"] is True+ assert tool.supports["image_to_video"] is True+ assert tool.supports["reference_to_video"] is True+ assert "env:ARK_API_KEY" in tool.dependencies++ def test_status_requires_ark_api_key(self, monkeypatch):+ monkeypatch.delenv("ARK_API_KEY", raising=False)+ assert SeedanceArkVideo().get_status() == ToolStatus.UNAVAILABLE+ monkeypatch.setenv("ARK_API_KEY", "fake-ark-key")+ assert SeedanceArkVideo().get_status() == ToolStatus.AVAILABLE++ def test_official_model_ids(self):+ assert SeedanceArkVideo.MODEL_IDS == {+ "standard": "doubao-seedance-2-0-260128",+ "fast": "doubao-seedance-2-0-fast-260128",+ "mini": "doubao-seedance-2-0-mini-260615",+ }+++class TestTaskActions:+ def test_create_uses_official_endpoint_bearer_auth_and_body(self, monkeypatch):+ monkeypatch.setenv("ARK_API_KEY", "fake-ark-key")+ captured = {}++ def fake_post(url, *, headers, json, timeout):+ captured.update(url=url, headers=headers, json=json, timeout=timeout)+ return _FakeResponse({"id": "cgt-test-123"})++ monkeypatch.setattr("requests.post", fake_post)+ result = SeedanceArkVideo().execute(+ {+ "task_action": "create",+ "prompt": "A paper bird takes flight",+ "model_variant": "standard",+ "duration": 5,+ "aspect_ratio": "16:9",+ "resolution": "720p",+ "generate_audio": True,+ "watermark": False,+ "return_last_frame": True,+ }+ )++ assert result.success is True+ assert result.data["task_id"] == "cgt-test-123"+ assert result.data["status"] == "submitted"+ assert captured["url"] == (+ "https://ark.cn-beijing.volces.com/api/v3/contents/generations/tasks"+ )+ assert captured["headers"]["Authorization"] == "Bearer fake-ark-key"+ assert captured["json"] == {+ "model": "doubao-seedance-2-0-260128",+ "content": [{"type": "text", "text": "A paper bird takes flight"}],+ "duration": 5,+ "ratio": "16:9",+ "resolution": "720p",+ "generate_audio": True,+ "watermark": False,+ "return_last_frame": True,+ }++ def test_query_uses_get_and_returns_task_payload(self, monkeypatch):+ monkeypatch.setenv("ARK_API_KEY", "fake-ark-key")+ captured = {}++ def fake_get(url, *, headers, timeout):+ captured.update(url=url, headers=headers, timeout=timeout)+ return _FakeResponse(+ {+ "id": "cgt-test-123",+ "status": "succeeded",+ "content": {"video_url": "https://example.com/result.mp4"},+ "usage": {"completion_tokens": 250000},+ }+ )++ monkeypatch.setattr("requests.get", fake_get)+ result = SeedanceArkVideo().execute(+ {"task_action": "query", "task_id": "cgt-test-123"}+ )++ assert result.success is True+ assert result.data["task"]["status"] == "succeeded"+ assert captured["url"].endswith(+ "/api/v3/contents/generations/tasks/cgt-test-123"+ )+ assert captured["headers"]["Authorization"] == "Bearer fake-ark-key"++ def test_cancel_uses_delete(self, monkeypatch):+ monkeypatch.setenv("ARK_API_KEY", "fake-ark-key")+ captured = {}++ def fake_delete(url, *, headers, timeout):+ captured.update(url=url, headers=headers, timeout=timeout)+ return _FakeResponse({})++ monkeypatch.setattr("requests.delete", fake_delete)+ result = SeedanceArkVideo().execute(+ {"task_action": "cancel", "task_id": "cgt-test-123"}+ )++ assert result.success is True+ assert result.data == {+ "task_id": "cgt-test-123",+ "status": "cancel_requested",+ }+ assert captured["url"].endswith(+ "/api/v3/contents/generations/tasks/cgt-test-123"+ )++ def test_generate_polls_and_downloads_without_extra_submission(+ self, monkeypatch, tmp_path+ ):+ monkeypatch.setenv("ARK_API_KEY", "fake-ark-key")+ calls = {"post": 0, "task_get": 0, "download_get": 0}++ def fake_post(url, *, headers, json, timeout):+ calls["post"] += 1+ return _FakeResponse({"id": "cgt-test-123"})++ def fake_get(url, *, headers=None, timeout):+ if url.endswith("/cgt-test-123"):+ calls["task_get"] += 1+ return _FakeResponse(+ {+ "id": "cgt-test-123",+ "model": "doubao-seedance-2-0-260128",+ "status": "succeeded",+ "content": {+ "video_url": "https://example.com/result.mp4",+ "last_frame_url": "https://example.com/last.png",+ },+ "duration": 5,+ "resolution": "720p",+ "ratio": "16:9",+ "usage": {"completion_tokens": 250000},+ }+ )+ calls["download_get"] += 1+ return _FakeResponse(content=b"fake-mp4")++ monkeypatch.setattr("requests.post", fake_post)+ monkeypatch.setattr("requests.get", fake_get)+ monkeypatch.setattr("time.sleep", lambda *_: None)+ monkeypatch.setattr(+ "tools.video._shared.probe_output",+ lambda *_: {"duration": 5.0, "width": 1280, "height": 720},+ )++ output = tmp_path / "ark.mp4"+ result = SeedanceArkVideo().execute(+ {+ "prompt": "A paper bird takes flight",+ "poll_interval_seconds": 0,+ "output_path": str(output),+ }+ )++ assert result.success is True+ assert output.read_bytes() == b"fake-mp4"+ assert result.data["task_id"] == "cgt-test-123"+ assert result.data["video_url"] == "https://example.com/result.mp4"+ assert result.data["last_frame_url"] == "https://example.com/last.png"+ assert calls == {"post": 1, "task_get": 1, "download_get": 1}+++class TestInputSafety:+ def test_local_first_frame_is_embedded_without_fal_upload(+ self, monkeypatch, tmp_path+ ):+ from PIL import Image++ monkeypatch.setenv("ARK_API_KEY", "fake-ark-key")+ captured = {}+ image = tmp_path / "anchor.png"+ Image.new("RGB", (640, 640), "white").save(image)++ def fail_fal_upload(*args, **kwargs):+ raise AssertionError("Ark local references must never use FAL")++ def fake_post(url, *, headers, json, timeout):+ captured["payload"] = json+ return _FakeResponse({"id": "cgt-test-123"})++ monkeypatch.setattr("tools.video._shared.upload_image_fal", fail_fal_upload)+ monkeypatch.setattr("requests.post", fake_post)+ result = SeedanceArkVideo().execute(+ {+ "task_action": "create",+ "prompt": "The bird opens its wings",+ "operation": "image_to_video",+ "reference_image_path": str(image),+ }+ )++ assert result.success is True+ media = captured["payload"]["content"][1]+ assert media["type"] == "image_url"+ assert media["role"] == "first_frame"+ prefix, encoded = media["image_url"]["url"].split(",", 1)+ assert prefix == "data:image/png;base64"+ assert base64.b64decode(encoded) == image.read_bytes()++ def test_reference_media_roles_follow_official_contract(self, monkeypatch):+ monkeypatch.setenv("ARK_API_KEY", "fake-ark-key")+ captured = {}++ def fake_post(url, *, headers, json, timeout):+ captured["payload"] = json+ return _FakeResponse({"id": "cgt-test-123"})++ monkeypatch.setattr("requests.post", fake_post)+ result = SeedanceArkVideo().execute(+ {+ "task_action": "create",+ "prompt": "Match the supplied look and rhythm",+ "operation": "reference_to_video",+ "reference_image_urls": ["https://example.com/look.png"],+ "reference_video_urls": ["https://example.com/motion.mp4"],+ "reference_audio_urls": ["https://example.com/voice.mp3"],+ }+ )++ assert result.success is True+ assert captured["payload"]["content"][1:] == [+ {+ "type": "image_url",+ "image_url": {"url": "https://example.com/look.png"},+ "role": "reference_image",+ },+ {+ "type": "video_url",+ "video_url": {"url": "https://example.com/motion.mp4"},+ "role": "reference_video",+ },+ {+ "type": "audio_url",+ "audio_url": {"url": "https://example.com/voice.mp3"},+ "role": "reference_audio",+ },+ ]++ @pytest.mark.parametrize(+ "inputs, message",+ [+ ({"task_action": "create", "prompt": ""}, "prompt"),+ (+ {+ "task_action": "create",+ "prompt": "x",+ "duration": 3,+ },+ "duration",+ ),+ (+ {+ "task_action": "create",+ "prompt": "x",+ "operation": "image_to_video",+ },+ "reference image",+ ),+ (+ {"task_action": "query", "task_id": "../not-valid"},+ "task_id",+ ),+ ],+ )+ def test_invalid_input_never_reaches_network(+ self, inputs, message, monkeypatch+ ):+ monkeypatch.setenv("ARK_API_KEY", "fake-ark-key")++ def fail_network(*args, **kwargs):+ raise AssertionError("invalid input must not call the network")++ monkeypatch.setattr("requests.post", fail_network)+ monkeypatch.setattr("requests.get", fail_network)+ monkeypatch.setattr("requests.delete", fail_network)+ result = SeedanceArkVideo().execute(inputs)+ assert result.success is False+ assert message in result.error.lower()++ def test_errors_redact_api_key(self, monkeypatch):+ api_key = "unit-test-api-key-redaction-marker"+ monkeypatch.setenv("ARK_API_KEY", api_key)++ def failing_post(*args, **kwargs):+ raise RuntimeError(f"request failed using {api_key}")++ monkeypatch.setattr("requests.post", failing_post)+ result = SeedanceArkVideo().execute(+ {"task_action": "create", "prompt": "x"}+ )+ assert result.success is False+ assert api_key not in result.error+ assert "[redacted]" in result.error++ def test_download_errors_redact_signed_url_and_preserve_task_id(+ self, monkeypatch+ ):+ monkeypatch.setenv("ARK_API_KEY", "fake-ark-key")++ def fake_post(*args, **kwargs):+ return _FakeResponse({"id": "cgt-paid-123"})++ def fake_get(url, **kwargs):+ if url.endswith("/cgt-paid-123"):+ return _FakeResponse(+ {+ "id": "cgt-paid-123",+ "status": "succeeded",+ "content": {+ "video_url": (+ "https://cdn.example/video.mp4"+ "?X-Signature=unit-test-signature-marker"+ )+ },+ }+ )+ raise RuntimeError(f"download failed: {url}")++ monkeypatch.setattr("requests.post", fake_post)+ monkeypatch.setattr("requests.get", fake_get)+ result = SeedanceArkVideo().execute({"prompt": "x"})+ assert result.success is False+ assert result.data["task_id"] == "cgt-paid-123"+ assert result.data["recovery_action"] == "query"+ assert "unit-test-signature-marker" not in result.error+ assert "?[redacted]" in result.error++ def test_terminal_failure_redacts_signed_input_url(self, monkeypatch):+ monkeypatch.setenv("ARK_API_KEY", "fake-ark-key")++ def fake_post(*args, **kwargs):+ return _FakeResponse({"id": "cgt-paid-123"})++ def fake_get(*args, **kwargs):+ return _FakeResponse(+ {+ "id": "cgt-paid-123",+ "status": "failed",+ "error": {+ "code": "InputFetchFailed",+ "message": (+ "cannot fetch https://media.example/a.mp4"+ "?X-Signature=unit-test-signature-marker"+ ),+ },+ }+ )++ monkeypatch.setattr("requests.post", fake_post)+ monkeypatch.setattr("requests.get", fake_get)+ result = SeedanceArkVideo().execute({"prompt": "x"})+ assert result.success is False+ assert result.data["task_id"] == "cgt-paid-123"+ assert "unit-test-signature-marker" not in result.error+ assert "?[redacted]" in result.error++ def test_corrupt_or_tiny_local_image_never_reaches_network(+ self, monkeypatch, tmp_path+ ):+ from PIL import Image++ monkeypatch.setenv("ARK_API_KEY", "fake-ark-key")++ def fail_network(*args, **kwargs):+ raise AssertionError("invalid local image must not call network")++ monkeypatch.setattr("requests.post", fail_network)+ corrupt = tmp_path / "corrupt.png"+ corrupt.write_bytes(b"\x89PNG\r\n\x1a\nmock")+ corrupt_result = SeedanceArkVideo().execute(+ {+ "task_action": "create",+ "prompt": "x",+ "operation": "image_to_video",+ "reference_image_path": str(corrupt),+ }+ )+ assert corrupt_result.success is False+ assert "unreadable or corrupt" in corrupt_result.error++ tiny = tmp_path / "tiny.png"+ Image.new("RGB", (1, 1), "white").save(tiny)+ tiny_result = SeedanceArkVideo().execute(+ {+ "task_action": "create",+ "prompt": "x",+ "operation": "image_to_video",+ "reference_image_path": str(tiny),+ }+ )+ assert tiny_result.success is False+ assert "300 to 6000" in tiny_result.error++ def test_corrupt_or_tiny_image_data_uri_never_reaches_network(+ self, monkeypatch+ ):+ from io import BytesIO++ from PIL import Image++ monkeypatch.setenv("ARK_API_KEY", "fake-ark-key")++ def fail_network(*args, **kwargs):+ raise AssertionError("invalid image Data URI must not call network")++ monkeypatch.setattr("requests.post", fail_network)+ corrupt = SeedanceArkVideo().execute(+ {+ "task_action": "create",+ "prompt": "x",+ "operation": "image_to_video",+ "reference_image_url": "data:image/png;base64,NOT-BASE64",+ }+ )+ assert corrupt.success is False+ assert "strict base64" in corrupt.error++ buffer = BytesIO()+ Image.new("RGB", (1, 1), "white").save(buffer, format="PNG")+ tiny_uri = (+ "data:image/png;base64,"+ + base64.b64encode(buffer.getvalue()).decode("ascii")+ )+ tiny = SeedanceArkVideo().execute(+ {+ "task_action": "create",+ "prompt": "x",+ "operation": "image_to_video",+ "reference_image_url": tiny_uri,+ }+ )+ assert tiny.success is False+ assert "300 to 6000" in tiny.error++ def test_rejects_bearer_prefix_before_network(self, monkeypatch):+ monkeypatch.setenv("ARK_API_KEY", "Bearer fake-ark-key")++ def fail_network(*args, **kwargs):+ raise AssertionError("invalid API Key config must not call network")++ monkeypatch.setattr("requests.post", fail_network)+ result = SeedanceArkVideo().execute(+ {"task_action": "create", "prompt": "x"}+ )+ assert result.success is False+ assert "remove the 'Bearer ' prefix" in result.error++ def test_rejects_local_reference_video_before_network(+ self, monkeypatch, tmp_path+ ):+ monkeypatch.setenv("ARK_API_KEY", "fake-ark-key")+ video = tmp_path / "reference.mp4"+ video.write_bytes(b"not-a-real-video")++ def fail_network(*args, **kwargs):+ raise AssertionError("local video must not reach the Ark API")++ monkeypatch.setattr("requests.post", fail_network)+ result = SeedanceArkVideo().execute(+ {+ "task_action": "create",+ "prompt": "match this motion",+ "operation": "reference_to_video",+ "reference_video_path": str(video),+ }+ )+ assert result.success is False+ assert "reference_video_path is not supported by ark" in result.error.lower()++ def test_rejects_fast_1080p_before_network(self, monkeypatch):+ monkeypatch.setenv("ARK_API_KEY", "fake-ark-key")++ def fail_network(*args, **kwargs):+ raise AssertionError("unsupported resolution must not call network")++ monkeypatch.setattr("requests.post", fail_network)+ result = SeedanceArkVideo().execute(+ {+ "task_action": "create",+ "prompt": "x",+ "model_variant": "fast",+ "resolution": "1080p",+ }+ )+ assert result.success is False+ assert "only 480p or 720p" in result.error++ def test_short_local_audio_never_reaches_network(+ self, monkeypatch, tmp_path+ ):+ monkeypatch.setenv("ARK_API_KEY", "fake-ark-key")+ audio = tmp_path / "short.wav"+ with wave.open(str(audio), "wb") as writer:+ writer.setnchannels(1)+ writer.setsampwidth(2)+ writer.setframerate(8000)+ writer.writeframes(b"\0\0" * 8000)++ def fail_network(*args, **kwargs):+ raise AssertionError("invalid local audio must not call network")++ monkeypatch.setattr("requests.post", fail_network)+ result = SeedanceArkVideo().execute(+ {+ "task_action": "create",+ "prompt": "match audio1",+ "operation": "reference_to_video",+ "reference_image_urls": ["https://example.com/look.png"],+ "reference_audio_path": str(audio),+ }+ )+ assert result.success is False+ assert "2 to 15 seconds" in result.error++ def test_invalid_exchange_rate_fails_before_paid_post(self, monkeypatch):+ monkeypatch.setenv("ARK_API_KEY", "fake-ark-key")+ monkeypatch.setenv("ARK_CNY_PER_USD", "not-a-number")++ def fail_network(*args, **kwargs):+ raise AssertionError("local cost config error must precede paid POST")++ monkeypatch.setattr("requests.post", fail_network)+ result = SeedanceArkVideo().execute(+ {"task_action": "create", "prompt": "x"}+ )+ assert result.success is False+ assert result.data == {}++ @pytest.mark.parametrize("exchange_rate", ["nan", "inf", "-inf"])+ def test_non_finite_exchange_rate_never_reaches_paid_post(+ self, monkeypatch, exchange_rate+ ):+ monkeypatch.setenv("ARK_API_KEY", "fake-ark-key")+ monkeypatch.setenv("ARK_CNY_PER_USD", exchange_rate)++ def fail_network(*args, **kwargs):+ raise AssertionError("non-finite exchange rate reached paid POST")++ monkeypatch.setattr("requests.post", fail_network)+ result = SeedanceArkVideo().execute(+ {"task_action": "create", "prompt": "x"}+ )+ assert result.success is False+ assert "finite" in result.error++ @pytest.mark.parametrize("exchange_rate", ["nan", "inf", "-inf"])+ def test_non_finite_exchange_rate_never_returns_query_cost(+ self, monkeypatch, exchange_rate+ ):+ monkeypatch.setenv("ARK_API_KEY", "fake-ark-key")+ monkeypatch.setenv("ARK_CNY_PER_USD", exchange_rate)+ monkeypatch.setattr(+ "requests.get",+ lambda *args, **kwargs: _FakeResponse(+ {+ "id": "task-query-cost",+ "status": "succeeded",+ "model": "doubao-seedance-2-0-260128",+ "usage": {"completion_tokens": 108_000},+ }+ ),+ )+ result = SeedanceArkVideo().execute(+ {"task_action": "query", "task_id": "task-query-cost"}+ )+ assert result.success is False+ assert "finite" in result.error++ @pytest.mark.parametrize("custom_price", ["nan", "inf", "-inf"])+ def test_non_finite_custom_price_never_returns_query_cost(+ self, monkeypatch, custom_price+ ):+ monkeypatch.setenv("ARK_API_KEY", "fake-ark-key")+ monkeypatch.setattr(+ "requests.get",+ lambda *args, **kwargs: _FakeResponse(+ {+ "id": "task-query-custom-cost",+ "status": "succeeded",+ "model": "ep-custom-account-pricing",+ "usage": {"completion_tokens": 108_000},+ }+ ),+ )+ result = SeedanceArkVideo().execute(+ {+ "task_action": "query",+ "task_id": "task-query-custom-cost",+ "custom_price_cny_per_million_tokens": custom_price,+ }+ )+ assert result.success is False+ assert "finite" in result.error++ def test_custom_query_without_price_reports_unknown_not_zero(+ self, monkeypatch+ ):+ monkeypatch.setenv("ARK_API_KEY", "fake-ark-key")+ monkeypatch.setattr(+ "requests.get",+ lambda *args, **kwargs: _FakeResponse(+ {+ "id": "task-query-custom-unknown",+ "status": "succeeded",+ "model": "ep-custom-account-pricing",+ "usage": {"completion_tokens": 100_000},+ }+ ),+ )+ result = SeedanceArkVideo().execute(+ {+ "task_action": "query",+ "task_id": "task-query-custom-unknown",+ }+ )+ assert result.success is True+ assert result.cost_usd is None+ assert (+ result.data["cost_estimate_status"]+ == "unknown_custom_model_or_missing_usage"+ )++ def test_query_retries_transient_server_error(self, monkeypatch):+ monkeypatch.setenv("ARK_API_KEY", "fake-ark-key")+ calls = {"count": 0}++ def fake_get(*args, **kwargs):+ calls["count"] += 1+ if calls["count"] == 1:+ return _FakeResponse(+ {"error": {"code": "InternalError"}},+ status_code=503,+ )+ return _FakeResponse(+ {"id": "cgt-test-123", "status": "running"}+ )++ monkeypatch.setattr("requests.get", fake_get)+ monkeypatch.setattr("time.sleep", lambda *_: None)+ result = SeedanceArkVideo().execute(+ {"task_action": "query", "task_id": "cgt-test-123"}+ )+ assert result.success is True+ assert calls["count"] == 2++ def test_dry_run_is_offline_and_never_submits(self, monkeypatch):+ monkeypatch.setenv("ARK_API_KEY", "fake-ark-key")++ def fail_network(*args, **kwargs):+ raise AssertionError("dry_run must not call the network")++ monkeypatch.setattr("requests.post", fail_network)+ result = SeedanceArkVideo().dry_run(+ {+ "prompt": "A paper bird takes flight",+ "duration": 5,+ "resolution": "720p",+ }+ )+ assert result["would_execute"] is False+ assert result["paid_submission"] is False+ assert result["api_contract"] == {+ "create": (+ "POST https://ark.cn-beijing.volces.com/api/v3/"+ "contents/generations/tasks"+ ),+ "query": (+ "GET https://ark.cn-beijing.volces.com/api/v3/"+ "contents/generations/tasks/{task_id}"+ ),+ "cancel": (+ "DELETE https://ark.cn-beijing.volces.com/api/v3/"+ "contents/generations/tasks/{task_id}"+ ),+ }+ assert "authorization" not in str(result).lower()+ assert "fake-ark-key" not in str(result)+++class TestOfficialCostFormula:+ def test_standard_720p_five_seconds_without_video(self):+ tool = SeedanceArkVideo()+ inputs = {+ "prompt": "x",+ "model_variant": "standard",+ "duration": 5,+ "resolution": "720p",+ "aspect_ratio": "16:9",+ }+ assert tool.estimate_token_usage(inputs) == 108000+ assert tool.estimate_cost_cny(inputs) == pytest.approx(4.968)++ def test_input_video_duration_uses_video_price(self):+ tool = SeedanceArkVideo()+ inputs = {+ "prompt": "x",+ "operation": "reference_to_video",+ "model_variant": "standard",+ "duration": 5,+ "resolution": "720p",+ "aspect_ratio": "16:9",+ "reference_video_urls": ["https://example.com/motion.mp4"],+ "reference_video_durations": [2],+ }+ assert tool.estimate_token_usage(inputs) == 151200+ assert tool.estimate_cost_cny(inputs) == pytest.approx(4.2336)++ def test_missing_video_duration_uses_conservative_fifteen_seconds(self):+ tool = SeedanceArkVideo()+ inputs = {+ "prompt": "x",+ "operation": "reference_to_video",+ "model_variant": "standard",+ "duration": 5,+ "resolution": "720p",+ "aspect_ratio": "16:9",+ "reference_video_urls": ["https://example.com/motion.mp4"],+ }+ assert tool.estimate_token_usage(inputs) == 432000+ assert tool.estimate_cost_cny(inputs) == pytest.approx(12.096)++ def test_custom_endpoint_cost_is_unknown_not_standard_price(self):+ tool = SeedanceArkVideo()+ inputs = {+ "prompt": "x",+ "model": "ep-custom-account-pricing",+ "duration": 5,+ "resolution": "720p",+ "aspect_ratio": "16:9",+ }+ with pytest.raises(ValueError, match="pricing is unknown"):+ tool.estimate_cost_cny(inputs)+ dry = tool.dry_run(inputs)+ assert dry["valid"] is False+ assert "pricing is unknown" in dry["error"]++ def test_custom_endpoint_requires_price_before_paid_post(+ self, monkeypatch+ ):+ monkeypatch.setenv("ARK_API_KEY", "fake-ark-key")++ def fail_network(*args, **kwargs):+ raise AssertionError("unknown custom price must precede paid POST")++ monkeypatch.setattr("requests.post", fail_network)+ result = SeedanceArkVideo().execute(+ {+ "task_action": "create",+ "model": "ep-custom-account-pricing",+ "prompt": "x",+ }+ )+ assert result.success is False+ assert "pricing is unknown" in result.error++ def test_custom_endpoint_accepts_explicit_price(self):+ tool = SeedanceArkVideo()+ cost = tool.estimate_cost_cny(+ {+ "model": "ep-custom-account-pricing",+ "prompt": "x",+ "duration": 5,+ "resolution": "720p",+ "aspect_ratio": "16:9",+ "custom_price_cny_per_million_tokens": 50,+ }+ )+ assert cost == pytest.approx(5.4)++ @pytest.mark.parametrize("custom_price", ["nan", "inf", "-inf"])+ def test_non_finite_custom_price_never_reaches_paid_post(+ self, monkeypatch, custom_price+ ):+ monkeypatch.setenv("ARK_API_KEY", "fake-ark-key")++ def fail_network(*args, **kwargs):+ raise AssertionError("non-finite custom price reached paid POST")++ monkeypatch.setattr("requests.post", fail_network)+ result = SeedanceArkVideo().execute(+ {+ "task_action": "create",+ "model": "ep-custom-account-pricing",+ "custom_price_cny_per_million_tokens": custom_price,+ "prompt": "x",+ }+ )+ assert result.success is False+ assert "finite" in result.error++ def test_valid_audio_data_uri_reaches_mocked_create(+ self, monkeypatch, tmp_path+ ):+ monkeypatch.setenv("ARK_API_KEY", "fake-ark-key")+ audio = tmp_path / "two-seconds.wav"+ with wave.open(str(audio), "wb") as writer:+ writer.setnchannels(1)+ writer.setsampwidth(2)+ writer.setframerate(8_000)+ writer.writeframes(b"\x00\x00" * 16_000)+ audio_uri = (+ "data:audio/wav;base64,"+ + base64.b64encode(audio.read_bytes()).decode("ascii")+ )+ observed = {}++ def fake_post(url, **kwargs):+ observed["payload"] = kwargs["json"]+ return _FakeResponse({"id": "task-audio-data-uri"})++ monkeypatch.setattr("requests.post", fake_post)+ result = SeedanceArkVideo().execute(+ {+ "task_action": "create",+ "prompt": "match this audio",+ "operation": "reference_to_video",+ "reference_image_url": "https://example.com/look.png",+ "reference_audio_url": audio_uri,+ }+ )+ assert result.success is True+ audio_items = [+ item+ for item in observed["payload"]["content"]+ if item["type"] == "audio_url"+ ]+ assert audio_items[0]["audio_url"]["url"] == audio_uridiff --git a/tests/tools/test_video_selector_routing.py b/tests/tools/test_video_selector_routing.pyindex 162e907d..5b61b34f 100644--- a/tests/tools/test_video_selector_routing.py+++ b/tests/tools/test_video_selector_routing.py@@ -23,7 +23,7 @@ from typing import Anyimport pytest-from tools.base_tool import ToolStatus+from tools.base_tool import ToolResult, ToolStatusfrom tools.video.video_selector import VideoSelector@@ -54,6 +54,7 @@ class _StubTool:self._status = statusself._cost = costself._runtime = runtime+ self.last_execute_inputs: dict[str, Any] | None = None# --- BaseTool surface used by the selector -------------------------------def get_status(self) -> ToolStatus:@@ -78,6 +79,10 @@ class _StubTool:def estimate_runtime(self, inputs: dict[str, Any]) -> float:return self._runtime+ def execute(self, inputs: dict[str, Any]) -> ToolResult:+ self.last_execute_inputs = dict(inputs)+ return ToolResult(success=True, data={})+# ProviderScore.weighted_score is a read-only computed property, so we can't# override it per-instance. Instead _ScoreStub exposes the same attribute surface@@ -279,3 +284,40 @@ def test_estimate_cost_zero_when_no_providers():sel = VideoSelector()sel._providers = lambda: [] # type: ignore[assignment]assert sel.estimate_cost({"prompt": "x"}) == 0.0+++def test_ark_local_reference_routes_without_fal_upload(rankings, monkeypatch, tmp_path):+ """An explicit Ark route preserves the local path for Ark's own encoder."""+ ark = _StubTool("seedance_ark", "ark")+ ark.input_schema = {+ "properties": {+ "prompt": {},+ "reference_image_path": {},+ "reference_image_url": {},+ }+ }+ rankings.append(_ScoreStub("seedance_ark", "ark", 0.99))++ def fail_upload(*args, **kwargs):+ raise AssertionError("Ark local references must never be uploaded via FAL")++ monkeypatch.setattr("tools.video._shared.upload_image_fal", fail_upload)+ image_path = tmp_path / "anchor.png"+ image_path.write_bytes(b"not-read-by-selector")++ selector = VideoSelector()+ selector._providers = lambda: [ark] # type: ignore[assignment]+ result = selector.execute({+ "prompt": "motion",+ "operation": "image_to_video",+ "preferred_provider": "ark",+ "allowed_providers": ["ark"],+ "reference_image_path": str(image_path),+ })++ assert result.success is True+ assert ark.last_execute_inputs is not None+ assert ark.last_execute_inputs["reference_image_path"] == str(image_path)+ assert "image_url" not in ark.last_execute_inputs+ assert result.data["selected_tool"] == "seedance_ark"+ assert result.data["selected_provider"] == "ark"diff --git a/tools/video/seedance_ark.py b/tools/video/seedance_ark.pynew file mode 100644index 00000000..f6843fd4--- /dev/null+++ b/tools/video/seedance_ark.py@@ -0,0 +1,1547 @@+"""Direct Volcengine Ark adapter for the Seedance 2.0 model family.++The Ark API is asynchronous: create a task, poll its status, then download the+24-hour result URL immediately. This provider is intentionally independent+from the existing fal.ai and Replicate Seedance adapters.+"""++from __future__ import annotations++import base64+import binascii+import io+import math+import mimetypes+import os+import re+import shutil+import subprocess+import tempfile+import time+from pathlib import Path+from typing import Any+from urllib.parse import urlsplit, urlunsplit++from tools.base_tool import (+ BaseTool,+ Determinism,+ ExecutionMode,+ ResourceProfile,+ RetryPolicy,+ ToolResult,+ ToolRuntime,+ ToolStability,+ ToolStatus,+ ToolTier,+)+++class SeedanceArkVideo(BaseTool):+ """Generate Seedance 2.0 video through Volcengine Ark's official REST API."""++ name = "seedance_ark"+ version = "0.1.0"+ tier = ToolTier.GENERATE+ capability = "video_generation"+ provider = "ark"+ stability = ToolStability.BETA+ execution_mode = ExecutionMode.ASYNC+ determinism = Determinism.STOCHASTIC+ runtime = ToolRuntime.API++ BASE_URL = "https://ark.cn-beijing.volces.com/api/v3"+ MODEL_IDS = {+ "standard": "doubao-seedance-2-0-260128",+ "fast": "doubao-seedance-2-0-fast-260128",+ "mini": "doubao-seedance-2-0-mini-260615",+ }+ TASK_ID_PATTERN = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._:-]{0,255}$")+ TERMINAL_STATUSES = frozenset(+ {"succeeded", "failed", "cancelled", "expired"}+ )+ IMAGE_SUFFIX_TO_MIME = {+ ".jpg": "image/jpeg",+ ".jpeg": "image/jpeg",+ ".png": "image/png",+ ".webp": "image/webp",+ ".bmp": "image/bmp",+ ".tif": "image/tiff",+ ".tiff": "image/tiff",+ ".gif": "image/gif",+ }+ AUDIO_SUFFIX_TO_MIME = {+ ".wav": "audio/wav",+ ".mp3": "audio/mp3",+ }+ MAX_IMAGE_BYTES = 30 * 1024 * 1024+ MAX_AUDIO_BYTES = 15 * 1024 * 1024+ MAX_REQUEST_BYTES = 64 * 1024 * 1024++ # Official 2026-07-26 on-demand prices, CNY per million completion tokens.+ PRICE_CNY_PER_MILLION = {+ "standard": {+ "without_video": {+ "480p": 46.0,+ "720p": 46.0,+ "1080p": 51.0,+ "4k": 26.0,+ },+ "with_video": {+ "480p": 28.0,+ "720p": 28.0,+ "1080p": 31.0,+ "4k": 16.0,+ },+ },+ "fast": {+ "without_video": {"480p": 37.0, "720p": 37.0},+ "with_video": {"480p": 22.0, "720p": 22.0},+ },+ "mini": {+ "without_video": {"480p": 23.0, "720p": 23.0},+ "with_video": {"480p": 14.0, "720p": 14.0},+ },+ }+ OUTPUT_DIMENSIONS = {+ "480p": {+ "16:9": (864, 496),+ "4:3": (752, 560),+ "1:1": (640, 640),+ "3:4": (560, 752),+ "9:16": (496, 864),+ "21:9": (992, 432),+ },+ "720p": {+ "16:9": (1280, 720),+ "4:3": (1112, 834),+ "1:1": (960, 960),+ "3:4": (834, 1112),+ "9:16": (720, 1280),+ "21:9": (1470, 630),+ },+ "1080p": {+ "16:9": (1920, 1080),+ "4:3": (1664, 1248),+ "1:1": (1440, 1440),+ "3:4": (1248, 1664),+ "9:16": (1080, 1920),+ "21:9": (2206, 946),+ },+ "4k": {+ "16:9": (3840, 2160),+ "4:3": (3326, 2494),+ "1:1": (2880, 2880),+ "3:4": (2494, 3326),+ "9:16": (2160, 3840),+ "21:9": (4398, 1886),+ },+ }++ dependencies = ["env:ARK_API_KEY"]+ install_instructions = (+ "Set ARK_API_KEY to the API Key body from Volcengine Ark (without "+ "the 'Bearer ' prefix). Optional: ARK_SEEDANCE_MODEL and ARK_BASE_URL."+ )+ agent_skills = ["seedance-2-0", "ai-video-gen"]++ capabilities = [+ "text_to_video",+ "image_to_video",+ "reference_to_video",+ "task_create",+ "task_query",+ "task_cancel",+ ]+ supports = {+ "text_to_video": True,+ "image_to_video": True,+ "reference_to_video": True,+ "multiple_reference_images": True,+ "reference_image": True,+ "reference_video": True,+ "reference_audio": True,+ "native_audio": True,+ "local_image_data_uri": True,+ "local_audio_data_uri": True,+ "local_video": False,+ "return_last_frame": True,+ "web_search": True,+ "aspect_ratio": True,+ }+ best_for = [+ "direct Volcengine Ark Seedance 2.0 generation without a gateway",+ "multimodal reference video with native synchronized audio",+ "Standard 1080p or 4K output and Fast/Mini lower-cost output",+ ]+ not_good_for = [+ "offline generation",+ "unapproved paid generation",+ "direct local reference-video upload",+ ]+ fallback_tools = ["seedance_video", "seedance_replicate", "jimeng_video"]++ input_schema = {+ "type": "object",+ "properties": {+ "task_action": {+ "type": "string",+ "enum": ["generate", "create", "query", "cancel"],+ "default": "generate",+ },+ "task_id": {+ "type": "string",+ "description": "Required for task_action=query/cancel.",+ },+ "prompt": {"type": "string"},+ "operation": {+ "type": "string",+ "enum": ["text_to_video", "image_to_video", "reference_to_video"],+ "default": "text_to_video",+ },+ "model_variant": {+ "type": "string",+ "enum": ["standard", "fast", "mini"],+ "default": "standard",+ },+ "model": {+ "type": "string",+ "description": (+ "Optional Ark Model ID or Endpoint ID. Overrides "+ "ARK_SEEDANCE_MODEL and model_variant."+ ),+ },+ "custom_price_cny_per_million_tokens": {+ "type": "number",+ "exclusiveMinimum": 0,+ "description": (+ "Required for a custom Endpoint or unknown future model "+ "so budget checks never treat unknown pricing as free."+ ),+ },+ "duration": {+ "description": "Integer seconds 4-15, or -1/'auto'.",+ "default": 5,+ },+ "aspect_ratio": {+ "type": "string",+ "enum": [+ "adaptive",+ "21:9",+ "16:9",+ "4:3",+ "1:1",+ "3:4",+ "9:16",+ ],+ "default": "16:9",+ },+ "resolution": {+ "type": "string",+ "enum": ["480p", "720p", "1080p", "4k"],+ "default": "720p",+ },+ "generate_audio": {"type": "boolean", "default": True},+ "watermark": {"type": "boolean", "default": False},+ "return_last_frame": {"type": "boolean", "default": False},+ "callback_url": {"type": "string"},+ "execution_expires_after": {+ "type": "integer",+ "minimum": 3600,+ "maximum": 259200,+ },+ "priority": {"type": "integer", "minimum": 0, "maximum": 9},+ "safety_identifier": {"type": "string", "maxLength": 64},+ "web_search": {+ "type": "boolean",+ "description": "Officially limited to pure text input.",+ },+ "reference_image_path": {"type": "string"},+ "reference_image_url": {"type": "string"},+ "reference_image_paths": {+ "type": "array",+ "items": {"type": "string"},+ },+ "reference_image_urls": {+ "type": "array",+ "items": {"type": "string"},+ },+ "end_image_path": {"type": "string"},+ "end_image_url": {"type": "string"},+ "reference_video_url": {"type": "string"},+ "reference_video_urls": {+ "type": "array",+ "items": {"type": "string"},+ },+ "reference_video_path": {+ "type": "string",+ "description": "Rejected: Ark does not document video Base64.",+ },+ "reference_video_durations": {+ "type": "array",+ "items": {"type": "number", "minimum": 2, "maximum": 15},+ "description": "Optional durations used for preflight cost estimation.",+ },+ "reference_audio_url": {"type": "string"},+ "reference_audio_urls": {+ "type": "array",+ "items": {"type": "string"},+ },+ "reference_audio_path": {"type": "string"},+ "reference_audio_paths": {+ "type": "array",+ "items": {"type": "string"},+ },+ "reference_audio_durations": {+ "type": "array",+ "items": {"type": "number", "minimum": 2, "maximum": 15},+ "description": (+ "Optional durations for remote audio preflight; local "+ "audio is probed automatically."+ ),+ },+ "poll_interval_seconds": {+ "type": "number",+ "minimum": 0,+ "maximum": 60,+ "default": 3,+ },+ "timeout_seconds": {+ "type": "number",+ "minimum": 1,+ "default": 1200,+ },+ "output_path": {"type": "string"},+ },+ }++ resource_profile = ResourceProfile(+ cpu_cores=1,+ ram_mb=512,+ vram_mb=0,+ disk_mb=2048,+ network_required=True,+ )+ retry_policy = RetryPolicy(+ max_retries=2,+ backoff_seconds=2.0,+ retryable_errors=["rate_limit", "timeout", "server_error"],+ )+ idempotency_key_fields = [+ "prompt",+ "operation",+ "model_variant",+ "model",+ "duration",+ "aspect_ratio",+ "resolution",+ "generate_audio",+ "watermark",+ "reference_image_url",+ "reference_image_path",+ "reference_image_urls",+ "reference_image_paths",+ "reference_video_urls",+ "reference_audio_urls",+ ]+ side_effects = [+ "submits a paid task to the Volcengine Ark API",+ "writes the completed video to output_path",+ ]+ user_visible_verification = [+ "Watch the downloaded clip for visual continuity and synchronized audio",+ "Confirm the local artifact before the 24-hour remote URL expires",+ ]++ def _get_api_key(self) -> str | None:+ return os.environ.get("ARK_API_KEY")++ def _get_base_url(self) -> str:+ base_url = os.environ.get("ARK_BASE_URL", self.BASE_URL).rstrip("/")+ if not base_url.startswith("https://"):+ raise ValueError("ARK_BASE_URL must be an https:// URL")+ return base_url++ def get_status(self) -> ToolStatus:+ api_key = self._get_api_key()+ if not api_key or api_key.lower().startswith("bearer "):+ return ToolStatus.UNAVAILABLE+ return ToolStatus.AVAILABLE++ def estimate_token_usage(self, inputs: dict[str, Any]) -> int:+ """Estimate billable completion tokens using Ark's published formula."""+ duration = self._normalize_duration(inputs.get("duration", 5))+ output_seconds = 15 if duration == -1 else duration+ video_refs = list(inputs.get("reference_video_urls") or [])+ if inputs.get("reference_video_url"):+ video_refs.append(inputs["reference_video_url"])+ video_durations = list(+ inputs.get("reference_video_durations") or []+ )+ # A video reference changes both the token formula and the price tier.+ # When duration metadata is absent, use the official 15-second combined+ # maximum as a conservative preflight upper bound instead of reporting+ # a deceptively cheap output-only estimate.+ if video_refs and len(video_durations) != len(video_refs):+ input_video_seconds = 15.0+ else:+ input_video_seconds = sum(float(value) for value in video_durations)+ resolution = str(inputs.get("resolution", "720p")).lower()+ ratio = str(inputs.get("aspect_ratio", "16:9"))+ if ratio == "adaptive":+ ratio = "16:9"+ width, height = self.OUTPUT_DIMENSIONS[resolution][ratio]+ return round(+ (input_video_seconds + output_seconds)+ * width+ * height+ * 24+ / 1024+ )++ def estimate_cost_cny(self, inputs: dict[str, Any]) -> float:+ model, variant = self._resolve_model(inputs)+ del model+ if variant is None:+ rate = self._get_custom_price(inputs, required=True)+ return round(+ self.estimate_token_usage(inputs) * rate / 1_000_000,+ 4,+ )+ resolution = str(inputs.get("resolution", "720p")).lower()+ with_video = bool(+ inputs.get("reference_video_url")+ or inputs.get("reference_video_urls")+ )+ condition = "with_video" if with_video else "without_video"+ try:+ rate = self.PRICE_CNY_PER_MILLION[variant][condition][resolution]+ except KeyError:+ # A custom Endpoint/Model may have different pricing. Returning+ # zero is safer than presenting a fabricated official estimate.+ return 0.0+ return round(self.estimate_token_usage(inputs) * rate / 1_000_000, 4)++ def estimate_cost(self, inputs: dict[str, Any]) -> float:+ cny_per_usd = self._get_cny_per_usd()+ return round(self.estimate_cost_cny(inputs) / cny_per_usd, 4)++ @staticmethod+ def _get_custom_price(+ inputs: dict[str, Any], *, required: bool+ ) -> float:+ try:+ raw = inputs["custom_price_cny_per_million_tokens"]+ except KeyError as exc:+ if not required:+ return 0.0+ raise ValueError(+ "pricing is unknown for a custom Ark Endpoint/Model; "+ "set custom_price_cny_per_million_tokens before a paid create"+ ) from exc+ try:+ value = float(raw)+ except (TypeError, ValueError) as exc:+ raise ValueError(+ "custom_price_cny_per_million_tokens must be a finite "+ "number greater than 0"+ ) from exc+ if not math.isfinite(value) or value <= 0:+ raise ValueError(+ "custom_price_cny_per_million_tokens must be a finite "+ "number greater than 0"+ )+ return value++ @staticmethod+ def _get_cny_per_usd() -> float:+ try:+ value = float(os.environ.get("ARK_CNY_PER_USD", "7.2"))+ except (TypeError, ValueError) as exc:+ raise ValueError(+ "ARK_CNY_PER_USD must be a finite number greater than 0"+ ) from exc+ if not math.isfinite(value) or value <= 0:+ raise ValueError(+ "ARK_CNY_PER_USD must be a finite number greater than 0"+ )+ return value++ def estimate_runtime(self, inputs: dict[str, Any]) -> float:+ _, variant = self._resolve_model(inputs)+ return 90.0 if variant in {"fast", "mini"} else 180.0++ def dry_run(self, inputs: dict[str, Any]) -> dict[str, Any]:+ """Validate and estimate locally; never submit Ark's paid POST."""+ action = str(inputs.get("task_action", "generate"))+ result: dict[str, Any] = {+ "tool": self.name,+ "task_action": action,+ "status": self.get_status().value,+ "would_execute": False,+ "paid_submission": False,+ "api_contract": {+ "create": f"POST {self.BASE_URL}/contents/generations/tasks",+ "query": (+ f"GET {self.BASE_URL}/contents/generations/tasks/"+ "{task_id}"+ ),+ "cancel": (+ f"DELETE {self.BASE_URL}/contents/generations/tasks/"+ "{task_id}"+ ),+ },+ }+ try:+ base_url = self._get_base_url()+ api_key = self._get_api_key()+ if api_key and api_key.lower().startswith("bearer "):+ raise ValueError(+ "ARK_API_KEY must contain only the API Key body; remove "+ "the 'Bearer ' prefix"+ )+ result["api_contract"] = {+ "create": (+ f"POST {base_url}/contents/generations/tasks"+ ),+ "query": (+ f"GET {base_url}/contents/generations/tasks/"+ "{task_id}"+ ),+ "cancel": (+ f"DELETE {base_url}/contents/generations/tasks/"+ "{task_id}"+ ),+ }+ if action in {"query", "cancel"}:+ self._validate_task_id(inputs.get("task_id"))+ else:+ payload = self._build_payload(inputs)+ result.update(+ {+ "model": payload["model"],+ "operation": inputs.get(+ "operation", "text_to_video"+ ),+ "resolution": payload.get("resolution", "720p"),+ "ratio": payload.get("ratio", "16:9"),+ "duration": payload.get("duration", 5),+ "generate_audio": payload.get(+ "generate_audio", True+ ),+ "media_counts": self._media_counts(payload["content"]),+ "estimated_tokens": self.estimate_token_usage(inputs),+ "estimated_cost_cny": self.estimate_cost_cny(inputs),+ "estimated_cost_usd": self.estimate_cost(inputs),+ "cost_estimate_note": (+ "Official formula estimate; actual usage comes "+ "from usage.completion_tokens and minimum billable "+ "tokens may apply. Missing reference-video duration "+ "is estimated at the official 15-second maximum."+ ),+ "cost_estimate_status": (+ "unknown_custom_model"+ if self._resolve_model(inputs)[1] is None+ else "estimated"+ ),+ }+ )+ result["valid"] = True+ except (TypeError, ValueError, OSError) as exc:+ result["valid"] = False+ result["error"] = self._safe_error(exc)+ return result++ def execute(self, inputs: dict[str, Any]) -> ToolResult:+ """Create, query, cancel, or synchronously finish an Ark task."""+ started = time.time()+ action = str(inputs.get("task_action", "generate"))+ task_id: str | None = None+ estimated_cost_usd = 0.0+ try:+ if action not in {"generate", "create", "query", "cancel"}:+ raise ValueError(+ "task_action must be generate, create, query, or cancel"+ )+ if action in {"query", "cancel"}:+ self._validate_task_id(inputs.get("task_id"))+ else:+ payload = self._build_payload(inputs)+ # Complete all local cost/config parsing before the paid POST.+ # A malformed exchange-rate override must never create an+ # untracked task and then fail while constructing ToolResult.+ estimated_cost_usd = self.estimate_cost(inputs)+ except (TypeError, ValueError, OSError) as exc:+ return ToolResult(success=False, error=self._safe_error(exc))++ api_key = self._get_api_key()+ if not api_key:+ return ToolResult(+ success=False,+ error="ARK_API_KEY not set. " + self.install_instructions,+ )+ if api_key.lower().startswith("bearer "):+ return ToolResult(+ success=False,+ error=(+ "ARK_API_KEY must contain only the API Key body; remove "+ "the 'Bearer ' prefix"+ ),+ )++ try:+ if action == "query":+ task = self._query_task(str(inputs["task_id"]), api_key)+ actual_cost_usd = self._cost_from_task(task, inputs)+ cost_status = (+ "actual_from_usage"+ if actual_cost_usd is not None+ else "unknown_custom_model_or_missing_usage"+ )+ return ToolResult(+ success=True,+ data={+ "task": task,+ "cost_estimate_status": cost_status,+ },+ cost_usd=actual_cost_usd, # type: ignore[arg-type]+ model=task.get("model"),+ )++ if action == "cancel":+ task_id = str(inputs["task_id"])+ self._cancel_task(task_id, api_key)+ return ToolResult(+ success=True,+ data={+ "task_id": task_id,+ "status": "cancel_requested",+ },+ )++ task_id = self._create_task(payload, api_key)+ model = str(payload["model"])+ if action == "create":+ return ToolResult(+ success=True,+ data={+ "task_id": task_id,+ "status": "submitted",+ "provider": self.provider,+ "model": model,+ },+ cost_usd=estimated_cost_usd,+ model=model,+ )++ task = self._poll_task(task_id, api_key, inputs)+ status = str(task.get("status", "")).lower()+ if status != "succeeded":+ detail = self._task_error(task)+ safe_detail = (+ self._safe_error(RuntimeError(detail), api_key)+ if detail+ else ""+ )+ return ToolResult(+ success=False,+ data={"task_id": task_id, "status": status},+ error=(+ f"Ark Seedance task {status or 'failed'}"+ + (f": {safe_detail}" if safe_detail else "")+ ),+ duration_seconds=round(time.time() - started, 2),+ model=str(task.get("model") or model),+ )++ content = task.get("content") or {}+ video_url = content.get("video_url")+ if not video_url:+ raise RuntimeError(+ "Ark task succeeded without content.video_url"+ )+ output_path = Path(+ inputs.get("output_path", "seedance_ark_output.mp4")+ )+ self._download_video(str(video_url), output_path)++ from tools.video._shared import probe_output++ probed = probe_output(output_path)+ cost_usd = self._cost_from_task(task, inputs)+ return ToolResult(+ success=True,+ data={+ "provider": self.provider,+ "task_id": task_id,+ "status": status,+ "model": task.get("model") or model,+ "prompt": inputs.get("prompt"),+ "operation": inputs.get(+ "operation", "text_to_video"+ ),+ "video_url": video_url,+ "last_frame_url": content.get("last_frame_url"),+ "output": str(output_path),+ "output_path": str(output_path),+ "format": "mp4",+ "resolution": task.get(+ "resolution", payload.get("resolution")+ ),+ "aspect_ratio": task.get(+ "ratio", payload.get("ratio")+ ),+ "duration": task.get(+ "duration", payload.get("duration")+ ),+ "generate_audio": task.get("generate_audio"),+ "usage": task.get("usage") or {},+ "estimated_cost_cny": self._cost_from_task_cny(+ task, inputs+ ),+ **probed,+ },+ artifacts=[str(output_path)],+ cost_usd=cost_usd,+ duration_seconds=round(time.time() - started, 2),+ model=str(task.get("model") or model),+ )+ except Exception as exc:+ error_data: dict[str, Any] = {}+ if task_id:+ error_data = {+ "task_id": task_id,+ "status": "submitted_result_unknown",+ "recovery_action": "query",+ }+ elif action in {"query", "cancel"} and inputs.get("task_id"):+ error_data = {"task_id": str(inputs["task_id"])}+ return ToolResult(+ success=False,+ data=error_data,+ error=(+ "Ark Seedance request failed: "+ f"{self._safe_error(exc, api_key)}"+ ),+ duration_seconds=round(time.time() - started, 2),+ )++ def _build_payload(self, inputs: dict[str, Any]) -> dict[str, Any]:+ operation = str(inputs.get("operation", "text_to_video"))+ if operation not in {+ "text_to_video",+ "image_to_video",+ "reference_to_video",+ }:+ raise ValueError(+ "operation must be text_to_video, image_to_video, or "+ "reference_to_video"+ )++ model, variant = self._resolve_model(inputs)+ resolution = str(inputs.get("resolution", "720p")).lower()+ if resolution not in self.OUTPUT_DIMENSIONS:+ raise ValueError(+ "resolution must be 480p, 720p, 1080p, or 4k"+ )+ if variant in {"fast", "mini"} and resolution not in {+ "480p",+ "720p",+ }:+ raise ValueError(+ f"{variant} supports only 480p or 720p resolution"+ )++ ratio = str(inputs.get("aspect_ratio", "16:9"))+ valid_ratios = {+ "adaptive",+ "21:9",+ "16:9",+ "4:3",+ "1:1",+ "3:4",+ "9:16",+ }+ if ratio not in valid_ratios:+ raise ValueError(+ "aspect_ratio must be adaptive, 21:9, 16:9, 4:3, "+ "1:1, 3:4, or 9:16"+ )++ duration = self._normalize_duration(inputs.get("duration", 5))+ prompt = str(inputs.get("prompt") or "").strip()+ content: list[dict[str, Any]] = []+ if prompt:+ content.append({"type": "text", "text": prompt})++ if inputs.get("reference_video_path"):+ raise ValueError(+ "reference_video_path is not supported by Ark; upload the "+ "video to a public/signed HTTPS URL or Ark asset first"+ )++ if operation == "text_to_video":+ if not prompt:+ raise ValueError("prompt is required for text_to_video")+ if self._has_any_media(inputs):+ raise ValueError(+ "text_to_video does not accept reference media; use "+ "image_to_video or reference_to_video"+ )+ elif operation == "image_to_video":+ first_refs = self._single_image_refs(inputs)+ if len(first_refs) != 1:+ raise ValueError(+ "image_to_video requires exactly one reference image"+ )+ content.append(+ self._image_content(first_refs[0], role="first_frame")+ )+ end_refs = [+ value+ for value in (+ inputs.get("end_image_url"),+ inputs.get("end_image_path"),+ )+ if value+ ]+ if len(end_refs) > 1:+ raise ValueError(+ "provide only one of end_image_url/end_image_path"+ )+ if end_refs:+ content.append(+ self._image_content(end_refs[0], role="last_frame")+ )+ else:+ image_refs = list(inputs.get("reference_image_urls") or [])+ image_refs.extend(inputs.get("reference_image_paths") or [])+ if inputs.get("reference_image_url"):+ image_refs.append(inputs["reference_image_url"])+ if inputs.get("reference_image_path"):+ image_refs.append(inputs["reference_image_path"])+ if len(image_refs) > 9:+ raise ValueError(+ "reference_to_video accepts at most 9 reference images"+ )++ video_refs = list(inputs.get("reference_video_urls") or [])+ if inputs.get("reference_video_url"):+ video_refs.append(inputs["reference_video_url"])+ if len(video_refs) > 3:+ raise ValueError(+ "reference_to_video accepts at most 3 reference videos"+ )+ self._validate_remote_refs(video_refs, "reference video")+ video_durations = list(+ inputs.get("reference_video_durations") or []+ )+ if video_durations:+ if len(video_durations) != len(video_refs):+ raise ValueError(+ "reference_video_durations must match the number of "+ "reference videos"+ )+ if any(+ float(value) < 2 or float(value) > 15+ for value in video_durations+ ):+ raise ValueError(+ "each reference video duration must be 2 to 15 seconds"+ )+ if sum(float(value) for value in video_durations) > 15:+ raise ValueError(+ "all reference videos together must be at most "+ "15 seconds"+ )++ audio_refs = list(inputs.get("reference_audio_urls") or [])+ audio_refs.extend(inputs.get("reference_audio_paths") or [])+ if inputs.get("reference_audio_url"):+ audio_refs.append(inputs["reference_audio_url"])+ if inputs.get("reference_audio_path"):+ audio_refs.append(inputs["reference_audio_path"])+ if len(audio_refs) > 3:+ raise ValueError(+ "reference_to_video accepts at most 3 reference audio "+ "clips"+ )+ audio_durations = list(+ inputs.get("reference_audio_durations") or []+ )+ if audio_durations:+ if len(audio_durations) != len(audio_refs):+ raise ValueError(+ "reference_audio_durations must match the number of "+ "reference audio clips"+ )+ if any(+ float(value) < 2 or float(value) > 15+ for value in audio_durations+ ):+ raise ValueError(+ "each reference audio duration must be 2 to 15 seconds"+ )+ if sum(float(value) for value in audio_durations) > 15:+ raise ValueError(+ "all reference audio clips together must be at most "+ "15 seconds"+ )+ local_audio_durations = [+ duration+ for ref in audio_refs+ if (+ duration := self._local_or_data_audio_duration(str(ref))+ )+ is not None+ ]+ if sum(local_audio_durations) > 15:+ raise ValueError(+ "all local reference audio clips together must be at "+ "most 15 seconds"+ )+ if audio_refs and not (image_refs or video_refs):+ raise ValueError(+ "reference audio requires at least one reference image "+ "or video"+ )+ if not (image_refs or video_refs):+ raise ValueError(+ "reference_to_video requires at least one image or video"+ )++ content.extend(+ self._image_content(ref, role="reference_image")+ for ref in image_refs+ )+ content.extend(+ {+ "type": "video_url",+ "video_url": {"url": str(ref)},+ "role": "reference_video",+ }+ for ref in video_refs+ )+ content.extend(+ self._audio_content(ref, role="reference_audio")+ for ref in audio_refs+ )++ if inputs.get("web_search") and len(content) != 1:+ raise ValueError(+ "web_search is supported only for pure text input"+ )++ payload: dict[str, Any] = {+ "model": model,+ "content": content,+ "duration": duration,+ "ratio": ratio,+ "resolution": resolution,+ "generate_audio": bool(inputs.get("generate_audio", True)),+ "watermark": bool(inputs.get("watermark", False)),+ "return_last_frame": bool(+ inputs.get("return_last_frame", False)+ ),+ }+ optional = (+ "callback_url",+ "execution_expires_after",+ "priority",+ "safety_identifier",+ )+ for key in optional:+ if inputs.get(key) is not None:+ payload[key] = inputs[key]+ if inputs.get("web_search"):+ payload["tools"] = [{"type": "web_search"}]++ self._validate_optional_parameters(payload)+ self._validate_request_size(payload)+ return payload++ def _resolve_model(+ self, inputs: dict[str, Any]+ ) -> tuple[str, str | None]:+ variant = str(inputs.get("model_variant", "standard")).lower()+ if variant not in self.MODEL_IDS:+ raise ValueError("model_variant must be standard, fast, or mini")+ model = str(+ inputs.get("model")+ or os.environ.get("ARK_SEEDANCE_MODEL")+ or self.MODEL_IDS[variant]+ )+ if not model or any(char.isspace() for char in model):+ raise ValueError("model must be a non-empty Ark Model/Endpoint ID")+ for known_variant, known_model in self.MODEL_IDS.items():+ if model == known_model:+ return model, known_variant+ # Endpoint IDs and future model IDs can have account-specific pricing.+ # Keep the caller's requested model, but never pretend its price is the+ # public price of model_variant.+ return model, None++ @staticmethod+ def _normalize_duration(value: Any) -> int:+ if value == "auto":+ return -1+ if isinstance(value, bool):+ raise ValueError("duration must be an integer from 4 to 15 or -1")+ try:+ duration = int(value)+ except (TypeError, ValueError) as exc:+ raise ValueError(+ "duration must be an integer from 4 to 15 or -1"+ ) from exc+ if str(value).strip() not in {str(duration), "auto"}:+ raise ValueError(+ "duration must be an integer from 4 to 15 or -1"+ )+ if duration != -1 and not 4 <= duration <= 15:+ raise ValueError("duration must be between 4 and 15 or -1")+ return duration++ @staticmethod+ def _single_image_refs(inputs: dict[str, Any]) -> list[Any]:+ refs = [+ inputs.get("reference_image_url") or inputs.get("image_url"),+ inputs.get("reference_image_path") or inputs.get("image_path"),+ ]+ return [ref for ref in refs if ref]++ @staticmethod+ def _has_any_media(inputs: dict[str, Any]) -> bool:+ keys = (+ "reference_image_url",+ "reference_image_path",+ "reference_image_urls",+ "reference_image_paths",+ "reference_video_url",+ "reference_video_path",+ "reference_video_urls",+ "reference_audio_url",+ "reference_audio_path",+ "reference_audio_urls",+ "reference_audio_paths",+ "image_url",+ "image_path",+ "end_image_url",+ "end_image_path",+ )+ return any(inputs.get(key) for key in keys)++ def _image_content(self, ref: Any, *, role: str) -> dict[str, Any]:+ url = self._media_url(+ ref,+ suffix_to_mime=self.IMAGE_SUFFIX_TO_MIME,+ max_bytes=self.MAX_IMAGE_BYTES,+ label="image",+ )+ return {+ "type": "image_url",+ "image_url": {"url": url},+ "role": role,+ }++ def _audio_content(self, ref: Any, *, role: str) -> dict[str, Any]:+ url = self._media_url(+ ref,+ suffix_to_mime=self.AUDIO_SUFFIX_TO_MIME,+ max_bytes=self.MAX_AUDIO_BYTES,+ label="audio",+ )+ return {+ "type": "audio_url",+ "audio_url": {"url": url},+ "role": role,+ }++ def _media_url(+ self,+ ref: Any,+ *,+ suffix_to_mime: dict[str, str],+ max_bytes: int,+ label: str,+ ) -> str:+ value = str(ref)+ if value.startswith("data:"):+ return self._validate_data_uri(+ value,+ suffix_to_mime=suffix_to_mime,+ max_bytes=max_bytes,+ label=label,+ )+ if self._is_remote_or_asset(value):+ return value+ path = Path(value).expanduser()+ if not path.is_file():+ raise ValueError(+ f"{label} reference must be a public URL, asset:// ID, "+ f"or existing local file: {value}"+ )+ size = path.stat().st_size+ if size >= max_bytes:+ raise ValueError(+ f"local {label} must be smaller than "+ f"{max_bytes // (1024 * 1024)} MB"+ )+ suffix = path.suffix.lower()+ mime = suffix_to_mime.get(suffix)+ if not mime:+ guessed, _ = mimetypes.guess_type(path.name)+ mime = guessed if guessed in suffix_to_mime.values() else None+ if not mime:+ formats = ", ".join(sorted(suffix_to_mime))+ raise ValueError(+ f"unsupported local {label} format; expected one of {formats}"+ )+ if label == "image":+ self._validate_local_image(path)+ elif label == "audio":+ self._probe_local_audio_duration(path)+ encoded = base64.b64encode(path.read_bytes()).decode("ascii")+ return f"data:{mime};base64,{encoded}"++ def _validate_local_image(self, path: Path) -> None:+ self._validate_image_bytes(path.read_bytes(), str(path))++ @staticmethod+ def _validate_image_bytes(data: bytes, source: str) -> None:+ try:+ from PIL import Image++ with Image.open(io.BytesIO(data)) as image:+ width, height = image.size+ image.verify()+ except Exception as exc:+ raise ValueError(+ f"image is unreadable or corrupt: {source}"+ ) from exc+ if not (300 <= width <= 6000 and 300 <= height <= 6000):+ raise ValueError(+ "local image width and height must each be 300 to 6000 pixels"+ )+ ratio = width / height+ if not 0.4 <= ratio <= 2.5:+ raise ValueError(+ "local image width/height ratio must be between 0.4 and 2.5"+ )++ def _validate_data_uri(+ self,+ value: str,+ *,+ suffix_to_mime: dict[str, str],+ max_bytes: int,+ label: str,+ ) -> str:+ mime, decoded = self._decode_data_uri(+ value,+ suffix_to_mime=suffix_to_mime,+ max_bytes=max_bytes,+ label=label,+ )+ if label == "image":+ self._validate_image_bytes(decoded, "Data URI")+ elif label == "audio":+ self._probe_audio_bytes(decoded, mime)+ return value++ @staticmethod+ def _decode_data_uri(+ value: str,+ *,+ suffix_to_mime: dict[str, str],+ max_bytes: int,+ label: str,+ ) -> tuple[str, bytes]:+ match = re.fullmatch(+ r"data:([a-z]+/[a-z0-9.+-]+);base64,([A-Za-z0-9+/=]+)",+ value,+ flags=re.IGNORECASE,+ )+ if not match:+ raise ValueError(+ f"{label} Data URI must use a supported MIME type and "+ "strict base64 encoding"+ )+ mime = match.group(1).lower()+ if mime not in set(suffix_to_mime.values()):+ raise ValueError(f"unsupported {label} Data URI MIME type: {mime}")+ try:+ decoded = base64.b64decode(match.group(2), validate=True)+ except (ValueError, binascii.Error) as exc:+ raise ValueError(f"invalid base64 in {label} Data URI") from exc+ if len(decoded) >= max_bytes:+ raise ValueError(+ f"decoded {label} Data URI must be smaller than "+ f"{max_bytes // (1024 * 1024)} MB"+ )+ return mime, decoded++ def _local_or_data_audio_duration(self, value: str) -> float | None:+ if value.startswith("data:"):+ mime, decoded = self._decode_data_uri(+ value,+ suffix_to_mime=self.AUDIO_SUFFIX_TO_MIME,+ max_bytes=self.MAX_AUDIO_BYTES,+ label="audio",+ )+ return self._probe_audio_bytes(decoded, mime)+ if self._is_remote_or_asset(value):+ return None+ return self._probe_local_audio_duration(Path(value).expanduser())++ def _probe_audio_bytes(self, decoded: bytes, mime: str) -> float:+ suffix = ".wav" if mime == "audio/wav" else ".mp3"+ with tempfile.NamedTemporaryFile(suffix=suffix) as temp:+ temp.write(decoded)+ temp.flush()+ return self._probe_local_audio_duration(Path(temp.name))++ @staticmethod+ def _probe_local_audio_duration(path: Path) -> float:+ if not path.is_file():+ raise ValueError(f"local audio file does not exist: {path}")+ ffprobe = shutil.which("ffprobe")+ if not ffprobe:+ raise ValueError(+ "ffprobe is required to validate local reference audio"+ )+ try:+ proc = subprocess.run(+ [+ ffprobe,+ "-v",+ "error",+ "-show_entries",+ "format=duration",+ "-of",+ "default=noprint_wrappers=1:nokey=1",+ str(path),+ ],+ capture_output=True,+ text=True,+ timeout=10,+ check=False,+ )+ duration = float(proc.stdout.strip()) if proc.returncode == 0 else 0+ except (OSError, ValueError, subprocess.SubprocessError) as exc:+ raise ValueError(+ f"failed to probe local reference audio: {path}"+ ) from exc+ if not 2 <= duration <= 15:+ raise ValueError(+ "each local reference audio clip must be 2 to 15 seconds"+ )+ return duration++ @staticmethod+ def _is_remote_or_asset(value: str) -> bool:+ return value.startswith(("https://", "http://", "asset://"))++ def _validate_remote_refs(+ self, refs: list[Any], label: str+ ) -> None:+ for ref in refs:+ value = str(ref)+ if not value.startswith(("https://", "http://", "asset://")):+ raise ValueError(+ f"{label} must be a public/signed URL or asset:// ID; "+ "Ark does not document video Base64 or local paths"+ )++ def _validate_optional_parameters(+ self, payload: dict[str, Any]+ ) -> None:+ callback = payload.get("callback_url")+ if callback is not None and not str(callback).startswith(+ ("https://", "http://")+ ):+ raise ValueError("callback_url must be an http(s) URL")+ expires = payload.get("execution_expires_after")+ if expires is not None and not 3600 <= int(expires) <= 259200:+ raise ValueError(+ "execution_expires_after must be between 3600 and 259200"+ )+ priority = payload.get("priority")+ if priority is not None and not 0 <= int(priority) <= 9:+ raise ValueError("priority must be between 0 and 9")+ safety = payload.get("safety_identifier")+ if safety is not None and len(str(safety)) > 64:+ raise ValueError("safety_identifier must be at most 64 characters")++ def _validate_request_size(self, payload: dict[str, Any]) -> None:+ # Base64 dominates request size; summing encoded media is a conservative+ # lower-cost check that avoids building a second complete JSON string.+ encoded_bytes = 0+ for item in payload["content"]:+ media = (+ item.get("image_url")+ or item.get("audio_url")+ or item.get("video_url")+ or {}+ )+ url = str(media.get("url", ""))+ if url.startswith("data:"):+ encoded_bytes += len(url.encode("ascii"))+ if encoded_bytes >= self.MAX_REQUEST_BYTES:+ raise ValueError("Ark request body must be smaller than 64 MB")++ @staticmethod+ def _media_counts(content: list[dict[str, Any]]) -> dict[str, int]:+ return {+ kind: sum(1 for item in content if item.get("type") == kind)+ for kind in ("text", "image_url", "video_url", "audio_url")+ }++ def _headers(self, api_key: str) -> dict[str, str]:+ return {+ "Authorization": f"Bearer {api_key}",+ "Content-Type": "application/json",+ }++ def _create_task(+ self, payload: dict[str, Any], api_key: str+ ) -> str:+ import requests++ response = requests.post(+ f"{self._get_base_url()}/contents/generations/tasks",+ headers=self._headers(api_key),+ json=payload,+ timeout=30,+ )+ self._raise_for_status(response)+ data = response.json()+ task_id = data.get("id")+ self._validate_task_id(task_id)+ return str(task_id)++ def _query_task(self, task_id: str, api_key: str) -> dict[str, Any]:+ import requests++ url = f"{self._get_base_url()}/contents/generations/tasks/{task_id}"+ response = None+ for attempt in range(self.retry_policy.max_retries + 1):+ try:+ response = requests.get(+ url,+ headers=self._headers(api_key),+ timeout=30,+ )+ retryable_status = (+ response.status_code == 429+ or response.status_code >= 500+ )+ if (+ retryable_status+ and attempt < self.retry_policy.max_retries+ ):+ time.sleep(+ self.retry_policy.backoff_seconds * (2**attempt)+ )+ continue+ self._raise_for_status(response)+ break+ except requests.RequestException:+ if attempt >= self.retry_policy.max_retries:+ raise+ time.sleep(self.retry_policy.backoff_seconds * (2**attempt))+ if response is None:+ raise RuntimeError("Ark query returned no response")+ data = response.json()+ if not isinstance(data, dict):+ raise RuntimeError("Ark query returned a non-object response")+ return data++ def _cancel_task(self, task_id: str, api_key: str) -> None:+ import requests++ response = requests.delete(+ f"{self._get_base_url()}/contents/generations/tasks/{task_id}",+ headers=self._headers(api_key),+ timeout=30,+ )+ # The official DELETE success body is undefined and may be empty.+ self._raise_for_status(response)++ def _poll_task(+ self,+ task_id: str,+ api_key: str,+ inputs: dict[str, Any],+ ) -> dict[str, Any]:+ interval = float(inputs.get("poll_interval_seconds", 3))+ timeout = float(inputs.get("timeout_seconds", 1200))+ if not 0 <= interval <= 60:+ raise ValueError("poll_interval_seconds must be between 0 and 60")+ if timeout <= 0:+ raise ValueError("timeout_seconds must be greater than 0")+ deadline = time.monotonic() + timeout+ while True:+ task = self._query_task(task_id, api_key)+ status = str(task.get("status", "")).lower()+ if status in self.TERMINAL_STATUSES:+ return task+ if status not in {"queued", "running"}:+ raise RuntimeError(+ f"Ark returned unknown task status: {status or '<empty>'}"+ )+ if time.monotonic() >= deadline:+ raise TimeoutError(+ f"Ark task {task_id} did not finish within {timeout}s"+ )+ time.sleep(interval)++ @staticmethod+ def _download_video(video_url: str, output_path: Path) -> None:+ import requests++ response = requests.get(video_url, timeout=120)+ response.raise_for_status()+ output_path.parent.mkdir(parents=True, exist_ok=True)+ partial = output_path.with_name(output_path.name + ".part")+ partial.write_bytes(response.content)+ partial.replace(output_path)++ @staticmethod+ def _validate_task_id(task_id: Any) -> None:+ value = str(task_id or "")+ if not SeedanceArkVideo.TASK_ID_PATTERN.fullmatch(value):+ raise ValueError("task_id is missing or invalid")++ @staticmethod+ def _raise_for_status(response: Any) -> None:+ try:+ response.raise_for_status()+ except Exception as exc:+ detail = ""+ try:+ payload = response.json()+ error = payload.get("error") if isinstance(payload, dict) else None+ if isinstance(error, dict):+ detail = ": ".join(+ str(error.get(key))+ for key in ("code", "message")+ if error.get(key)+ )+ except Exception:+ pass+ raise RuntimeError(+ f"{exc}" + (f"; {detail}" if detail else "")+ ) from exc++ @staticmethod+ def _task_error(task: dict[str, Any]) -> str:+ error = task.get("error")+ if isinstance(error, dict):+ return ": ".join(+ str(error.get(key))+ for key in ("code", "message")+ if error.get(key)+ )+ return str(error or "")++ def _cost_from_task_cny(+ self, task: dict[str, Any], inputs: dict[str, Any]+ ) -> float | None:+ usage = task.get("usage") or {}+ tokens = usage.get("completion_tokens")+ if (+ not isinstance(tokens, (int, float))+ or not math.isfinite(float(tokens))+ or float(tokens) < 0+ ):+ return None+ model_inputs = dict(inputs)+ if task.get("model"):+ model_inputs["model"] = task["model"]+ _, variant = self._resolve_model(model_inputs)+ resolution = str(+ task.get("resolution")+ or inputs.get("resolution", "720p")+ ).lower()+ condition = (+ "with_video"+ if inputs.get("input_includes_video")+ or inputs.get("reference_video_url")+ or inputs.get("reference_video_urls")+ else "without_video"+ )+ if variant is None:+ if "custom_price_cny_per_million_tokens" not in inputs:+ return None+ rate = self._get_custom_price(inputs, required=False)+ else:+ try:+ rate = self.PRICE_CNY_PER_MILLION[variant][condition][+ resolution+ ]+ except KeyError:+ return None+ return round(float(tokens) * rate / 1_000_000, 4)++ def _cost_from_task(+ self, task: dict[str, Any], inputs: dict[str, Any]+ ) -> float | None:+ cost_cny = self._cost_from_task_cny(task, inputs)+ if cost_cny is None:+ return None+ cny_per_usd = self._get_cny_per_usd()+ return round(cost_cny / cny_per_usd, 4)++ def _safe_error(+ self, exc: Exception, api_key: str | None = None+ ) -> str:+ message = str(exc)+ secrets = {+ value+ for value in (api_key, self._get_api_key())+ if value+ }+ for secret in secrets:+ message = message.replace(secret, "[redacted]")+ message = re.sub(+ r"data:(?:image|audio)/[^;\s]+;base64,[A-Za-z0-9+/=]+",+ "[redacted data URI]",+ message,+ flags=re.IGNORECASE,+ )++ def redact_url(match: re.Match[str]) -> str:+ raw = match.group(0)+ trailing = ""+ while raw and raw[-1] in ".,;:)]}":+ trailing = raw[-1] + trailing+ raw = raw[:-1]+ try:+ parsed = urlsplit(raw)+ host = parsed.hostname or ""+ if parsed.port:+ host = f"{host}:{parsed.port}"+ safe = urlunsplit(+ (+ parsed.scheme,+ host,+ parsed.path,+ "[redacted]" if parsed.query else "",+ "",+ )+ )+ return safe + trailing+ except ValueError:+ return "[redacted URL]"++ message = re.sub(+ r"https?://[^\s'\"<>]+",+ redact_url,+ message,+ flags=re.IGNORECASE,+ )+ message = re.sub(+ r"(?i)authorization\s*[:=]\s*bearer\s+\S+",+ "Authorization: Bearer [redacted]",+ message,+ )+ return message