API 文档中文 Markdown

AI 助手接入(Claude Code / Codex)

在对话中找模型、估价、生成图片、视频和音频,并把结果保存到本地。

AI 助手使用流程

同样的模型,同样的价格;独立预算,随时撤销;超过设定金额先询问。

三步开始

登录接入页创建连接,设置预算、单次预估上限和询问阈值;复制对应助手的命令;重启助手,等待页面显示已连接。

AI 助手接入

以下示例仅适用于主站。租户用户应复制自己站点接入页生成的命令。凭证只显示一次,遗失后请撤销并重新创建。

这里的 MCP 连接让助手调用本站的生成工具,使用 AI 助手凭证。若要让 Codex 直接使用本站的对话模型写代码,请看下文“把本站设为 Codex 的模型服务”,那里使用 API Key。两种凭证不能互换。

Claude Code(Windows PowerShell / macOS / Linux)

claude mcp add --scope user --transport http seedance https://api.deepwhiteai.com/mcp --header "Authorization: Bearer <AGENT_TOKEN>"

运行后重新打开 Claude Code,可用 /mcp 查看连接状态。

Codex(Windows PowerShell)

setx SEEDANCE_AGENT_TOKEN "<AGENT_TOKEN>"
$env:SEEDANCE_AGENT_TOKEN = "<AGENT_TOKEN>"
codex mcp add seedance --url https://api.deepwhiteai.com/mcp --bearer-token-env-var SEEDANCE_AGENT_TOKEN

Codex(macOS / Linux)

export SEEDANCE_AGENT_TOKEN="<AGENT_TOKEN>"
echo 'export SEEDANCE_AGENT_TOKEN="<AGENT_TOKEN>"' >> ~/.zshrc
codex mcp add seedance --url https://api.deepwhiteai.com/mcp --bearer-token-env-var SEEDANCE_AGENT_TOKEN

Bash 用户将 ~/.zshrc 改为 ~/.bashrc。设置后关闭并重新打开终端,再启动 Codex。配置保存在 ~/.codex/config.toml。

claude.ai、Claude Desktop 和 ChatGPT(无需复制凭证)

这些平台通过 OAuth 连接,不需要在接入页创建连接或复制凭证:

  1. 复制服务器地址 https://api.deepwhiteai.com/mcp(租户用户使用自己站点的地址,接入页选择“claude.ai / ChatGPT”即可看到)。
  2. claude.ai 或 Claude Desktop:设置 → 连接器 → 添加自定义连接器,粘贴地址后点击连接。ChatGPT:在开发者模式中添加自定义连接器,填入地址并选择 OAuth 认证。
  3. 平台会打开本站的授权页。登录后设置预算、单次上限、询问阈值和权限,点击“通过”。

本站的 AI 助手授权页:设置预算和权限后通过

通过后,这个连接会出现在接入页的连接列表中,可以像其他连接一样修改预算或撤销。可以只勾选部分权限,例如只读画布。Claude Code 也可以这样连接:添加地址时不带凭证,然后在 /mcp 中选择登录,助手会打开授权页。

推荐安装使用技巧

接入页提供一键复制的下载命令。Claude Code 安装到 ~/.claude/skills/seedance/SKILL.md;Codex 安装到 ~/.agents/skills/seedance/SKILL.md。Skill 会提醒助手先估价、等待确认、上传本地文件并给出结果链接。

能做什么

查找模型和参数、估价、生成图片和视频、生成语音与音乐、查看进度、上传本地文件、导入 HTTPS 素材、下载结果,以及在无限画布上搭建、修改、运行和撤销工作流。claude.ai、Claude Desktop 和 ChatGPT 可以通过 OAuth 直接连接。

让助手搭建和运行无限画布

以前要在画布上一个个添加节点、连线、选模型、点运行。现在可以直接对助手说出想要的流程:助手会创建节点、连好线、选好模型,先报价再运行,并把画布链接交给你。你随时可以在网页上打开同一张画布继续修改。

1. 打开画布权限

创建或编辑连接时,在“高级设置 > 权限”中保留以下三项。新连接默认已勾选;在此之前创建的连接需要编辑后勾选并保存,再重启助手。

接入页高级设置中的三项画布权限

2. 用一句话描述流程

例如:

在我的画布上做一个灯塔分镜:一段文字简介、一张关键帧图片和一段视频镜头。连好线后运行,花费不超过 ¥1。

助手会依次读取画布说明、查询模型参数、创建画布、一次性添加并连接节点、报价、运行并查询结果。下图是一次真实运行的会话记录(已精简),总费用 ¥0.15:

Claude Code 通过 MCP 搭建并运行画布的会话记录

3. 打开画布查看和继续编辑

助手返回的链接就是网页中的同一张画布。下图是上面那次运行的结果:文字简介连到关键帧图片,关键帧再作为视频镜头的输入。

助手搭建并运行后的画布:简介、关键帧图片和视频镜头

好用的提示词

安全与费用

五段示例对话

雨夜海报

用户:生成一张 16:9 的雨夜街景。

助手:先查询可用模型与参数,上传需要的本地文件,再估价。预估费用为 X(示意,实际以工具结果为准),是否确认?

用户:确认。助手:提交生成并查询进度,完成后提供结果链接和网站作品链接。

本地图片做视频

用户:把 ./product.png 做成 5 秒产品旋转视频。

助手:先查询可用模型与参数,上传需要的本地文件,再估价。预估费用为 X(示意,实际以工具结果为准),是否确认?

用户:确认。助手:提交生成并查询进度,完成后提供结果链接和网站作品链接。

批量头像

用户:生成四张风格不同的猫咪头像。

助手:先查询可用模型与参数,上传需要的本地文件,再估价。预估费用为 X(示意,实际以工具结果为准),是否确认?

用户:确认。助手:提交生成并查询进度,完成后提供结果链接和网站作品链接。

音乐

用户:生成一段 30 秒轻快的 lo-fi 音乐。

助手:先查询可用模型与参数,上传需要的本地文件,再估价。预估费用为 X(示意,实际以工具结果为准),是否确认?

用户:确认。助手:提交生成并查询进度,完成后提供结果链接和网站作品链接。

语音

用户:将这段欢迎词变成自然的语音。

助手:先查询可用模型与参数,上传需要的本地文件,再估价。预估费用为 X(示意,实际以工具结果为准),是否确认?

用户:确认。助手:提交生成并查询进度,完成后提供结果链接和网站作品链接。

费用与安全

助手使用网站相同模型和价格。连接预算独立于账户余额,两者都需要足够额度。单次上限和询问阈值作用于预估费用,实际结算可能不同;最终费用以用量记录为准。

不要分享或提交凭证、签名上传链接。怀疑泄露时立即撤销连接;已生成的作品保留。助手必须在收到用户同意后才携带确认凭证重试。

把本站设为 Codex 的模型服务

Codex 可以把本站当作模型服务,用本站的对话模型写代码。这种方式使用 API Key,按日志中的实际用量扣费,与上面的 MCP 连接和 AI 助手凭证无关。

1. 准备 API Key 和模型

在控制台的 API Keys 页面创建一个 API Key。在模型列表中选择一个对话模型,记下完整模型 ID,例如 deepseek/deepseek-v4.1-flash。

如果这个 API Key 开启了“高级设置 > 模型限制”,请把所选模型加入允许列表,或关闭模型限制。否则请求会返回 HTTP 403,提示模型不在该 API Key 的允许列表中。

2. 设置 API Key 环境变量

Windows PowerShell:

setx SEEDANCE_API_KEY "<API Key>"
$env:SEEDANCE_API_KEY = "<API Key>"

macOS / Linux:

export SEEDANCE_API_KEY="<API Key>"
echo 'export SEEDANCE_API_KEY="<API Key>"' >> ~/.zshrc

Bash 用户将 ~/.zshrc 改为 ~/.bashrc。设置后关闭并重新打开终端。

3. 编辑 Codex 配置文件

在用户目录的 Codex 配置文件中加入以下内容。macOS / Linux 为 ~/.codex/config.toml,Windows 为 %USERPROFILE%\.codex\config.toml。项目目录内的 .codex/config.toml 不能设置模型服务。

model = "deepseek/deepseek-v4.1-flash"
model_provider = "seedance"

[model_providers.seedance]
name = "Seedance"
base_url = "https://api.deepwhiteai.com/v1"
env_key = "SEEDANCE_API_KEY"
wire_api = "responses"

保存后重新启动 Codex。

4. 确认连接

在 Codex 中发送一条简单消息。随后在控制台的使用日志中应看到该模型的记录,请求路径为 /v1/responses。

排查

常见问题

为什么需要重启助手?

助手会从启动环境读取服务器地址和凭证。

在哪里查看生成结果?

助手会返回结果链接和网页地址;同一条记录也会出现在生成记录中。

为什么助手看不到工具?

重启助手,并确认凭证和服务器地址属于本站。

凭证无效时该怎么办?

如果凭证复制不完整、已撤销、已过期或是在其他站点创建,请重新创建连接。

预算不足时该怎么办?

提高此连接的预算,并确认账户余额足以支付请求。

confirmation_required 是什么意思?

预估价格超过了你的确认阈值。确认费用后,再让助手重试。

为什么预估价格可能和最终扣费不同?

部分模型按实际用量结算。使用日志中的最终扣费为准。

如何上传本地图片?

告诉助手本地文件路径,它会在请求前上传文件。

可以在公司网络或代理下使用吗?

助手必须能通过 HTTPS 访问本站,包括服务和上传地址。

这个连接安全吗?

每个连接都有独立预算和限制。凭证泄露后请立即撤销。

助手改坏了画布怎么办?

让助手撤销刚才的修改即可;它会用该次修改的批次 ID 恢复。若之后你又改过相关节点,撤销会被拒绝,请在网页中手动调整。

我在网页上编辑时,助手也在改同一张画布,会互相覆盖吗?

不会。修改同一个节点时,后提交的一方会因版本号不一致被拒绝。助手需要重新读取后再修改;网页修改后刷新即可看到助手的结果。

为什么助手看不到画布工具?

确认连接勾选了画布权限,保存后重启助手。

可以使用 Claude Desktop 或 claude.ai 吗?

可以。把 https://api.deepwhiteai.com/mcp 添加为自定义连接器,在本站的授权页设置预算和权限即可,无需复制凭证。ChatGPT 的自定义连接器同样适用。见上文“claude.ai、Claude Desktop 和 ChatGPT”。

开发者信息

MCP: https://api.deepwhiteai.com/mcp
Authorization: Bearer <AGENT_TOKEN>

OAuth 客户端(遵循 MCP 授权规范):

Protected resource metadata: https://api.deepwhiteai.com/.well-known/oauth-protected-resource/mcp
Authorization server metadata: https://api.deepwhiteai.com/.well-known/oauth-authorization-server
Dynamic client registration: POST https://api.deepwhiteai.com/api/agent/v1/oauth/register
Authorization: https://api.deepwhiteai.com/agent-authorize(授权码 + PKCE S256,resource=https://api.deepwhiteai.com/mcp)
Token: POST https://api.deepwhiteai.com/api/agent/v1/oauth/token

访问令牌有效期 1 小时,刷新令牌每次使用后轮换;重复使用旧的刷新令牌会使该连接的全部令牌失效。未携带凭证访问 /mcp 时返回 401,WWW-Authenticate 头中给出 resource_metadata 地址。

工具与主要参数

get_account {}
list_models {kind, query, limit}
get_model_schema {model}
estimate_cost {model, prompt, params, inputs, count}
generate_image / generate_video / generate_audio
  {model, prompt, params, inputs, count, max_cost, idempotency_key, confirm_token}
get_task {task_id, wait_seconds}
list_tasks {limit}
create_upload {filename, content_type, size_bytes}
import_media_url {url, kind}

get_canvas_guide {}
list_canvases {limit, offset}
list_canvas_models {kind, query, limit}
get_canvas_outline {canvas_id, offset, limit}
get_canvas_nodes {canvas_id, node_ids}
create_canvas {name}
apply_canvas_changes {canvas_id, operations, summary, idempotency_key}
  operations: add_node / update_node / delete_node / connect / disconnect
list_canvas_changes {canvas_id, limit}
undo_canvas_changes {canvas_id, batch_id}
quote_canvas_run {canvas_id, node_ids, mode, max_cost}
start_canvas_run {quote_id, idempotency_key, max_cost, confirm_token}
get_canvas_run {run_id, wait_seconds}

画布工具需要 canvas:read、canvas:write 或 canvas:run 权限。修改和删除节点必须带上最近读取的 base_revision,版本不一致时返回 status: conflict 且不写入。新节点可用 ref 临时命名并在同一次调用中连线,省略 x、y 时由服务器自动排版。报价 5 分钟内有效;运行开始后用 get_canvas_run 轮询,每次最多等待 25 秒。

完整参数以 tools/list 返回的 JSON Schema 为准。估价后提交生成会立即返回持久任务 ID;调用 get_task,wait_seconds 最大为 50,任务成功、失败或未知时停止轮询。重试同一请求必须使用同一个 idempotency_key;unknown 表示上游结果不确定,不要自动重新生成。