What causes "ARK_API_KEY not set." in ATH-MaaS/Pixelle-Video?

Set the ARK_API_KEY environment variable before running: export ARK_API_KEY=your-key

ATH-MaaS/Pixelle-Video · critical · RuntimeError

ARK_API_KEY not set.

Error message

ARK_API_KEY not set.

What it means

SeedanceVideoClient.generate_video throws RuntimeError when self.api_key is falsy before doing any work. The client requires the ARK_API_KEY environment variable to authenticate against the Volcano Engine (Ark) Seedance video-generation API; without it no request can be signed.

Source

Thrown at pixelle_video/services/api_services/video_seedance.py:67

        prompt: str,
        image_path: Optional[str],
        save_path: str,
        model: str = "doubao-seedance-2-0-260128",
        duration: int = 5,
        **kwargs
    ) -> str:
        """
        图生视频完整流程

        Args:
            prompt: 提示词
            image_path: 输入图片本地路径；为空时走文生视频
            save_path: 输出视频保存路径
            model: 模型名称
            duration: 视频时长
        """
        if not self.api_key:
            raise RuntimeError("ARK_API_KEY not set.")

        # 1. 提交任务
        task_id = self._submit_task(prompt, image_path, model, duration, **kwargs)
        
        # 2. 轮询等待
        video_url = self._poll_until_done(task_id)
        
        # 3. 下载视频
        self._download_video(video_url, save_path)
        
        return video_url

    def _submit_task(self, prompt: str, image_path: Optional[str], model: str, duration: int, **kwargs) -> str:
        # 根据 Seedance 2.0 文档更新接口路径
        url = f"{self.base_url}/contents/generations/tasks"

        # 构建 content 数组
        content = []

View on GitHub (pinned to 848b054e4f)

Solutions

Set the ARK_API_KEY environment variable before running: export ARK_API_KEY=your-key
If using a .env file, ensure it is loaded (e.g. python-dotenv load_dotenv()) and contains ARK_API_KEY
Verify the key is present at process start: python -c "import os; print(bool(os.environ.get('ARK_API_KEY')))"
If the client accepts an api_key argument, pass it explicitly instead of relying on the environment

Example fix

// before
python generate.py   # ARK_API_KEY not set
// after
export ARK_API_KEY="your-volcano-engine-key"
python generate.py

Defensive patterns

Strategy: validation

Validate before calling

import os
if not os.environ.get("ARK_API_KEY"):
    raise SystemExit("Set ARK_API_KEY before running")

Try / catch

try:
    client.generate_video(prompt=p, image_path=img, save_path=out)
except RuntimeError as e:
    if "ARK_API_KEY" in str(e):
        logging.critical("Missing ARK_API_KEY; configure the environment")
    else:
        raise

Prevention

Fail fast at process startup with an env-var presence check
Keep all secrets in .env and load it before any client construction
Add ARK_API_KEY to CI/CD secret injection and container env templates

When it happens

Trigger: Instantiating SeedanceVideoClient without ARK_API_KEY set in the environment (or empty string) and then calling generate_video().

Common situations: Developer forgot to export ARK_API_KEY in shell/container; .env file not loaded; CI/CD secrets not injected; typo like ARKAPI_KEY; key set for a different user account than the one running the app.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

AI-assisted analysis of ATH-MaaS/Pixelle-Video@848b054e4f (2026-08-30). Data as JSON: /api/errors/04c67be31a0b6db4. Report an issue: GitHub.