volcengine-ark-mcp 0.6.0__tar.gz

volcengine_ark_mcp-0.6.0/.gitignore

@@ -0,0 +1,9 @@
+.DS_Store
+.idea/
+.vscode/
+__pycache__/
+*.egg-info/
+.venv/
+dist/
+build/
+.upstream-docs/

volcengine_ark_mcp-0.6.0/PKG-INFO

@@ -0,0 +1,118 @@
+Metadata-Version: 2.5
+Name: volcengine-ark-mcp
+Version: 0.6.0
+Summary: 火山方舟图片、Seedance视频、语言模型、搜索、向量与任务恢复 MCP server
+Project-URL: Homepage, https://github.com/hoobnn/hoobnn-mcps/tree/main/servers/volcengine-ark
+Project-URL: Repository, https://github.com/hoobnn/hoobnn-mcps
+Project-URL: Issues, https://github.com/hoobnn/hoobnn-mcps/issues
+Author: hoobnn
+License-Expression: MIT
+Keywords: ark,doubao,mcp,mcp-server,seedance,seedream,volcengine
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: httpx<1,>=0.28
+Requires-Dist: mcp<3,>=2.3
+Description-Content-Type: text/markdown
+
+# volcengine-ark-mcp
+
+调用火山方舟（Volcengine Ark）的 MCP server：Seedream 5.0 生成和编辑图片、Seedance 视频、对话与多模态理解、联网搜索和向量化，产物直接存到本地。
+
+原名 `seedream-mcp`（PyPI 上该名已被他人占用），0.4 起改名，不保留旧命令和 `SEEDREAM_*` 环境变量。
+
+`0.6.0` 去掉 `query_video`：视频进度统一用 `get_job(job_id=...)` 或 `get_job(task_id=...)` 查询，完成时自动下载；`generate_image` 新增 `parameters`。这是不兼容变更。
+
+## Seedream 图片生成
+
+| 模型 | 参数 | 独有能力 |
+|---|---|---|
+| Seedream 5.0 pro（默认） | `model="pro"` → `doubao-seedream-5-0-pro-260628` | 图层拆分、交互编辑、透明背景、fast 模式 |
+| Seedream 5.0 flash | `model="flash"` → `doubao-seedream-5-0-flash-260915` | 图层拆分、交互编辑、透明背景；不支持 fast 提示词优化 |
+| Seedream 5.0 lite | `model="lite"` → `doubao-seedream-5-0-260128` | 组图、联网搜索、3K / 4K |
+
+三个模型都支持文生图和单图 / 多图参考生图。模型不支持的参数组合会在本地直接报错，不发请求。
+
+## 环境变量
+
+| 变量 | 说明 |
+|---|---|
+| `ARK_API_KEY` | 必需，方舟控制台 → API Key 管理 |
+| `ARK_OUT_DIR` | 输出目录，默认 `~/Downloads/volcengine-ark` |
+| `ARK_RESOURCE_MODE` | 交付方式：`local`（默认）下载到本地，`url` 只返回 24 小时内有效的链接 |
+| `ARK_BASE_URL` | 默认 `https://ark.cn-beijing.volces.com/api/v3` |
+
+参数说明见工具描述（`src/volcengine_ark_mcp/server.py`），接口细节以[图片生成 API 文档](https://ark.volcengine.com/region:cn-beijing/docs/ark/image-generation-api)为准。
+
+## 0.3 方舟扩展（待云端验证）
+
+保留原有生图工具，同时接入方舟其他能力，无需新建MCP配置。
+
+| 工具 | 能力 | 官方来源 |
+|---|---|---|
+| `generate_video` | Seedance文生、首帧、首尾帧、多模态参考视频 | [创建任务](https://docs.volcengine.com/docs/ark/create-video-generation-task-api?lang=zh)、[查询任务](https://docs.volcengine.com/docs/ark/get-video-generation-task-api?lang=zh) |
+| `chat` | 语言、图片/视频理解、深度思考、结构化输出 | [Chat](https://docs.volcengine.com/docs/ark/chat-api?lang=zh)、[Responses](https://docs.volcengine.com/docs/ark/create-model-responses-api?lang=zh) |
+| `chat(web_search=true)` | 联网搜索，保留来源和完整响应 | [Web Search](https://docs.volcengine.com/docs/ark/web-search?lang=zh) |
+| `embed` | 文本与多模态向量化 | [向量化](https://docs.volcengine.com/docs/ark/vectorization?lang=zh)、[多模态API](https://docs.volcengine.com/docs/ark/multimodal-vectorization-api?lang=zh) |
+| `list_capabilities` | 静态能力目录和边界 | 不联网，不代表账号权限 |
+| `list_jobs` / `get_job` / `recover_job` | 查任务进度（视频生成中会查询方舟并在完成时下载）、补交付 | 图片和视频留档，跨进程重启恢复 |
+
+### Seedance视频
+
+模型别名：`seedance` → `doubao-seedance-2-5-260628`；`seedance-2` / `seedance-fast` / `seedance-mini` → 相应2.0系列。
+也可直接指定完整模型ID或Endpoint ID。不同模型的素材数量、时长、分辨率限制以官方接口为准。
+
+默认 `wait=0`，提交后返回 `task_id`、`job_id`。`get_job(job_id=..., wait=30)` 查询进度，完成后下载到原目录；别处提交的任务可传 `get_job(task_id=...)`，首次查询会新建本地记录。下载失败或链接过期用 `recover_job(job_id=...)`。都不会提交新生成。
+
+图片支持本地路径/data URL/公网URL；视频和音频参考使用公网URL或 `asset://` ID。本轮没有自动上传本地视频/音频。
+2.5首帧/首尾帧任务 `ratio=adaptive`；输出时长为4–30秒，2.0系列为4–15秒，均可用 `duration=-1`。首尾帧与全模态参考不能混用；2.0系列不能仅传音频。
+2.0标准版支持4k，fast/mini仅480p/720p。视频编辑通过prompt明确意图，`duration=-1`、`ratio=adaptive`；可用 `parameters.omni_reference_task_type="edit"` 提前校验任务类型，省略duration采用官方默认值。
+`parameters` 可传官方顶层选项，如 `draft`、`return_last_frame`、`output_format`；不能覆盖模型和输入素材。
+
+### 对话与检索
+
+`chat` 默认 `pro` 为 `doubao-seed-2-1-pro-260628`，也可显式指定模型；与生图工具中的pro别名含义不同。
+`images` 支持本地图片，`videos` 须公开URL。不开搜索时使用Chat API；开启 `web_search` 或提供 `previous_response_id` 时使用Responses API。
+多轮历史采用Chat消息结构，Responses会转换本轮多模态内容；保留 `response_id`、来源注解；完整响应用 `include_response=true` 按需获取。
+`parameters` 透传模型支持的高级选项，不执行模型返回的工具调用。
+
+向量工具须显式指定模型：`texts` 为文本列表；`contents` 为官方类型化数组，例如：
+
+```json
+[{"type":"text","text":"猫"},{"type":"image_url","image_url":{"url":"/absolute/cat.png"}}]
+```
+
+返回 `data`、`usage`，完整响应用 `include_response=true` 按需获取；不自动建索引或知识库。
+
+### 本地恢复
+
+`ARK_JOB_DIR` 默认 `~/.local/share/volcengine-ark-mcp/jobs`。生成前创建记录，响应收到后保留完整响应，内联图片先缓存再交付。
+组图逐项记录错误，下载失败可单独补交付；图层记录和 `layers.json` 随恢复更新。部分生成失败会返回 `partial`，不会重新生成失败项。
+视频保存原 `task_id`，通过云端查询刷新URL。临时URL或云端任务过期可能无法恢复。
+
+返回 `job_id`、`job_state`、`request_id` 和 `artifacts`。`ok` 表示本次调用成功；已提交、运行中返回 `ok=true, completed=false`，全部交付返回 `completed=true`，执行错误通过 MCP `isError=true` 返回。
+`get_job.ok` 是记录读取成功；调用超时没拿到ID时可用 `list_jobs` 按时间查找。保留原有files、layers、usage、errors字段。
+每项产物记录字节数和SHA-256；下载采用临时文件和原子替换。质量、像素尺寸和媒体播放仍需后续验证。
+
+`url`模式也留存任务元数据；任务目录保存签名URL、响应与图片缓存，不保存API Key。缓存用于恢复，不自动清理。
+恢复锁使用POSIX `flock`，面向macOS/Linux。产物默认目录增加随机后缀，避免同秒调用碰撞。
+
+原始接入范围见 [接入记录](https://github.com/hoobnn/hoobnn-mcps/blob/main/docs/mcp-expansion.md)。当前运行时和任务恢复已通过离线故障测试及真实 stdio 检查；尚未验证云端生成、账号权限和媒体质量。
+
+产物的 `media_info` 读取PNG头中的实际宽高；若系统已有 `ffprobe`，可读取其他媒体的实际尺寸、时长和音轨信息。不可读取时显式返回 `available=false`，不把请求参数当作实际输出规格。无需新增Python依赖。
+
+## 运行时与稳定性
+
+共享连接池、总超时、工具分组、错误语义和迁移说明见 [MCP 构建与稳定性](https://github.com/hoobnn/hoobnn-mcps/blob/main/docs/mcp-reliability.md)。完整工具说明可调用 `get_tool_help(tool="工具名")`。
+
+## 官方接口核实
+
+逐工具映射、模型版本、参数差异和可程序化获取的官方文档来源见 [火山方舟接口审计](https://github.com/hoobnn/hoobnn-mcps/blob/main/docs/audits/volcengine-ark.md)。本地校验依据2026-10-10官方文档快照；账号权限及实际云端生成仍未验证。

volcengine_ark_mcp-0.6.0/README.md

@@ -0,0 +1,93 @@
+# volcengine-ark-mcp
+
+调用火山方舟（Volcengine Ark）的 MCP server：Seedream 5.0 生成和编辑图片、Seedance 视频、对话与多模态理解、联网搜索和向量化，产物直接存到本地。
+
+原名 `seedream-mcp`（PyPI 上该名已被他人占用），0.4 起改名，不保留旧命令和 `SEEDREAM_*` 环境变量。
+
+`0.6.0` 去掉 `query_video`：视频进度统一用 `get_job(job_id=...)` 或 `get_job(task_id=...)` 查询，完成时自动下载；`generate_image` 新增 `parameters`。这是不兼容变更。
+
+## Seedream 图片生成
+
+| 模型 | 参数 | 独有能力 |
+|---|---|---|
+| Seedream 5.0 pro（默认） | `model="pro"` → `doubao-seedream-5-0-pro-260628` | 图层拆分、交互编辑、透明背景、fast 模式 |
+| Seedream 5.0 flash | `model="flash"` → `doubao-seedream-5-0-flash-260915` | 图层拆分、交互编辑、透明背景；不支持 fast 提示词优化 |
+| Seedream 5.0 lite | `model="lite"` → `doubao-seedream-5-0-260128` | 组图、联网搜索、3K / 4K |
+
+三个模型都支持文生图和单图 / 多图参考生图。模型不支持的参数组合会在本地直接报错，不发请求。
+
+## 环境变量
+
+| 变量 | 说明 |
+|---|---|
+| `ARK_API_KEY` | 必需，方舟控制台 → API Key 管理 |
+| `ARK_OUT_DIR` | 输出目录，默认 `~/Downloads/volcengine-ark` |
+| `ARK_RESOURCE_MODE` | 交付方式：`local`（默认）下载到本地，`url` 只返回 24 小时内有效的链接 |
+| `ARK_BASE_URL` | 默认 `https://ark.cn-beijing.volces.com/api/v3` |
+
+参数说明见工具描述（`src/volcengine_ark_mcp/server.py`），接口细节以[图片生成 API 文档](https://ark.volcengine.com/region:cn-beijing/docs/ark/image-generation-api)为准。
+
+## 0.3 方舟扩展（待云端验证）
+
+保留原有生图工具，同时接入方舟其他能力，无需新建MCP配置。
+
+| 工具 | 能力 | 官方来源 |
+|---|---|---|
+| `generate_video` | Seedance文生、首帧、首尾帧、多模态参考视频 | [创建任务](https://docs.volcengine.com/docs/ark/create-video-generation-task-api?lang=zh)、[查询任务](https://docs.volcengine.com/docs/ark/get-video-generation-task-api?lang=zh) |
+| `chat` | 语言、图片/视频理解、深度思考、结构化输出 | [Chat](https://docs.volcengine.com/docs/ark/chat-api?lang=zh)、[Responses](https://docs.volcengine.com/docs/ark/create-model-responses-api?lang=zh) |
+| `chat(web_search=true)` | 联网搜索，保留来源和完整响应 | [Web Search](https://docs.volcengine.com/docs/ark/web-search?lang=zh) |
+| `embed` | 文本与多模态向量化 | [向量化](https://docs.volcengine.com/docs/ark/vectorization?lang=zh)、[多模态API](https://docs.volcengine.com/docs/ark/multimodal-vectorization-api?lang=zh) |
+| `list_capabilities` | 静态能力目录和边界 | 不联网，不代表账号权限 |
+| `list_jobs` / `get_job` / `recover_job` | 查任务进度（视频生成中会查询方舟并在完成时下载）、补交付 | 图片和视频留档，跨进程重启恢复 |
+
+### Seedance视频
+
+模型别名：`seedance` → `doubao-seedance-2-5-260628`；`seedance-2` / `seedance-fast` / `seedance-mini` → 相应2.0系列。
+也可直接指定完整模型ID或Endpoint ID。不同模型的素材数量、时长、分辨率限制以官方接口为准。
+
+默认 `wait=0`，提交后返回 `task_id`、`job_id`。`get_job(job_id=..., wait=30)` 查询进度，完成后下载到原目录；别处提交的任务可传 `get_job(task_id=...)`，首次查询会新建本地记录。下载失败或链接过期用 `recover_job(job_id=...)`。都不会提交新生成。
+
+图片支持本地路径/data URL/公网URL；视频和音频参考使用公网URL或 `asset://` ID。本轮没有自动上传本地视频/音频。
+2.5首帧/首尾帧任务 `ratio=adaptive`；输出时长为4–30秒，2.0系列为4–15秒，均可用 `duration=-1`。首尾帧与全模态参考不能混用；2.0系列不能仅传音频。
+2.0标准版支持4k，fast/mini仅480p/720p。视频编辑通过prompt明确意图，`duration=-1`、`ratio=adaptive`；可用 `parameters.omni_reference_task_type="edit"` 提前校验任务类型，省略duration采用官方默认值。
+`parameters` 可传官方顶层选项，如 `draft`、`return_last_frame`、`output_format`；不能覆盖模型和输入素材。
+
+### 对话与检索
+
+`chat` 默认 `pro` 为 `doubao-seed-2-1-pro-260628`，也可显式指定模型；与生图工具中的pro别名含义不同。
+`images` 支持本地图片，`videos` 须公开URL。不开搜索时使用Chat API；开启 `web_search` 或提供 `previous_response_id` 时使用Responses API。
+多轮历史采用Chat消息结构，Responses会转换本轮多模态内容；保留 `response_id`、来源注解；完整响应用 `include_response=true` 按需获取。
+`parameters` 透传模型支持的高级选项，不执行模型返回的工具调用。
+
+向量工具须显式指定模型：`texts` 为文本列表；`contents` 为官方类型化数组，例如：
+
+```json
+[{"type":"text","text":"猫"},{"type":"image_url","image_url":{"url":"/absolute/cat.png"}}]
+```
+
+返回 `data`、`usage`，完整响应用 `include_response=true` 按需获取；不自动建索引或知识库。
+
+### 本地恢复
+
+`ARK_JOB_DIR` 默认 `~/.local/share/volcengine-ark-mcp/jobs`。生成前创建记录，响应收到后保留完整响应，内联图片先缓存再交付。
+组图逐项记录错误，下载失败可单独补交付；图层记录和 `layers.json` 随恢复更新。部分生成失败会返回 `partial`，不会重新生成失败项。
+视频保存原 `task_id`，通过云端查询刷新URL。临时URL或云端任务过期可能无法恢复。
+
+返回 `job_id`、`job_state`、`request_id` 和 `artifacts`。`ok` 表示本次调用成功；已提交、运行中返回 `ok=true, completed=false`，全部交付返回 `completed=true`，执行错误通过 MCP `isError=true` 返回。
+`get_job.ok` 是记录读取成功；调用超时没拿到ID时可用 `list_jobs` 按时间查找。保留原有files、layers、usage、errors字段。
+每项产物记录字节数和SHA-256；下载采用临时文件和原子替换。质量、像素尺寸和媒体播放仍需后续验证。
+
+`url`模式也留存任务元数据；任务目录保存签名URL、响应与图片缓存，不保存API Key。缓存用于恢复，不自动清理。
+恢复锁使用POSIX `flock`，面向macOS/Linux。产物默认目录增加随机后缀，避免同秒调用碰撞。
+
+原始接入范围见 [接入记录](https://github.com/hoobnn/hoobnn-mcps/blob/main/docs/mcp-expansion.md)。当前运行时和任务恢复已通过离线故障测试及真实 stdio 检查；尚未验证云端生成、账号权限和媒体质量。
+
+产物的 `media_info` 读取PNG头中的实际宽高；若系统已有 `ffprobe`，可读取其他媒体的实际尺寸、时长和音轨信息。不可读取时显式返回 `available=false`，不把请求参数当作实际输出规格。无需新增Python依赖。
+
+## 运行时与稳定性
+
+共享连接池、总超时、工具分组、错误语义和迁移说明见 [MCP 构建与稳定性](https://github.com/hoobnn/hoobnn-mcps/blob/main/docs/mcp-reliability.md)。完整工具说明可调用 `get_tool_help(tool="工具名")`。
+
+## 官方接口核实
+
+逐工具映射、模型版本、参数差异和可程序化获取的官方文档来源见 [火山方舟接口审计](https://github.com/hoobnn/hoobnn-mcps/blob/main/docs/audits/volcengine-ark.md)。本地校验依据2026-10-10官方文档快照；账号权限及实际云端生成仍未验证。

volcengine_ark_mcp-0.6.0/pyproject.toml

@@ -0,0 +1,37 @@
+[project]
+name = "volcengine-ark-mcp"
+version = "0.6.0"
+description = "火山方舟图片、Seedance视频、语言模型、搜索、向量与任务恢复 MCP server"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [{ name = "hoobnn" }]
+keywords = ["mcp", "mcp-server", "volcengine", "ark", "seedream", "seedance", "doubao"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Multimedia",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = ["mcp>=2.3,<3", "httpx>=0.28,<1"]
+
+[project.urls]
+Homepage = "https://github.com/hoobnn/hoobnn-mcps/tree/main/servers/volcengine-ark"
+Repository = "https://github.com/hoobnn/hoobnn-mcps"
+Issues = "https://github.com/hoobnn/hoobnn-mcps/issues"
+
+[project.scripts]
+volcengine-ark-mcp = "volcengine_ark_mcp.server:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.sdist]
+only-include = ["src", "tests", "README.md"]

volcengine_ark_mcp-0.6.0/src/volcengine_ark_mcp/__init__.py

@@ -0,0 +1 @@
+"""火山方舟 MCP server：Seedream 图片、Seedance 视频、对话、搜索与向量化。"""

volcengine_ark_mcp-0.6.0/src/volcengine_ark_mcp/ark.py

@@ -0,0 +1,238 @@
+"""火山方舟图片生成 API 的校验、请求与落盘。通过共享 HTTP 连接池请求。"""
+
+import base64
+import json
+import os
+import re
+import urllib.error
+import urllib.request
+
+from . import transport
+from .mcp_runtime import merge_parameters
+from pathlib import Path
+
+BASE_URL = os.environ.get("ARK_BASE_URL", "https://ark.cn-beijing.volces.com/api/v3")
+MODELS = {
+    "pro": "doubao-seedream-5-0-pro-260628",
+    "lite": "doubao-seedream-5-0-260128",
+    "flash": "doubao-seedream-5-0-flash-260915",
+}
+MAX_REF = {"pro": 10, "flash": 10, "lite": 14}
+IMAGE_EXT = {"png", "jpeg", "jpg", "webp", "bmp", "tiff", "tif", "gif", "heic", "heif"}
+
+
+class InputError(ValueError):
+    pass
+
+
+def family(model):
+    if "seedream-5-0-flash" in model:
+        return "flash"
+    if "seedream-5-0-pro" in model:
+        return "pro"
+    if "seedream-5-0-26" in model:
+        return "lite"
+    return None  # Endpoint ID 等无法识别的，跳过本地校验，交给服务端
+
+
+def encode_image(src):
+    if src.startswith(("http://", "https://", "data:")):
+        return src
+    p = Path(src).expanduser()
+    if not p.is_file():
+        raise InputError(f"参考图不存在：{src}")
+    ext = p.suffix.lower().lstrip(".")
+    if ext not in IMAGE_EXT:
+        raise InputError(f"不支持的图片格式：{p.name}")
+    if p.stat().st_size > 30 * 1024 * 1024:
+        raise InputError(f"参考图超过 30MB：{p.name}")
+    mime = {"jpg": "jpeg", "tif": "tiff"}.get(ext, ext)
+    return f"data:image/{mime};base64," + base64.b64encode(p.read_bytes()).decode()
+
+
+def check(o, fam):
+    """服务端也会拒，但本地先挡掉，省一次请求和一段等待。"""
+    n = len(o["images"])
+    if fam in ("pro", "flash") and (o["group"] is not None or o["web_search"]):
+        return f"Seedream 5.0 {fam} 不支持组图（group）和联网搜索（web_search），改用 model=lite"
+    if fam == "flash" and o["fast"]:
+        return "Seedream 5.0 flash 不支持 fast 提示词优化模式"
+    if fam == "lite":
+        if o["layers"] or o["transparent"]:
+            return "图层拆分（layers）和透明背景（transparent）仅 Seedream 5.0 pro/flash 支持"
+        if o["fast"]:
+            return "fast 只有 Seedream 5.0 pro 支持"
+    if fam and n > MAX_REF[fam]:
+        return f"{fam} 最多 {MAX_REF[fam]} 张参考图，当前 {n} 张"
+    if o["layers"] and n != 1:
+        return "图层拆分必须且只能传 1 张图（png / jpeg）"
+    if o["transparent"]:
+        if n != 1:
+            return "透明背景只支持图生图，且只能传 1 张带透明通道的图"
+        if o["output_format"] == "jpeg":
+            return "透明背景输出是 png，不能同时指定 output_format=jpeg"
+    if o["group"] is not None and (isinstance(o["group"], bool) or not isinstance(o["group"], int) or o["group"] < 1 or n + o["group"] > 15):
+        return f"组图要求 参考图数 + 生成数 ≤ 15（当前 {n} + {o['group']}）"
+    if o["output_format"] is not None and o["output_format"] not in ("png", "jpeg"):
+        return "output_format 必须为 png 或 jpeg"
+    if fam and o["size"] is not None:
+        allowed = {"2K", "3K", "4K"} if fam == "lite" else {"1K", "1.5K", "2K"}
+        if o["layers"]:
+            allowed.add("auto")
+        size = o["size"]
+        if size not in allowed:
+            dimensions = re.fullmatch(r"([1-9][0-9]*)x([1-9][0-9]*)", size)
+            if not dimensions or o["layers"]:
+                return "所选模型/场景不支持该 size；图层拆分仅支持分辨率档位"
+            width, height = map(int, dimensions.groups())
+            minimum, maximum = (3686400, 16777216) if fam == "lite" else (921600, 4624220)
+            if not minimum <= width * height <= maximum or not 1 / 16 <= width / height <= 16:
+                return "size 超出所选模型的像素总量或宽高比范围"
+    if not o["prompt"] and not o["layers"]:
+        return "缺少提示词（只有图层拆分可以不写）"
+    return None
+
+
+def build_body(o, model, mode="local"):
+    body = {"model": model, "response_format": "url" if mode == "url" else "b64_json",
+            "watermark": o["watermark"]}
+    if o["prompt"]:
+        body["prompt"] = o["prompt"]
+    if o["images"]:
+        imgs = [encode_image(s) for s in o["images"]]
+        body["image"] = imgs[0] if len(imgs) == 1 else imgs
+    if o["size"]:
+        body["size"] = o["size"]
+    if o["output_format"]:
+        body["output_format"] = o["output_format"]
+    if o["transparent"]:
+        body["background"] = "transparent"
+    if o["layers"]:
+        body["layer_decomposition"] = True
+    if o["group"]:
+        body["sequential_image_generation"] = "auto"
+        body["sequential_image_generation_options"] = {"max_images": o["group"]}
+    if o["web_search"]:
+        body["tools"] = [{"type": "web_search"}]
+    if o["fast"]:
+        body["optimize_prompt_options"] = {"mode": "fast"}
+    extra = o.get("parameters")
+    if extra:
+        if not isinstance(extra, dict) or set(extra) & {"model", "response_format"}:
+            raise InputError("parameters 必须是 object，且不能覆盖 model/response_format")
+        merge_parameters(body, extra)
+    return body
+
+
+def post(body, timeout):
+    key = os.environ.get("ARK_API_KEY")
+    if not key:
+        return None, "未设置环境变量 ARK_API_KEY"
+    req = urllib.request.Request(
+        BASE_URL.rstrip("/") + "/images/generations",
+        data=json.dumps(body).encode(),
+        headers={"Content-Type": "application/json", "Authorization": f"Bearer {key}"},
+    )
+    try:
+        with transport.urlopen(req, timeout=timeout) as r:
+            data = json.loads(r.read())
+            if not isinstance(data, dict):
+                return None, "响应状态未知：服务端返回非对象JSON"
+            data.setdefault("request_id", r.headers.get("X-Request-Id"))
+            return data, None
+    except urllib.error.HTTPError as e:
+        raw = e.read().decode(errors="replace")
+        try:
+            err = json.loads(raw).get("error") or {}
+            return None, f"HTTP {e.code} {err.get('code', '')}: {err.get('message', raw)}".strip()
+        except (json.JSONDecodeError, AttributeError):
+            return None, f"HTTP {e.code}: {raw[:500]}"
+    except (urllib.error.URLError, TimeoutError) as e:
+        return None, f"请求失败：{e}"
+    except (OSError, ValueError) as e:
+        return None, f"响应状态未知：{e}"
+
+
+def generate(o, out_dir, timeout=300, mode="local"):
+    """mode=local 下载到 out_dir；mode=url 只返回 24 小时内有效的图片 URL，不落盘。"""
+    model = MODELS.get(o["model"], o["model"])
+    result = {"ok": False, "model": model, "files": [], "layers": [], "usage": None,
+              "errors": [], "error": None, "out_dir": None}
+    try:
+        err = check(o, family(model))
+        body = None if err else build_body(o, model, mode)
+    except InputError as e:
+        err = str(e)
+    if err:
+        result["error"] = err
+        return result
+
+    from .products import STORE
+    job = STORE.create("image", model, out_dir, mode,
+                       summary={"size": o["size"], "group": o["group"], "layers": o["layers"],
+                                "output_format": o["output_format"] or ("png" if o["transparent"] else "jpeg")})
+    with STORE.processing(job):
+        resp, err = post(body, timeout)
+        if err:
+            job.update(error=err, state="failed" if err.startswith(("HTTP 4", "未设置")) else "unknown")
+            STORE.save(job)
+            return STORE.result(job)
+        if resp.get("error"):
+            job.update(state="failed", error=str(resp["error"]))
+            STORE.save(job)
+            return STORE.result(job)
+        STORE.record_response(job, resp)
+        return deliver_image(resp, job)
+
+
+def deliver_image(resp, job):
+    from .products import STORE
+    from .jobs import atomic_bytes
+    errors = []
+    job.update(usage=resp.get("usage"), request_id=resp.get("request_id"), state="generated")
+    STORE.save(job)
+    for i, item in enumerate(resp.get("data") or []):
+        if item.get("error"):
+            errors.append({"index": i, "error": item["error"]})
+            continue
+        z = item.get("z_index")
+        output_format = item.get("output_format")
+        if not output_format:
+            output_format = "png" if isinstance(z, int) and z > 0 else job.get("summary", {}).get("output_format", "jpeg")
+            # Legacy records do not persist output_format; trust actual inline bytes.
+            if item.get("b64_json"):
+                try:
+                    signature = base64.b64decode(item["b64_json"][:16])
+                    if signature.startswith(b"\x89PNG\r\n\x1a\n"):
+                        output_format = "png"
+                    elif signature.startswith(b"\xff\xd8\xff"):
+                        output_format = "jpeg"
+                except ValueError:
+                    pass  # Full base64 validation below records the artifact failure.
+        ext = "jpg" if output_format == "jpeg" else "png"
+        name = f"layer-{z:02d}.{ext}" if isinstance(z, int) else f"image-{i + 1:02d}.{ext}"
+        metadata = {k: item.get(k) for k in ("z_index", "name", "description", "size", "bounding_box")}
+        try:
+            STORE.add(job, name, url=item.get("url"),
+                      data=base64.b64decode(item["b64_json"], validate=True) if item.get("b64_json") else None,
+                      metadata=metadata)
+        except (OSError, ValueError) as exc:
+            errors.append({"index": i, "error": str(exc)})
+    job["result"]["errors"] = errors
+    if not job["artifacts"]:
+        job.update(state="failed", error="没有可交付的图片")
+        STORE.save(job)
+        return STORE.result(job)
+    STORE.deliver(job)
+    layers = [{**a["metadata"], **({"file": a["file"]} if a.get("file") else {"url": a.get("url")})}
+              for a in job["artifacts"] if a.get("metadata", {}).get("z_index") is not None]
+    job["result"]["layers"] = layers
+    if layers and job["mode"] == "local":
+        try:
+            atomic_bytes(Path(job["out_dir"]) / "layers.json", json.dumps(layers, ensure_ascii=False, indent=2).encode())
+        except OSError as exc:
+            job.update(state="download_failed", error=f"图层索引保存失败：{exc}")
+    if errors and job["state"] == "delivered":
+        job.update(state="partial", error="部分图片生成失败；恢复不会重新生成失败项")
+    STORE.save(job)
+    return STORE.result(job)