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: add Tencent Hunyuan cloud video provider via TokenHub API
clarkh287c77fa6414
diff --git a/.env.example b/.env.exampleindex d60f8987..70266e18 100644--- a/.env.example+++ b/.env.example@@ -51,7 +51,10 @@ SUNO_API_KEY= # Suno AI music generation (full songs, instrumentaHEYGEN_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)-VOLC_SECRETKEY= # Secret Access Key paired with VOLC_ACCESSKEY. Get both at https://console.volcengine.com/iam/keymanage+VOLC_SECRETKEY= # Secret Access Key paired with VOLC_ACCESSKEY. Get both at https://console.volcengine.com/iam/keymanage+TENCENT_TOKENHUB_API_KEY= # Tencent Hunyuan (腾讯混元) video generation via TokenHub API (Bearer token)+ # Get it at https://console.cloud.tencent.com/tokenhub+# TENCENT_TOKENHUB_MODEL= # Optional: override default TokenHub model (hy-video-1.5 / yt-video-2.0)VIDEO_GEN_LOCAL_ENABLED= # Set to "true" for local video gen (needs GPU + diffusers)VIDEO_GEN_LOCAL_MODEL= # Local model: wan2.1-1.3b, wan2.1-14b, hunyuan-1.5, ltx2-local, cogvideo-5bMODAL_LTX2_ENDPOINT_URL= # Modal self-hosted LTX-2 endpoint (optional)diff --git a/docs/PROVIDERS.md b/docs/PROVIDERS.mdindex 7ad51bad..a9b86874 100644--- a/docs/PROVIDERS.md+++ b/docs/PROVIDERS.md@@ -19,10 +19,11 @@ Everything you need to know about every provider in OpenMontage — setup instru| 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 |+| 10 | **pay-as-you-go** | Hunyuan cloud video | Chinese-friendly T2V + I2V |+| 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@@ -60,6 +61,9 @@ HEYGEN_API_KEY= # HeyGen avatar video gatewayRUNWAY_API_KEY= # Runway Gen-4 video (direct)SUNO_API_KEY= # Suno music generation+# TENCLOUD HUNYUAN VIDEO+TENCENT_TOKENHUB_API_KEY= # Tencent Hunyuan cloud video via TokenHub API+# LOCAL (no keys needed — just GPU + install)VIDEO_GEN_LOCAL_ENABLED= # Set to "true" for local video genVIDEO_GEN_LOCAL_MODEL= # wan2.1-1.3b, wan2.1-14b, hunyuan-1.5, ltx2-local, cogvideo-5b@@ -343,6 +347,80 @@ Doubao Speech 2.0 is billed by character package or usage in Volcengine. OpenMon---+### Tencent Hunyuan Cloud — Video Generation++> **Tencent Hunyuan (腾讯混元) cloud video generation via TokenHub API.** Generates+> videos from text or images using Tencent's Hunyuan models through the Tencent+> TokenHub API — an OpenAI-compatible gateway (tokenhub.tencentmaas.com) with+> simple Bearer-token authentication. No TC3-HMAC-SHA256 signing required.++**Tools unlocked:** `hunyuan_cloud_video`+**Env vars:** `TENCENT_TOKENHUB_API_KEY` (required), `TENCENT_TOKENHUB_MODEL` (optional, overrides the default model)++#### Setup++1. Go to the [Tencent Cloud TokenHub console](https://console.cloud.tencent.com/tokenhub).+2. Create an application or navigate to the **API Key** section.+3. Generate an API key and copy its value.+4. Add to `.env`:+ ```bash+ TENCENT_TOKENHUB_API_KEY=your-tokenhub-api-key+ # TENCENT_TOKENHUB_MODEL=hy-video-1.5 # optional model override+ ```++#### What It's Best For++- **Chinese-friendly prompt understanding** — Hunyuan models natively understand Chinese prompts better than most Western APIs+- **Simple auth** — Bearer token, no complex signing (just an HTTP Authorization header)+- **Direct Tencent Cloud quota** — uses your own Tencent Cloud credits, not a third-party gateway mark-up+- **Both T2V and I2V** — one API key unlocks text-to-video and image-to-video++#### API Notes++TokenHub uses a **submit-then-poll** pattern:++```text+# Submit a generation task+POST https://tokenhub.tencentmaas.com/v1/api/video/submit+Authorization: Bearer ${TENCENT_TOKENHUB_API_KEY}++# Poll for results+POST https://tokenhub.tencentmaas.com/v1/api/video/query+Authorization: Bearer ${TENCENT_TOKENHUB_API_KEY}+```++| Model | Type | Pricing |+|-------|------|---------|+| `hy-video-1.5` | Text-to-video | 1.5 credits (~$0.25) |+| `yt-video-2.0` | Image-to-video | 2–5 credits (~$0.33–0.83) |++Resolution options: **720p** (default) or **1080p**.++A watermark (`logo_add`) is added by default. Set `logo_add: 0` to disable it (requires console approval from Tencent).++**Schema constraints:**+- **Prompt:** max 200 UTF-8 characters+- **Image:** max 10MB, 50–5000 px per side, aspect ratio 1:4 to 4:1+- **Formats:** jpg, png, jpeg, webp, bmp, tiff++#### Fallback Tools++If `hunyuan_cloud_video` returns an error, the agent may retry with: `jimeng_video`, `kling_official_video`, `minimax_video`++#### Pricing++Tencent TokenHub uses a credit-based pricing system (1 credit = 1.2 RMB ≈ $0.167 USD):++| Model | Resolution | Credits | Estimated USD |+|-------|-----------|---------|---------------|+| HY-Video-1.5 | any | 1.5 | ~$0.25 |+| YT-Video-2.0 | 480p | 2 | ~$0.33 |+| YT-Video-2.0 | 720p / 1080p | 5 | ~$0.83 |++> **Free tier:** Tencent occasionally offers new-user credits for TokenHub. Check the [TokenHub console](https://console.cloud.tencent.com/tokenhub) for current promotions.++---+### Azure AI Speech — Speech-to-Text> **Cloud transcription.** Azure AI Speech Fast Transcription turns local audio into text with word-level timestamps, speaker diarization, and multi-language identification — no GPU required. Optional: the local faster-whisper `transcriber` remains the default offline STT path. When `AZURE_SPEECH_KEY` is set, the agent prefers `azure_stt` for cloud transcription.@@ -936,6 +1014,7 @@ These tools require only FFmpeg or Python packages — no GPU, no API key.| **Higgsfield** | `HIGGSFIELD_API_KEY` + `HIGGSFIELD_API_SECRET` | `higgsfield_video` | Subscription ($15-84/mo) || **HeyGen** | `HEYGEN_API_KEY` | `heygen_video` | Pay-as-you-go || **Suno** | `SUNO_API_KEY` | `suno_music` | Pay-as-you-go |+| **Tencent Hunyuan** | `TENCENT_TOKENHUB_API_KEY` | `hunyuan_cloud_video` | Pay-as-you-go (~$0.25–0.83/gen) || **Local GPU** | `VIDEO_GEN_LOCAL_ENABLED` | `wan_video`, `hunyuan_video`, `cogvideo_video`, `ltx_video_local` | Free (GPU required) || **Local Diffusion** | — (install only) | `local_diffusion` | Free (GPU required) || **Modal** | `MODAL_LTX2_ENDPOINT_URL` | `ltx_video_modal` | Self-hosted cloud |@@ -949,7 +1028,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, Runway, Veo, Gemini Omni, Higgsfield, MiniMax, HeyGen, Tencent Hunyuan | 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_hunyuan_cloud_video.py b/tests/contracts/test_hunyuan_cloud_video.pynew file mode 100644index 00000000..b445d5dd--- /dev/null+++ b/tests/contracts/test_hunyuan_cloud_video.py@@ -0,0 +1,820 @@+"""Contract tests for the Tencent Hunyuan cloud video provider tool (TokenHub API).++These tests verify that the tool satisfies the BaseTool contract without+requiring real Tencent Cloud credentials or making any API calls.++Run: pytest tests/contracts/test_hunyuan_cloud_video.py -v+"""++from __future__ import annotations++import json+import sys+import types+from pathlib import Path++import pytest++from tools.base_tool import (+ BaseTool,+ ExecutionMode,+ ToolRuntime,+ ToolStability,+ ToolStatus,+ ToolTier,+)+from tools.video.hunyuan_cloud_video import HunyuanCloudVideo+++# ------------------------------------------------------------------+# Fake HTTP infrastructure (used by execute-path tests)+# ------------------------------------------------------------------++class FakeResponse:+ def __init__(self, json_data=None, content=b"", ok=True, status_code=200, headers=None, text=""):+ self._json = json_data+ self.content = content+ self.ok = ok+ self.status_code = status_code+ self.headers = headers or {}+ self.text = text or (json.dumps(json_data) if json_data is not None else "")++ def json(self):+ return self._json++ def raise_for_status(self):+ if not self.ok:+ raise RuntimeError(f"HTTP {self.status_code}")+++def _install_fake_requests(monkeypatch, post_responses, get_responses):+ """Inject a fake requests module; returns the recorded calls."""+ calls = {"post": [], "get": []}+ fake = types.ModuleType("requests")++ def fake_post(url, headers=None, json=None, data=None, timeout=None, params=None):+ calls["post"].append({"url": url, "headers": headers, "json": json, "data": data})+ return post_responses.pop(0)++ def fake_get(url, headers=None, timeout=None, params=None):+ calls["get"].append({"url": url, "headers": headers, "params": params})+ return get_responses.pop(0)++ fake.post = fake_post+ fake.get = fake_get+ monkeypatch.setitem(sys.modules, "requests", fake)+ return calls+++# ------------------------------------------------------------------+# Fixtures+# ------------------------------------------------------------------++def hunyuan_env(monkeypatch):+ """Set fake TokenHub API credentials."""+ monkeypatch.setenv("TENCENT_TOKENHUB_API_KEY", "thub-fake-test-key")+++def no_hunyuan_env(monkeypatch):+ """Ensure no TokenHub credentials are set."""+ monkeypatch.delenv("TENCENT_TOKENHUB_API_KEY", raising=False)+++# ------------------------------------------------------------------+# Contract compliance+# ------------------------------------------------------------------++class TestContract:++ def test_inherits_base_tool(self):+ assert issubclass(HunyuanCloudVideo, BaseTool)++ def test_has_required_identity(self):+ tool = HunyuanCloudVideo()+ assert tool.name == "hunyuan_cloud_video"+ assert tool.version == "0.1.0"+ assert tool.provider == "hunyuan_cloud"+ assert tool.capability == "video_generation"+ assert tool.tier == ToolTier.GENERATE+ assert tool.stability == ToolStability.EXPERIMENTAL+ assert tool.runtime == ToolRuntime.API++ def test_execution_mode_is_async(self):+ assert HunyuanCloudVideo().execution_mode == ExecutionMode.ASYNC++ def test_has_input_schema(self):+ schema = HunyuanCloudVideo().input_schema+ assert schema.get("type") == "object"+ props = schema.get("properties", {})+ required = schema.get("required", [])+ assert required == ["prompt"]+ for field in required:+ assert field in props++ def test_has_capabilities(self):+ tool = HunyuanCloudVideo()+ assert "text_to_video" in tool.capabilities+ assert "image_to_video" in tool.capabilities++ def test_has_agent_skills(self):+ assert "ai-video-gen" in HunyuanCloudVideo().agent_skills++ def test_has_fallbacks(self):+ tool = HunyuanCloudVideo()+ assert "jimeng_video" in tool.fallback_tools+ assert "kling_official_video" in tool.fallback_tools+ assert "minimax_video" in tool.fallback_tools++ def test_has_install_instructions(self):+ tool = HunyuanCloudVideo()+ assert "TENCENT_TOKENHUB_API_KEY" in tool.install_instructions++ def test_get_info_returns_dict(self):+ info = HunyuanCloudVideo().get_info()+ assert isinstance(info, dict)+ assert info["name"] == "hunyuan_cloud_video"+ assert info["provider"] == "hunyuan_cloud"+ assert info["runtime"] == "api"+ assert info["capability"] == "video_generation"++ def test_status_unavailable_without_keys(self, no_hunyuan_env):+ assert HunyuanCloudVideo().get_status() == ToolStatus.UNAVAILABLE++ def test_status_available_with_keys(self, hunyuan_env):+ assert HunyuanCloudVideo().get_status() == ToolStatus.AVAILABLE++ def test_has_resource_profile(self):+ rp = HunyuanCloudVideo().resource_profile+ assert rp.network_required is True+ assert rp.vram_mb == 0++ def test_has_retry_policy(self):+ assert HunyuanCloudVideo().retry_policy.max_retries >= 0++ def test_has_side_effects(self):+ side = HunyuanCloudVideo().side_effects+ assert len(side) > 0+ assert any("API" in s for s in side) or any("TokenHub" in s for s in side)++ def test_has_user_visible_verification(self):+ assert len(HunyuanCloudVideo().user_visible_verification) > 0++ def test_estimate_cost_returns_float(self):+ cost = HunyuanCloudVideo().estimate_cost({"prompt": "x"})+ assert isinstance(cost, float)+ assert cost > 0.0++ def test_dry_run_returns_dict(self):+ result = HunyuanCloudVideo().dry_run({"prompt": "test"})+ assert isinstance(result, dict)+ assert result["tool"] == "hunyuan_cloud_video"+++# ------------------------------------------------------------------+# Supports flags+# ------------------------------------------------------------------++class TestSupports:++ def test_text_to_video_supported(self):+ assert HunyuanCloudVideo().supports["text_to_video"] is True++ def test_image_to_video_supported(self):+ assert HunyuanCloudVideo().supports["image_to_video"] is True++ def test_native_audio_not_supported(self):+ assert HunyuanCloudVideo().supports["native_audio"] is False++ def test_seed_not_supported(self):+ assert HunyuanCloudVideo().supports["seed"] is False+++# ------------------------------------------------------------------+# Idempotency keys+# ------------------------------------------------------------------++class TestIdempotencyKeys:++ def test_includes_all_output_affecting_fields(self):+ fields = HunyuanCloudVideo().idempotency_key_fields+ for field in ("prompt", "operation", "model", "image_url", "resolution"):+ assert field in fields, f"missing idempotency field: {field}"++ def test_excludes_execution_only_fields(self):+ fields = HunyuanCloudVideo().idempotency_key_fields+ for field in ("output_path", "poll_interval_seconds", "timeout_seconds"):+ assert field not in fields++ def test_differs_on_operation(self):+ tool = HunyuanCloudVideo()+ base = {"prompt": "x"}+ assert tool.idempotency_key(base) != tool.idempotency_key(+ {**base, "operation": "image_to_video"}+ )++ def test_differs_on_model(self):+ tool = HunyuanCloudVideo()+ base = {"prompt": "x"}+ assert tool.idempotency_key(base) != tool.idempotency_key(+ {**base, "model": "yt-video-2.0"}+ )++ def test_differs_on_image_url(self):+ tool = HunyuanCloudVideo()+ base = {"prompt": "x", "operation": "image_to_video"}+ assert tool.idempotency_key(base) != tool.idempotency_key(+ {**base, "image_url": "https://example.com/img.png"}+ )++ def test_ignores_execution_params(self):+ tool = HunyuanCloudVideo()+ base = {"prompt": "x"}+ assert tool.idempotency_key(base) == tool.idempotency_key(+ {**base, "output_path": "/tmp/out.mp4", "timeout_seconds": 999}+ )+++# ------------------------------------------------------------------+# Tool-specific behavior+# ------------------------------------------------------------------++class TestToolSpecific:++ def test_default_operation_is_text_to_video(self):+ tool = HunyuanCloudVideo()+ assert tool.input_schema["properties"]["operation"]["default"] == "text_to_video"++ def test_default_resolution_is_720p(self):+ tool = HunyuanCloudVideo()+ assert tool.input_schema["properties"]["resolution"]["default"] == "720p"++ def test_default_logo_add_is_1(self):+ tool = HunyuanCloudVideo()+ assert tool.input_schema["properties"]["logo_add"]["default"] == 1++ def test_default_poll_interval_is_5(self):+ tool = HunyuanCloudVideo()+ assert tool.input_schema["properties"]["poll_interval_seconds"]["default"] == 5.0++ def test_default_timeout_is_600(self):+ tool = HunyuanCloudVideo()+ assert tool.input_schema["properties"]["timeout_seconds"]["default"] == 600++ # -- _resolve_model --++ def test_resolve_model_defaults_t2v(self):+ model = HunyuanCloudVideo._resolve_model({"prompt": "test"})+ assert model == "hy-video-1.5"++ def test_resolve_model_defaults_i2v(self):+ model = HunyuanCloudVideo._resolve_model({+ "prompt": "test", "operation": "image_to_video",+ })+ assert model == "yt-video-2.0"++ def test_resolve_model_explicit_input(self):+ model = HunyuanCloudVideo._resolve_model({+ "prompt": "test", "model": "yt-video-2.0",+ })+ assert model == "yt-video-2.0"++ def test_resolve_model_from_env(self, monkeypatch):+ monkeypatch.setenv("TENCENT_TOKENHUB_MODEL", "hy-video-1.5")+ model = HunyuanCloudVideo._resolve_model({+ "prompt": "test", "operation": "image_to_video",+ })+ assert model == "hy-video-1.5"++ def test_resolve_model_input_overrides_env(self, monkeypatch):+ monkeypatch.setenv("TENCENT_TOKENHUB_MODEL", "hy-video-1.5")+ model = HunyuanCloudVideo._resolve_model({+ "prompt": "test", "model": "yt-video-2.0",+ })+ assert model == "yt-video-2.0"++ # -- _build_payload --++ def test_build_payload_t2v_minimal(self):+ """Minimal T2V payload — only prompt is required by TokenHub."""+ tool = HunyuanCloudVideo()+ payload = tool._build_payload({"prompt": "一只猫"})+ assert payload["prompt"] == "一只猫"+ # resolution and logo_add are optional in TokenHub; only included when+ # explicitly passed in inputs+ assert "resolution" not in payload+ assert "logo_add" not in payload++ def test_build_payload_t2v_with_resolution_and_logo(self):+ tool = HunyuanCloudVideo()+ payload = tool._build_payload({+ "prompt": "test", "resolution": "720p", "logo_add": 0,+ })+ assert payload["prompt"] == "test"+ assert payload["resolution"] == "720p"+ assert payload["logo_add"] == 0++ def test_build_payload_t2v_custom_logo_add(self):+ tool = HunyuanCloudVideo()+ payload = tool._build_payload({"prompt": "test", "logo_add": 0})+ assert payload["logo_add"] == 0++ def test_build_payload_i2v_includes_image_url(self):+ tool = HunyuanCloudVideo()+ payload = tool._build_payload({+ "prompt": "motion",+ "operation": "image_to_video",+ "image_url": "https://example.com/frame.png",+ })+ assert payload["image_url"] == "https://example.com/frame.png"++ def test_build_payload_t2v_omits_image(self):+ tool = HunyuanCloudVideo()+ payload = tool._build_payload({"prompt": "a cat", "operation": "text_to_video"})+ assert "image_url" not in payload+ assert "image" not in payload++ def test_build_payload_i2v_base64_from_path(self, tmp_path):+ """image_path should be base64-encoded into the image field."""+ img = tmp_path / "frame.jpg"+ img.write_bytes(b"\xff\xd8\xff\xe0test-jpeg-data")+ tool = HunyuanCloudVideo()+ payload = tool._build_payload({+ "prompt": "test",+ "operation": "image_to_video",+ "image_path": str(img),+ })+ assert payload["image"].startswith("/9j/")++ def test_encode_image_returns_base64(self, tmp_path):+ img = tmp_path / "ref.jpg"+ img.write_bytes(b"\xff\xd8\xff\xe0\x00\x10JFIF")+ encoded = HunyuanCloudVideo._encode_image(str(img))+ assert isinstance(encoded, str)+ assert encoded.startswith("/9j/")++ def test_encode_image_raises_on_missing(self):+ with pytest.raises(FileNotFoundError):+ HunyuanCloudVideo._encode_image("/nonexistent/file.jpg")++ # -- Error paths --++ def test_no_keys_returns_error(self, no_hunyuan_env):+ result = HunyuanCloudVideo().execute({"prompt": "test"})+ assert result.success is False+ assert "TENCENT_TOKENHUB_API_KEY" in result.error++ def test_i2v_without_image_fails(self, hunyuan_env):+ result = HunyuanCloudVideo().execute(+ {"prompt": "test", "operation": "image_to_video"}+ )+ assert result.success is False+ assert "image_url" in result.error or "image_path" in result.error++ def test_i2v_both_url_and_path_fails(self, hunyuan_env, tmp_path):+ img = tmp_path / "ref.jpg"+ img.write_bytes(b"fake-jpeg")+ result = HunyuanCloudVideo().execute({+ "prompt": "test",+ "operation": "image_to_video",+ "image_url": "https://example.com/img.jpg",+ "image_path": str(img),+ })+ assert result.success is False+ assert "not both" in result.error.lower()++ def test_safe_error_redacts_keys(self, monkeypatch):+ monkeypatch.setenv("TENCENT_TOKENHUB_API_KEY", "thub-secret-key")+ redacted = HunyuanCloudVideo._safe_error(+ Exception("failed with thub-secret-key in message")+ )+ assert "thub-secret-key" not in redacted+ assert "[redacted]" in redacted++ def test_safe_error_no_empty_string_bug(self, no_hunyuan_env):+ msg = HunyuanCloudVideo._safe_error(Exception("abc"))+ assert msg == "abc"+++# ------------------------------------------------------------------+# TokenHub auth headers+# ------------------------------------------------------------------++class TestAuthHeaders:++ def test_auth_headers_includes_bearer(self):+ headers = HunyuanCloudVideo._auth_headers("test-api-key")+ assert headers["Authorization"] == "Bearer test-api-key"+ assert headers["Content-Type"] == "application/json"+++# ------------------------------------------------------------------+# Error handling helpers+# ------------------------------------------------------------------++class TestErrorHelpers:++ def test_json_or_raise_returns_dict(self):+ class FakeResp:+ status_code = 200+ def json(self):+ return {"id": "task-123", "status": "queued"}+ result = HunyuanCloudVideo._json_or_raise(FakeResp())+ assert result == {"id": "task-123", "status": "queued"}++ def test_json_or_raise_raises_on_non_json(self):+ class FakeResp:+ status_code = 500+ def json(self):+ raise ValueError("not JSON")+ with pytest.raises(RuntimeError, match="Non-JSON"):+ HunyuanCloudVideo._json_or_raise(FakeResp())++ def test_check_response_passes_on_success(self):+ HunyuanCloudVideo._check_response(+ {"id": "task-123", "status": "completed"}+ )++ def test_check_response_passes_without_error_field(self):+ HunyuanCloudVideo._check_response(+ {"id": "task-456", "status": "running", "progress": 50}+ )++ def test_check_response_raises_on_api_error(self):+ with pytest.raises(RuntimeError, match="Prompt too long"):+ HunyuanCloudVideo._check_response({+ "error": {"code": "invalid_parameter", "message": "Prompt too long"},+ })++ def test_check_response_raises_on_auth_failure(self):+ with pytest.raises(RuntimeError, match="Invalid API key"):+ HunyuanCloudVideo._check_response({+ "error": {+ "type": "authentication_error",+ "message": "Invalid API key",+ },+ })+++# ------------------------------------------------------------------+# Execute with mocked HTTP+# ------------------------------------------------------------------++class TestExecuteWithMocks:++ def test_text_to_video_success(self, hunyuan_env, tmp_path, monkeypatch):+ """Full T2V flow: submit -> poll -> download -> write output."""+ task_id = "143-test-task-12345"+ calls = _install_fake_requests(+ monkeypatch,+ post_responses=[+ # Submit response+ FakeResponse({+ "id": task_id,+ "request_id": "req-sub-001",+ "object": "video",+ "created_at": 1700000000,+ "status": "queued",+ }),+ # Poll response (completed)+ FakeResponse({+ "request_id": "req-poll-001",+ "object": "video",+ "created_at": 1700000000,+ "completed_at": 1700000120,+ "status": "completed",+ "progress": 100,+ "data": {"url": "https://example.com/output.mp4"},+ }),+ ],+ get_responses=[+ # Download response+ FakeResponse(content=b"fake-hunyuan-mp4-data"),+ ],+ )++ output_path = tmp_path / "hunyuan_out.mp4"+ result = HunyuanCloudVideo().execute({+ "prompt": "一只猫在草原上奔跑",+ "output_path": str(output_path),+ })++ assert result.success, result.error+ assert output_path.read_bytes() == b"fake-hunyuan-mp4-data"+ assert result.data["provider"] == "hunyuan_cloud"+ assert result.data["route"] == "tokenhub"+ assert result.data["model"] == "hy-video-1.5"+ assert result.data["task_id"] == task_id+ assert result.data["operation"] == "text_to_video"+ assert result.cost_usd == pytest.approx(0.25)+ assert len(result.artifacts) == 1+ assert result.artifacts[0] == str(output_path)++ # Verify submit was called to the correct TokenHub endpoint+ submit_call = calls["post"][0]+ assert "tokenhub.tencentmaas.com" in submit_call["url"]+ assert submit_call["url"].endswith("/v1/api/video/submit")+ assert submit_call["headers"]["Authorization"] == "Bearer thub-fake-test-key"+ assert submit_call["json"]["model"] == "hy-video-1.5"+ assert submit_call["json"]["prompt"] == "一只猫在草原上奔跑"++ # Verify poll was called+ poll_call = calls["post"][1]+ assert poll_call["url"].endswith("/v1/api/video/query")+ assert poll_call["json"]["model"] == "hy-video-1.5"+ assert poll_call["json"]["id"] == task_id++ # Verify download was called+ assert len(calls["get"]) == 1+ assert calls["get"][0]["url"] == "https://example.com/output.mp4"++ def test_image_to_video_with_url_success(self, hunyuan_env, tmp_path, monkeypatch):+ """Full I2V flow with an image URL."""+ task_id = "i2v-task-999"+ _install_fake_requests(+ monkeypatch,+ post_responses=[+ FakeResponse({+ "id": task_id, "request_id": "req-sub", "object": "video",+ "created_at": 1700000000, "status": "queued",+ }),+ FakeResponse({+ "request_id": "req-poll", "object": "video",+ "created_at": 1700000000, "completed_at": 1700000120,+ "status": "completed", "progress": 100,+ "data": {"url": "https://example.com/i2v_out.mp4"},+ }),+ ],+ get_responses=[+ FakeResponse(content=b"fake-i2v-video"),+ ],+ )++ output_path = tmp_path / "i2v_out.mp4"+ result = HunyuanCloudVideo().execute({+ "prompt": "让画面动起来",+ "operation": "image_to_video",+ "image_url": "https://example.com/frame.jpg",+ "output_path": str(output_path),+ })++ assert result.success, result.error+ assert output_path.read_bytes() == b"fake-i2v-video"+ assert result.data["operation"] == "image_to_video"+ assert result.data["model"] == "yt-video-2.0"+ assert result.data["task_id"] == task_id++ def test_i2v_with_local_image_path(self, hunyuan_env, tmp_path, monkeypatch):+ """Full I2V flow with a local image path -> base64 encoding."""+ img = tmp_path / "frame.jpg"+ img.write_bytes(b"\xff\xd8\xff\xe0test-jpeg-image-data")++ task_id = "i2v-local-task"+ _install_fake_requests(+ monkeypatch,+ post_responses=[+ FakeResponse({+ "id": task_id, "request_id": "req-sub", "object": "video",+ "created_at": 1700000000, "status": "queued",+ }),+ FakeResponse({+ "request_id": "req-poll", "object": "video",+ "created_at": 1700000000, "completed_at": 1700000120,+ "status": "completed", "progress": 100,+ "data": {"url": "https://example.com/i2v_local.mp4"},+ }),+ ],+ get_responses=[+ FakeResponse(content=b"fake-i2v-local-video"),+ ],+ )++ output_path = tmp_path / "i2v_local.mp4"+ result = HunyuanCloudVideo().execute({+ "prompt": "animate this frame",+ "operation": "image_to_video",+ "image_path": str(img),+ "output_path": str(output_path),+ })++ assert result.success, result.error+ assert output_path.read_bytes() == b"fake-i2v-local-video"++ def test_explicit_model_takes_priority(self, hunyuan_env, tmp_path, monkeypatch):+ """When model is explicitly set, it should be used for both T2V and I2V."""+ task_id = "model-override-1"+ calls = _install_fake_requests(+ monkeypatch,+ post_responses=[+ FakeResponse({+ "id": task_id, "request_id": "req-sub", "object": "video",+ "created_at": 1700000000, "status": "queued",+ }),+ FakeResponse({+ "request_id": "req-poll", "object": "video",+ "status": "completed", "progress": 100,+ "data": {"url": "https://example.com/out.mp4"},+ }),+ ],+ get_responses=[FakeResponse(content=b"data")],+ )++ result = HunyuanCloudVideo().execute({+ "prompt": "test",+ "operation": "image_to_video",+ "model": "hy-video-1.5",+ "image_url": "https://example.com/frame.jpg",+ "poll_interval_seconds": 0.1,+ "output_path": str(tmp_path / "out.mp4"),+ })++ assert result.success, result.error+ assert result.data["model"] == "hy-video-1.5"+ assert calls["post"][0]["json"]["model"] == "hy-video-1.5"++ def test_polling_retries_until_success(self, hunyuan_env, tmp_path, monkeypatch):+ """Polling should retry when status is queued/running, then succeed."""+ task_id = "poll-retry-task"+ _install_fake_requests(+ monkeypatch,+ post_responses=[+ FakeResponse({+ "id": task_id, "request_id": "req-sub", "object": "video",+ "created_at": 1700000000, "status": "queued",+ }),+ FakeResponse({+ "request_id": "r1", "object": "video",+ "status": "queued", "progress": 0,+ }),+ FakeResponse({+ "request_id": "r2", "object": "video",+ "status": "running", "progress": 45,+ }),+ FakeResponse({+ "request_id": "r3", "object": "video",+ "status": "completed", "progress": 100,+ "data": {"url": "https://example.com/final.mp4"},+ }),+ ],+ get_responses=[+ FakeResponse(content=b"final-video-data"),+ ],+ )++ result = HunyuanCloudVideo().execute({+ "prompt": "test polling",+ "poll_interval_seconds": 0.1,+ "output_path": str(tmp_path / "polled.mp4"),+ })++ assert result.success, result.error+ assert result.data["task_id"] == task_id++ def test_polling_fails_on_task_failed(self, hunyuan_env, tmp_path, monkeypatch):+ """When the API returns status=failed, execute should return error."""+ task_id = "failed-task"+ _install_fake_requests(+ monkeypatch,+ post_responses=[+ FakeResponse({+ "id": task_id, "request_id": "req-sub", "object": "video",+ "created_at": 1700000000, "status": "queued",+ }),+ FakeResponse({+ "request_id": "req-fail", "object": "video",+ "status": "failed",+ "error": {"code": "internal_error", "message": "Service unavailable"},+ }),+ ],+ get_responses=[],+ )++ result = HunyuanCloudVideo().execute({+ "prompt": "this will fail",+ "poll_interval_seconds": 0.1,+ "output_path": str(tmp_path / "failed.mp4"),+ })++ assert result.success is False+ assert "failed" in result.error.lower()+ assert "Service unavailable" in result.error++ def test_submit_error_returns_failure(self, hunyuan_env, tmp_path, monkeypatch):+ """API-level error on submit should be returned as ToolResult error."""+ _install_fake_requests(+ monkeypatch,+ post_responses=[+ FakeResponse({+ "error": {"code": "invalid_parameter", "message": "Prompt exceeds limit"},+ }),+ ],+ get_responses=[],+ )++ result = HunyuanCloudVideo().execute({+ "prompt": "test",+ "output_path": str(tmp_path / "err.mp4"),+ })++ assert result.success is False+ assert "Prompt exceeds limit" in result.error+++# ------------------------------------------------------------------+# Registry discovery+# ------------------------------------------------------------------++class TestRegistryDiscovery:++ def test_discoverable(self, isolated_tool_registry):+ isolated_tool_registry.discover()+ tool = isolated_tool_registry.get("hunyuan_cloud_video")+ assert tool is not None+ assert tool.provider == "hunyuan_cloud"+ assert tool.capability == "video_generation"++ def test_distinct_from_local_hunyuan_tool(self, isolated_tool_registry):+ isolated_tool_registry.discover()+ cloud = isolated_tool_registry.get("hunyuan_cloud_video")+ local = isolated_tool_registry.get("hunyuan_video")+ assert cloud is not None+ assert local is not None+ assert cloud.provider == "hunyuan_cloud"+ assert local.provider == "hunyuan"+ assert cloud.runtime == ToolRuntime.API+ assert local.runtime == ToolRuntime.LOCAL_GPU+++# ------------------------------------------------------------------+# Schema validation+# ------------------------------------------------------------------++class TestSchemaValidation:++ def test_prompt_max_length_200(self):+ schema = HunyuanCloudVideo().input_schema+ assert schema["properties"]["prompt"]["maxLength"] == 200++ def test_prompt_rejects_over_200_chars(self):+ import jsonschema+ schema = HunyuanCloudVideo().input_schema+ instance = {"prompt": "x" * 201}+ with pytest.raises(jsonschema.ValidationError):+ jsonschema.validate(instance, schema)++ def test_prompt_accepts_200_chars(self):+ import jsonschema+ schema = HunyuanCloudVideo().input_schema+ instance = {"prompt": "x" * 200}+ jsonschema.validate(instance, schema)++ def test_operation_accepts_valid_values(self):+ import jsonschema+ schema = HunyuanCloudVideo().input_schema+ for op in ["text_to_video", "image_to_video"]:+ jsonschema.validate({"prompt": "test", "operation": op}, schema)++ def test_operation_rejects_invalid_values(self):+ import jsonschema+ schema = HunyuanCloudVideo().input_schema+ for invalid in ["video_to_video", "", "TEXT_TO_VIDEO"]:+ with pytest.raises(jsonschema.ValidationError):+ jsonschema.validate({"prompt": "test", "operation": invalid}, schema)++ def test_model_accepts_valid_values(self):+ import jsonschema+ schema = HunyuanCloudVideo().input_schema+ for m in ["hy-video-1.5", "yt-video-2.0"]:+ jsonschema.validate({"prompt": "test", "model": m}, schema)++ def test_model_rejects_invalid_values(self):+ import jsonschema+ schema = HunyuanCloudVideo().input_schema+ with pytest.raises(jsonschema.ValidationError):+ jsonschema.validate({"prompt": "test", "model": "invalid-model"}, schema)++ def test_logo_add_accepts_0_and_1(self):+ import jsonschema+ schema = HunyuanCloudVideo().input_schema+ for val in [0, 1]:+ jsonschema.validate({"prompt": "test", "logo_add": val}, schema)++ def test_logo_add_rejects_other_values(self):+ import jsonschema+ schema = HunyuanCloudVideo().input_schema+ for invalid in [2, -1, 99]:+ with pytest.raises(jsonschema.ValidationError):+ jsonschema.validate({"prompt": "test", "logo_add": invalid}, schema)++ def test_poll_interval_minimum_2(self):+ schema = HunyuanCloudVideo().input_schema+ assert schema["properties"]["poll_interval_seconds"]["minimum"] == 2++ def test_timeout_minimum_60(self):+ schema = HunyuanCloudVideo().input_schema+ assert schema["properties"]["timeout_seconds"]["minimum"] == 60++ def test_resolution_only_720p(self):+ schema = HunyuanCloudVideo().input_schema+ assert schema["properties"]["resolution"]["enum"] == ["720p", "1080p"]diff --git a/tools/video/hunyuan_cloud_video.py b/tools/video/hunyuan_cloud_video.pynew file mode 100644index 00000000..2ab430b2--- /dev/null+++ b/tools/video/hunyuan_cloud_video.py@@ -0,0 +1,523 @@+"""Tencent Hunyuan (腾讯混元) cloud video generation via TokenHub API.++Calls the Tencent TokenHub API (tokenhub.tencentmaas.com) using simple Bearer+token authentication. This is the OpenAI-compatible API gateway for Tencent+Hunyuan video models — no TC3-HMAC-SHA256 signing required.++API flow: POST /v1/api/video/submit -> poll /v1/api/video/query ->+download data.url.++Authentication uses a TokenHub API key obtained from the Tencent Cloud+TokenHub console (https://console.cloud.tencent.com/tokenhub).+"""++from __future__ import annotations++import os+import time+from pathlib import Path+from typing import Any++from tools.base_tool import (+ BaseTool,+ Determinism,+ ExecutionMode,+ ResourceProfile,+ RetryPolicy,+ ToolResult,+ ToolRuntime,+ ToolStability,+ ToolStatus,+ ToolTier,+)++_HOST = "tokenhub.tencentmaas.com"+_SUBMIT_PATH = "/v1/api/video/submit"+_QUERY_PATH = "/v1/api/video/query"++# TokenHub model identifiers+_MODEL_T2V = "hy-video-1.5" # text-to-video+_MODEL_I2V = "yt-video-2.0" # image-to-video+++class HunyuanCloudVideo(BaseTool):+ """Tencent Hunyuan cloud video generation via TokenHub API."""++ name = "hunyuan_cloud_video"+ version = "0.1.0"+ tier = ToolTier.GENERATE+ capability = "video_generation"+ provider = "hunyuan_cloud"+ stability = ToolStability.EXPERIMENTAL+ execution_mode = ExecutionMode.ASYNC+ determinism = Determinism.STOCHASTIC+ runtime = ToolRuntime.API++ dependencies = []+ install_instructions = (+ "Set TENCENT_TOKENHUB_API_KEY to your Tencent Cloud TokenHub API key.\n"+ " Get it at https://console.cloud.tencent.com/tokenhub\n"+ " Optionally set TENCENT_TOKENHUB_MODEL to override the default model."+ )+ agent_skills = ["ai-video-gen"]++ capabilities = ["text_to_video", "image_to_video"]+ supports = {+ "text_to_video": True,+ "image_to_video": True,+ "native_audio": False,+ "seed": False,+ }+ best_for = [+ "Hunyuan text-to-video and image-to-video via Tencent TokenHub API",+ "simple Bearer-token auth (no TC3 signing required)",+ "direct Tencent Cloud quota usage (not through a third-party gateway)",+ "Chinese-language prompt understanding"+ ]+ not_good_for = [+ "offline generation or air-gapped environments",+ "users without Tencent Cloud account and real-name verification"+ ]+ fallback_tools = ["jimeng_video", "kling_official_video", "minimax_video"]++ input_schema = {+ "type": "object",+ "required": ["prompt"],+ "properties": {+ "prompt": {+ "type": "string",+ "maxLength": 200,+ "description": (+ "Video description. Max 200 UTF-8 characters. "+ "Supports Chinese and English. Be specific about subject, action, "+ "setting, and style."+ ),+ },+ "operation": {+ "type": "string",+ "enum": ["text_to_video", "image_to_video"],+ "default": "text_to_video",+ "description": "Generation mode.",+ },+ "model": {+ "type": "string",+ "enum": ["hy-video-1.5", "yt-video-2.0"],+ "description": (+ "TokenHub model ID. hy-video-1.5 for text-to-video, "+ "yt-video-2.0 for image-to-video. Defaults to the recommended "+ "model for the chosen operation."+ ),+ },+ "image_url": {+ "type": "string",+ "description": (+ "Reference image URL for image-to-video. "+ "Must be publicly accessible. Max 10MB. "+ "Formats: jpg/png/jpeg/webp/bmp/tiff. "+ "Resolution: 50-5000 pixels per side, aspect ratio 1:4 to 4:1."+ ),+ },+ "image_path": {+ "type": "string",+ "description": (+ "Local path to a reference image for image-to-video. "+ "Will be base64-encoded and sent inline. "+ "Mutually exclusive with image_url."+ ),+ },+ "resolution": {+ "type": "string",+ "enum": ["720p", "1080p"],+ "default": "720p",+ "description": "Output resolution.",+ },+ "logo_add": {+ "type": "integer",+ "enum": [0, 1],+ "default": 1,+ "description": (+ "Add 'AI-generated' watermark. 1 = add watermark (default), "+ "0 = no watermark (requires console approval from Tencent)."+ ),+ },+ "output_path": {+ "type": "string",+ "description": "Output file path for the generated video (MP4).",+ },+ "poll_interval_seconds": {+ "type": "number",+ "minimum": 2,+ "default": 5.0,+ "description": "Seconds between status polls.",+ },+ "timeout_seconds": {+ "type": "integer",+ "minimum": 60,+ "default": 600,+ "description": "Maximum seconds to wait for generation.",+ },+ },+ }++ resource_profile = ResourceProfile(+ cpu_cores=1, ram_mb=512, vram_mb=0, disk_mb=500, network_required=True,+ )+ retry_policy = RetryPolicy(+ max_retries=2,+ backoff_seconds=2.0,+ retryable_errors=["rate_limit", "timeout"],+ )+ idempotency_key_fields = [+ "prompt",+ "operation",+ "model",+ "image_url",+ "resolution",+ ]+ side_effects = [+ "writes video file to output_path",+ "calls Tencent TokenHub API (Bearer-token submit + poll + download)",+ ]+ user_visible_verification = [+ "Watch generated clip for motion coherence and prompt adherence",+ "Check for watermark if logo_add=0 was requested",+ ]++ # ------------------------------------------------------------------+ # Credential helpers+ # ------------------------------------------------------------------++ @staticmethod+ def _api_key() -> str | None:+ val = os.environ.get("TENCENT_TOKENHUB_API_KEY", "")+ if val and not val.strip().startswith("#"):+ return val.strip()+ return None++ # ------------------------------------------------------------------+ # Tool contract methods+ # ------------------------------------------------------------------++ def get_status(self) -> ToolStatus:+ if self._api_key():+ return ToolStatus.AVAILABLE+ return ToolStatus.UNAVAILABLE++ def estimate_cost(self, inputs: dict[str, Any]) -> float:+ """Estimate cost in USD based on model and resolution.++ Tencent TokenHub credit-based pricing (1 credit = 1.2 RMB ≈ $0.167 USD):+ - HY-Video-1.5: 1.5 credits/generation → $0.25+ - YT-Video-2.0 480p: 2 credits/generation → $0.33+ - YT-Video-2.0 720p/1080p: 5 credits/generation → $0.83++ Source: https://cloud.tencent.com.cn/document/product/1823/130054+ """+ model = self._resolve_model(inputs)+ resolution = inputs.get("resolution", "720p")++ _CREDIT_TO_USD = 1.2 / 7.2 # 1 credit = 1.2 RMB, ~7.2 RMB/USD++ if model == _MODEL_I2V:+ # YT-Video-2.0 has resolution-tiered pricing+ if resolution in ("720p", "1080p"):+ credits = 5.0+ else:+ credits = 2.0 # 480p and below+ else:+ # HY-Video-1.5 (and fallback for unknown models)+ credits = 1.5++ return round(credits * _CREDIT_TO_USD, 2)++ def estimate_runtime(self, inputs: dict[str, Any]) -> float:+ """Estimate wall-clock time in seconds.++ Empirical estimate: most cloud video generation APIs (Kling, Pika, etc.)+ queue + generate in 60-180s. No official latency published by Tencent.+ 180s is a safe upper-bound for timeout planning.+ """+ return 180.0++ # ------------------------------------------------------------------+ # Main execution+ # ------------------------------------------------------------------++ def execute(self, inputs: dict[str, Any]) -> ToolResult:+ api_key = self._api_key()+ if not api_key:+ return ToolResult(+ success=False,+ error="TENCENT_TOKENHUB_API_KEY not set. " + self.install_instructions,+ )++ operation = inputs.get("operation", "text_to_video")+ if operation == "image_to_video" and not inputs.get("image_url") and not inputs.get("image_path"):+ return ToolResult(+ success=False,+ error="image_to_video requires image_url (public URL) or image_path (local file).",+ )++ if inputs.get("image_url") and inputs.get("image_path"):+ return ToolResult(+ success=False,+ error="Provide only one of image_url or image_path, not both.",+ )++ start = time.time()+ try:+ result = self._generate(inputs, api_key=api_key)+ except Exception as exc:+ return ToolResult(+ success=False,+ error=f"Hunyuan TokenHub video generation failed: {self._safe_error(exc)}",+ )++ result.duration_seconds = round(time.time() - start, 2)+ return result++ # ------------------------------------------------------------------+ # Generation pipeline+ # ------------------------------------------------------------------++ def _generate(+ self, inputs: dict[str, Any], *, api_key: str,+ ) -> ToolResult:+ import requests++ from tools.video._shared import probe_output++ payload = self._build_payload(inputs)+ model = self._resolve_model(inputs)+ task_id = self._submit_task(payload, model=model, api_key=api_key)+ video_url = self._poll_task(+ task_id,+ model=model,+ api_key=api_key,+ poll_interval=float(inputs.get("poll_interval_seconds", 5.0)),+ timeout_seconds=int(inputs.get("timeout_seconds", 600)),+ )++ download = requests.get(video_url, timeout=120)+ download.raise_for_status()++ output_path = Path(+ inputs.get("output_path", f"hunyuan_cloud_{task_id}.mp4")+ )+ output_path.parent.mkdir(parents=True, exist_ok=True)+ output_path.write_bytes(download.content)++ probed = probe_output(output_path)+ return ToolResult(+ success=True,+ data={+ "provider": "hunyuan_cloud",+ "route": "tokenhub",+ "model": model,+ "prompt": inputs["prompt"],+ "operation": inputs.get("operation", "text_to_video"),+ "resolution": inputs.get("resolution", "720p"),+ "logo_add": payload.get("logo_add", 1),+ "task_id": task_id,+ "video_url": video_url,+ "output": str(output_path),+ "format": "mp4",+ **probed,+ },+ artifacts=[str(output_path)],+ cost_usd=self.estimate_cost(inputs),+ model=model,+ )++ # ------------------------------------------------------------------+ # Payload construction+ # ------------------------------------------------------------------++ def _build_payload(self, inputs: dict[str, Any]) -> dict[str, Any]:+ """Build the request body for TokenHub video submit."""+ operation = inputs.get("operation", "text_to_video")+ payload: dict[str, Any] = {+ "prompt": inputs["prompt"],+ }++ # Optional parameters (TokenHub uses lowercase_with_underscores)+ if inputs.get("resolution"):+ payload["resolution"] = inputs["resolution"]+ if "logo_add" in inputs:+ payload["logo_add"] = int(inputs["logo_add"])++ # Image for image-to-video+ if operation == "image_to_video":+ if inputs.get("image_url"):+ payload["image_url"] = inputs["image_url"]+ elif inputs.get("image_path"):+ payload["image"] = self._encode_image(inputs["image_path"])++ return payload++ @staticmethod+ def _resolve_model(inputs: dict[str, Any]) -> str:+ """Resolve the TokenHub model ID.++ Order of precedence:+ 1. Explicit ``model`` input+ 2. TENCENT_TOKENHUB_MODEL env var+ 3. Default based on operation (hy-video-1.5 for T2V, yt-video-2.0 for I2V)+ """+ if inputs.get("model"):+ return inputs["model"]+ env_model = os.environ.get("TENCENT_TOKENHUB_MODEL", "").strip()+ if env_model:+ return env_model+ operation = inputs.get("operation", "text_to_video")+ return _MODEL_I2V if operation == "image_to_video" else _MODEL_T2V++ @staticmethod+ def _encode_image(path: str) -> str:+ """Read a local image file and return a base64-encoded string."""+ import base64++ image_path = Path(path)+ if not image_path.is_file():+ raise FileNotFoundError(f"Image not found: {path}")++ raw = image_path.read_bytes()+ max_raw = 6 * 1024 * 1024 # 6MB raw ≈ 8MB base64+ if len(raw) > max_raw:+ raise ValueError(+ f"Image too large ({len(raw)} bytes). Max ~6MB raw (8MB base64-encoded)."+ )++ return base64.b64encode(raw).decode("ascii")++ # ------------------------------------------------------------------+ # API communication (TokenHub OpenAI-compatible)+ # ------------------------------------------------------------------++ @staticmethod+ def _auth_headers(api_key: str) -> dict[str, str]:+ """Build common request headers for TokenHub API calls."""+ return {+ "Authorization": f"Bearer {api_key}",+ "Content-Type": "application/json",+ }++ def _submit_task(+ self, payload: dict[str, Any], *, model: str, api_key: str,+ ) -> str:+ """Submit a video generation task and return the task ID."""+ import requests++ body = {+ "model": model,+ **payload,+ }+ url = f"https://{_HOST}{_SUBMIT_PATH}"+ resp = requests.post(+ url,+ json=body,+ headers=self._auth_headers(api_key),+ timeout=30,+ )+ data = self._json_or_raise(resp)+ self._check_response(data)++ task_id = data.get("id")+ if not task_id:+ raise RuntimeError(+ f"TokenHub submit returned no task id: {data}"+ )+ return task_id++ def _poll_task(+ self,+ task_id: str,+ *,+ model: str,+ api_key: str,+ poll_interval: float,+ timeout_seconds: int,+ ) -> str:+ """Poll /v1/api/video/query until completion, return video download URL."""+ import requests++ url = f"https://{_HOST}{_QUERY_PATH}"++ deadline = time.time() + timeout_seconds+ while time.time() < deadline:+ time.sleep(poll_interval)++ resp = requests.post(+ url,+ json={"model": model, "id": task_id},+ headers=self._auth_headers(api_key),+ timeout=30,+ )+ data = self._json_or_raise(resp)+ self._check_response(data)++ status = data.get("status", "")++ if status == "completed":+ result_data = data.get("data") or {}+ video_url = result_data.get("url")+ if not video_url:+ raise RuntimeError(+ f"TokenHub task {task_id} completed but no data.url: {data}"+ )+ return video_url++ if status == "failed":+ error_info = data.get("error") or {}+ error_msg = error_info.get("message", "unknown error")+ raise RuntimeError(+ f"TokenHub task {task_id} failed: {error_msg}"+ )++ # queued / running / in_progress — continue polling+ if status not in ("queued", "running", "in_progress"):+ raise RuntimeError(+ f"TokenHub task {task_id} returned unknown status: {status}"+ )++ raise TimeoutError(+ f"TokenHub task {task_id} did not finish within {timeout_seconds}s"+ )++ # ------------------------------------------------------------------+ # Error handling helpers+ # ------------------------------------------------------------------++ @staticmethod+ def _safe_error(exc: Exception) -> str:+ """Redact secret values from exception messages."""+ msg = str(exc)+ for var in ("TENCENT_TOKENHUB_API_KEY",):+ val = os.environ.get(var, "")+ if val:+ msg = msg.replace(val, "[redacted]")+ return msg++ @staticmethod+ def _json_or_raise(response: Any) -> dict[str, Any]:+ """Parse JSON response body or raise with HTTP status."""+ try:+ return response.json()+ except ValueError as exc:+ raise RuntimeError(+ f"Non-JSON response from TokenHub API: HTTP {response.status_code}"+ ) from exc++ @staticmethod+ def _check_response(payload: dict[str, Any]) -> None:+ """Check the TokenHub API response for errors.++ TokenHub returns errors at the top level with an ``error`` field.+ """+ error = payload.get("error")+ if error:+ message = error.get("message", "unknown error")+ code = error.get("code", error.get("type", "unknown"))+ raise RuntimeError(+ f"TokenHub API error: code={code}, message={message}"+ )