静觅 崔庆才的个人站点 - Python爬虫教程

📘 总览指南：在 Claude 里用全部 11 个 AceData Cloud MCP →

Seedream 是字节跳动开源的图像生成模型，对中文 prompt 友好、写实和艺术风格都强、出图速度快，特别适合做插画、概念图、海报。挂上 MCP，Claude 在聊天框里随手一句 prompt，十几秒就把图丢回来。

本文是一篇亲手在 Claude.ai 网页版跑通的实测记录：从添加 Connector、OAuth 授权，到一句 prompt 生成 16:9 水彩风凤凰图，全程截图，复制即可复现。

什么是 MCP？

MCP（Model Context Protocol）是 Anthropic 推出的开放协议，让 Claude 这类模型可以通过标准接口调用外部工具。简单理解：给 Claude 装上插件能力。

AceData Cloud 把 Seedream 的核心能力封装成了一个远程 MCP Server，挂上去之后 Claude 就能直接：

• 从文字描述生成图（seedream_generate_image）
• 用图改图 / 局部修改（seedream_edit_image）
• 查询单个任务（seedream_get_task）
• 批量查询任务（seedream_get_tasks_batch）
• 列出可用模型（seedream_list_models）
• 列出可用图片尺寸（seedream_list_sizes）

整套接入只需一个 URL，剩下交给 Claude。

在 Claude.ai 网页版添加 Seedream MCP

💡 Claude.ai 网页版接入是 OAuth 直连，不需要复制 API Token。你只需要一个能登录 AceData Cloud 的账号（GitHub / Google / 微信均可）。

1. 打开 Connectors 设置

登录 https://claude.ai，点左下角头像 → Settings → Customize → Connectors，或直接访问 https://claude.ai/customize/connectors。

⚠️ 旧入口 /settings/connectors 已经迁移到 /customize/connectors，访问旧地址会看到一条 “Connectors have moved to Customize” 的提示。

2. 添加 Seedream MCP Server

点击右上角加号 → Add custom connector，在弹出对话框里填：

点 Add，Claude 会自动发现 Server 暴露的全部工具。

3. OAuth 授权

点 Connect → 跳转到 AceData Cloud OAuth 授权页 → 用账号登录、点 Allow 即可。如果还没注册，先去 https://platform.acedata.cloud 注册一下，注册即送免费额度，足够你跑完本文的 demo。

4. 检查工具列表 & 把工具切到 Always allow

授权完成后回到 Claude.ai，点开 Seedream Connector，能看到 6 个工具：seedream_generate_image、seedream_edit_image、seedream_get_task、seedream_get_tasks_batch、seedream_list_models、seedream_list_sizes。

⚙️ 强烈建议把右上角的 Needs approval 下拉切换到 Always allow，否则每次工具调用都会弹确认框。生成一张图通常会触发 2–4 次工具调用（提交 + 多次查询状态），点确认到怀疑人生。

实测：一句英文 Prompt 出图

下面是我真实跑出来的对话：

Prompt: Use Seedream to generate one image: a majestic phoenix rising from cherry blossoms, watercolor painting style, soft pink and gold palette, 16:9.

Claude 收到后做的事情：

1. 自动调用 seedream_generate_image，带上 prompt 和 16:9 比例
2. 拿到 task id，自己开始轮询 seedream_get_task
3. 约 20–40 秒后拿到最终图片（2848×1600）
4. 把图片链接 + 文字总结一次性贴回聊天框，附带 “需要换风格 / 调整构图吗？” 的后续提示

下面是聊天最终结果截图：

实际生成的最终图（直接落到 platform.cdn.acedata.cloud，长期可用）：

💡 图片链接是稳定的：AceData Cloud 把 Seedream 出来的图直接搬到自己的 CDN（platform.cdn.acedata.cloud/seedream/<id>.jpg），不像直连上游 CDN 那样会过期。Claude 返回的链接可以直接贴到博客、PPT、设计稿里。

更多玩法（同样一个 Connector）

把 prompt 换成下面这些，Claude 会自动选合适的工具：

先查可用尺寸再出图

1

List Seedream sizes first, then generate a 9:16 vertical poster of a Tokyo neon alley at midnight.

→ Claude 先调 seedream_list_sizes 拿合法的尺寸列表，再用 seedream_generate_image 出图。

改图 / 局部修改

1

Take that phoenix image and add a giant full moon in the background.

→ Claude 调用 seedream_edit_image，传入上一张图的 URL 做编辑。

中文 prompt 直出

1

用 Seedream 生成一张图：江南雨夜的撑伞女子，水墨画风格，背景留白，9:16。

→ Seedream 对中文 prompt 的理解非常稳，Claude 会原样传入。

批量生成多张候选

1

Generate 4 variations of "cyberpunk Shanghai bund at rainy night", each in a different mood.

→ Claude 顺序调用 4 次 generate，最后用 seedream_get_tasks_batch 一次性拉回结果。

常见问题

Q：为什么我点了 Always allow，新工具还是要确认？
A：Always allow 是按工具粒度记忆的。Generate、Edit、Get Task、Get Tasks Batch、List Models、List Sizes 是 6 个不同工具，第一次各确认一次即可。

Q：余额不够怎么办？
A：错误信息里会带 insufficient balance。去 https://platform.acedata.cloud/console/coin 充值，支持支付宝 / 微信 / Stripe / USDC。生成一张 Seedream 图通常消耗几个 credit，新账号免费额度足够测十几次。

Q：和 Midjourney / NanoBanana 比有什么优势？
A：Seedream 的中文 prompt 跟随度优于 Midjourney；艺术质感优于 NanoBanana；定价介于二者之间。做中文海报、插画、运营图建议优先 Seedream。

Q：可以和别的 MCP 一起用吗？
A：可以。Claude.ai 支持多 Connector 并存。一句 “用 Seedream 出一张水墨江南，然后用 Suno 写一首匹配氛围的古风曲” 就能让 Claude 自己编排图像 + 音乐流水线。完整列表见 Claude × 11 个 MCP 总览。

Q：Claude Desktop 和 Claude Code 也能这么用吗？
A：能。详见 Claude Desktop + Seedream MCP 和 Claude Code + Seedream MCP。

相关链接

• Seedream MCP Server URL
• Seedream MCP GitHub
• Seedream MCP PyPI
• AceData Cloud 平台
• MCP 协议官网

MCP（Model Context Protocol） 是由 Anthropic 推出的模型上下文协议，允许 AI 模型（如 Claude、GPT 等）通过标准化接口调用外部工具。通过 AceData Cloud 提供的 Nano Banana MCP Server，你可以在 Claude Desktop、VS Code、Cursor 等 AI 客户端中直接生成和编辑 AI 图像。

功能概览

Nano Banana MCP Server 提供以下核心功能：

• 图像生成 — 通过文本提示词生成高质量图像
• 图像编辑 — 修改已有图像或组合多张图像
• 虚拟试衣 — 将服装穿戴到人物照片上
• 产品植入 — 将产品置于真实场景中
• 多模型支持 — 支持 nano-banana、nano-banana-2 和 nano-banana-pro 模型
• 任务查询 — 监控生成进度并获取结果

前置准备

使用前，你需要获取 AceData Cloud API Token：

1. 注册或登录 AceData Cloud 平台
2. 前往 Nano Banana Images API 页面
3. 点击「Acquire」获取 API Token（首次申请赠送免费额度）

方式一：使用托管 MCP Server（推荐，零安装）

AceData Cloud 已经把 Nano Banana MCP Server 托管在云端，无需本地安装任何依赖，直接在 AI 客户端里填写下面这个 URL 就能用：

1

https://nanobanana.mcp.acedata.cloud/mcp

认证方式：在请求头中加上 Authorization: Bearer 你的API Token 即可（Claude.ai 通过 OAuth 自动完成，无需手动填 Token）。

Claude.ai（网页版，OAuth 登录，最简单）

1. 打开 Claude.ai → 左下角 Customize → Connectors → Add More
2. 在 URL 处填入：https://nanobanana.mcp.acedata.cloud/mcp
3. 完成 OAuth 授权登录（自动跳转 AceData Cloud 登录页）
4. 回到对话界面，工具即可使用

Claude Desktop

编辑配置文件：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

1
2
3
4
5
6
7
8
9
10
11

{
  "mcpServers": {
    "nanobanana": {
      "type": "http",
      "url": "https://nanobanana.mcp.acedata.cloud/mcp",
      "headers": {
        "Authorization": "Bearer 你的API Token"
      }
    }
  }
}

保存后重启 Claude Desktop 即可生效。

Claude Code（终端命令行）

1
2

claude mcp add nanobanana --transport http https://nanobanana.mcp.acedata.cloud/mcp \
  -H "Authorization: Bearer 你的API Token"

VS Code（GitHub Copilot）

在项目根目录创建 .vscode/mcp.json：

1
2
3
4
5
6
7
8
9
10
11

{
  "servers": {
    "nanobanana": {
      "type": "http",
      "url": "https://nanobanana.mcp.acedata.cloud/mcp",
      "headers": {
        "Authorization": "Bearer 你的API Token"
      }
    }
  }
}

Cursor

在项目根目录创建 .cursor/mcp.json：

1
2
3
4
5
6
7
8
9
10

{
  "mcpServers": {
    "nanobanana": {
      "url": "https://nanobanana.mcp.acedata.cloud/mcp",
      "headers": {
        "Authorization": "Bearer 你的API Token"
      }
    }
  }
}

其他支持 MCP 的客户端

任何支持 MCP Streamable HTTP 协议的客户端（Windsurf、Cline、ChatGPT Connectors、Gemini CLI、JetBrains AI Assistant 等）都可以通过填写以下两项接入：

• URL：https://nanobanana.mcp.acedata.cloud/mcp
• Header：Authorization: Bearer 你的API Token

方式二：本地运行（pip / uvx 安装）

如果你需要离线运行、自定义代码或部署到内网，可以把 MCP Server 安装在本地通过 stdio 启动。

安装

pip 安装（推荐）：

1

pip install mcp-nanobanana-pro

或源码安装：

1
2
3

git clone https://github.com/AceDataCloud/NanoBananaMCP.git
cd NanoBananaMCP
pip install -e .

安装完成后，即可使用 mcp-nanobanana-pro 命令启动服务。

在 Claude Desktop 中使用（本地）

编辑 Claude Desktop 配置文件：

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

添加以下配置：

1
2
3
4
5
6
7
8
9
10

{
  "mcpServers": {
    "nanobanana": {
      "command": "mcp-nanobanana-pro",
      "env": {
        "ACEDATACLOUD_API_TOKEN": "你的API Token"
      }
    }
  }
}

如果使用 uvx（无需提前安装包）：

1
2
3
4
5
6
7
8
9
10
11

{
  "mcpServers": {
    "nanobanana": {
      "command": "uvx",
      "args": ["mcp-nanobanana-pro"],
      "env": {
        "ACEDATACLOUD_API_TOKEN": "你的API Token"
      }
    }
  }
}

保存配置后重启 Claude Desktop 即可生效。

在 VS Code / Cursor 中使用（本地）

在项目根目录创建 .vscode/mcp.json：

1
2
3
4
5
6
7
8
9
10

{
  "servers": {
    "nanobanana": {
      "command": "mcp-nanobanana-pro",
      "env": {
        "ACEDATACLOUD_API_TOKEN": "你的API Token"
      }
    }
  }
}

或者使用 uvx：

1
2
3
4
5
6
7
8
9
10
11

{
  "servers": {
    "nanobanana": {
      "command": "uvx",
      "args": ["mcp-nanobanana-pro"],
      "env": {
        "ACEDATACLOUD_API_TOKEN": "你的API Token"
      }
    }
  }
}

可用工具列表

使用示例

配置完成后，你可以在 AI 客户端中直接用自然语言调用这些功能，例如：

• 「帮我生成一张水彩风格的山水画」
• 「把这件衣服 PS 到这个人身上」
• 「将这个产品放到一个咖啡厅场景中」
• 「用 nano-banana-pro 模型生成一张高质量人像」

更多信息

• GitHub 仓库：AceDataCloud/NanoBananaMCP
• PyPI 包：mcp-nanobanana-pro
• API 文档：Nano Banana API

本文将介绍一种 人脸美颜 API 对接说明，它可以通过用户上传一张人脸图片（最多能处理一张图片中最大的五张人脸信息），精准定位五官，实现美肤、亮肤、祛痘等美颜功能。

申请流程

要使用 人脸美颜 API，首先到 Ace Data Cloud 控制台 获取您的 API Token，留作备用。

如果你尚未登录或注册，会自动跳转到登录页面邀请你注册和登录，完成后会自动返回当前页面。

一个 API Token 即可调用平台所有服务，无需为每个服务单独申请。 首次申请会赠送免费额度，可免费体验；额度不足时可在 控制台 充值通用余额。

📘 完整文档：人脸美颜 API →

基本使用

首先先了解下基本的使用方式，就是输入图片链接以及美颜信息，便可获得处理后结果图片，首先需要简单地传递一个 image_url 字段，人脸图片如下图所示：

然后我们还需上传关于人脸美颜信息参数，具体的见下面的请求体信息。我们接下来就可以在界面上填写对应的内容，如图所示：

可以看到这里我们设置了 Request Headers，包括：

• accept：想要接收怎样格式的响应结果，这里填写为 application/json，即 JSON 格式。
• authorization：调用 API 的密钥，申请之后可以直接下拉选择。

另外设置了 Request Body，包括：

• image_url：需要处理的人脸图片链接。
• smoothing：磨皮程度，取值范围[0,100]。0不磨皮，100代表最高程度。默认值10。
• whitening：美白程度，取值范围[0,100]。0不美白，100代表最高程度。默认值30。
• face_lifting：瘦脸程度，取值范围[0,100]。0不瘦脸，100代表最高程度。默认值70。
• eye_enlarging：大眼程度，取值范围[0,100]。0不大眼，100代表最高程度。默认值70。

选择之后，可以发现右侧也生成了对应代码，如图所示：

点击「Try」按钮即可进行测试，如上图所示，这里我们就得到了如下结果：

1
2
3

{
  "image_url": "https://faceeffect-1254418846.cos.ap-guangzhou.myqcloud.com/fmu/BeautifyPic/1256437459/1a68c13b-b03c-4c7b-92a1-e4a9b5f1d7ec"
}

可以看到，这里返回的结果中有一个 image_url 字段，就是根据输入美颜变化后的人脸图片。其中变化后人脸信息如下所示：

</p >

可以看到图片中人脸是根据输入的美颜信息发生了变化。

另外如果想生成对应的对接代码，可以直接复制生成，例如 CURL 的代码如下：

1
2
3
4
5
6
7
8
9
10
11

curl -X POST 'https://api.acedata.cloud/face/beautify' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "image_url": "https://cdn.acedata.cloud/lrbtcn.jpg",
  "smoothing": 50,
  "whitening": 50,
  "face_lifting": 50,
  "eye_enlarging": 50
}'

Python 的对接代码如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

import requests

url = "https://api.acedata.cloud/face/beautify"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "image_url": "https://cdn.acedata.cloud/lrbtcn.jpg",
    "smoothing": 50,
    "whitening": 50,
    "face_lifting": 50,
    "eye_enlarging": 50
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

错误处理

在调用 API 时，如果遇到错误，API 会返回相应的错误代码和信息。例如：

• 400 token_mismatched：Bad request, possibly due to missing or invalid parameters.
• 400 api_not_implemented：Bad request, possibly due to missing or invalid parameters.
• 401 invalid_token：Unauthorized, invalid or missing authorization token.
• 429 too_many_requests：Too many requests, you have exceeded the rate limit.
• 500 api_error：Internal server error, something went wrong on the server.

错误响应示例

1
2
3
4
5
6
7
8

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

结论

通过本文档，您已经了解了如何使用 人脸美颜 API 对用户上传的一张人脸图片（最多能处理一张图片中最大的五张人脸信息），精准定位五官，实现美肤、亮肤、祛痘等美颜功能。希望本文档能帮助您更好地对接和使用该 API。如有任何问题，请随时联系我们的技术支持团队。

Maestro 是一个 Agent 原生的视频生产接口：你用一句自然语言 prompt 描述想要的视频（可选地用 file_urls 附上参考图片 / 视频 / 音频），一个无头的「AI 导演」会自动完成选题、写脚本、生成画面、配音、配乐、合成与渲染，最终产出带字幕的成片并上传 CDN。

本文将详细介绍 Maestro 视频生成 API 的对接说明，帮助您快速集成并充分利用该 API 的能力。

这是一个异步任务接口：提交后会立即返回 task_id，随后通过 Maestro 任务查询 API（POST /maestro/tasks）轮询获取结果（轮询免费不计费）。要在已有视频上继续迭代，可使用 action: remix / edit / extend 配合 ref_task_id。

申请流程

要使用 Maestro 视频生成 API，首先到 Ace Data Cloud 控制台 获取您的 API Token，留作备用。

如果你尚未登录或注册，会自动跳转到登录页面邀请你注册和登录，完成后会自动返回当前页面。

一个 API Token 即可调用平台所有服务，无需为每个服务单独申请。 首次申请会赠送免费额度，可免费体验；额度不足时可在 控制台 充值通用余额。

📘 完整文档：Maestro 视频生成 API →

基本使用

POST https://api.acedata.cloud/maestro/videos

最基础的用法只需要传入一个自然语言 prompt，AI 导演会自动决定脚本、画面、配音与剪辑。这里我们先了解下需要设置的请求头与请求体。

Request Headers 包括：

• accept：想要接收怎样格式的响应结果，这里填写为 application/json，即 JSON 格式。
• authorization：调用 API 的密钥，申请之后可以直接下拉选择。
• content-type：请求体的格式，这里填写为 application/json。

Request Body 主要包括：

• prompt：用自然语言描述要做的视频（主题、要展示什么、风格、受众）。
• langs：输出语言数组，如 ["zh-cn", "en"]，默认 ["zh-cn"]。
• aspect：画面比例，9:16（默认）/ 16:9 / 1:1。
• duration：目标时长（秒），默认 30。

请求体的全部字段如下表所示：

下面通过一个具体示例来演示。假设我们要生成一条中英双语、竖屏、20 秒的科普短视频，对应的 CURL 代码如下：

1
2
3
4
5
6
7
8
9
10

curl -X POST 'https://api.acedata.cloud/maestro/videos' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "prompt": "用 20 秒讲清楚什么是向量数据库，适合零基础观众，结尾给一句记忆点",
  "langs": ["zh-cn", "en"],
  "aspect": "9:16",
  "duration": 20
}'

对应的 Python 代码如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

import requests

url = "https://api.acedata.cloud/maestro/videos"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "prompt": "用 20 秒讲清楚什么是向量数据库，适合零基础观众，结尾给一句记忆点",
    "langs": ["zh-cn", "en"],
    "aspect": "9:16",
    "duration": 20
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

点击运行，可以发现会立即得到一个结果，如下：

1
2
3
4
5

{
  "success": true,
  "task_id": "f57e99c4f60f4373a15517742ce2357d",
  "trace_id": "70e1cb12-c619-4292-a416-90191205996b"
}

返回结果的字段介绍如下：

• success：此次任务是否成功提交。
• task_id：此次视频生成任务的 ID，后续用它去 Maestro 任务查询 API 轮询结果。
• trace_id：本次请求的追踪 ID，遇到问题时可提供给技术支持定位。

由于视频生产耗时较长，接口在此立即返回 task_id，并不会等到视频渲染完成。接下来需要用 task_id 去轮询结果，详见「取结果」一节。

指定视频类型与风格（scenario / style）

不传 scenario 时由 AI 自动判断（等于 auto）；想把视频钉到某种类型就显式传。例如做一条竖屏短剧，可以指定如下内容：

• scenario：视频类型，这里设为 drama（角色 + 对白的短剧）。
• style：视觉风格，这里设为 cinematic（电影质感）。

填写样例的 CURL 代码如下：

1
2
3
4
5
6
7
8
9
10
11

curl -X POST 'https://api.acedata.cloud/maestro/videos' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "prompt": "两个合租室友因为一只猫闹翻又和好，三幕反转，结尾温暖",
  "scenario": "drama",
  "style": "cinematic",
  "aspect": "9:16",
  "duration": 40
}'

常见的搭配方式：

• 短剧：scenario: "drama"（角色 + 对白）。
• 数字人 / 口播：scenario: "avatar"，并用 file_urls 传一张人像。
• 动感字幕 / 数据动画：scenario: "motion"；演示 / 路演：scenario: "slideshow"。
• style 是视觉风格预设（如 modern / neon / luxury），不改变类型、只影响观感。
• voice 用来指定旁白音色（如 warm-female / deep-male），与语言无关、跨语言通用。

返回结果与「基本使用」一致，同样是立即返回 task_id。

多语言输出

在 langs 中传入多个语言即可一次产出多语言版本。第一个为主语言，之后每多一种语言会复用同一套画面，只额外配音 + 渲染，因此每多一种语言仅 +6 积分。示例：

1
2
3
4
5
6
7
8
9
10

curl -X POST 'https://api.acedata.cloud/maestro/videos' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "prompt": "介绍我们的智能客服产品，突出 3 个核心卖点",
  "langs": ["zh-cn", "en", "ja"],
  "aspect": "16:9",
  "duration": 30
}'

任务完成后，每种语言会对应结果里的一个 variant（见 Maestro 任务查询 API）。

在已有视频上迭代（remix / edit / extend）

传入 action 与上一次任务的 ref_task_id，即可在原项目基础上做差量修改（如「把第 2 幕标题改掉」「换个配音」「整体调暗」）。小改动很快、大改动会重做：

1
2
3
4
5
6
7
8
9

curl -X POST 'https://api.acedata.cloud/maestro/videos' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "action": "remix",
  "ref_task_id": "f57e99c4f60f4373a15517742ce2357d",
  "prompt": "把开场标题换成更有冲击力的一句，整体配色更暗一些"
}'

• remix：在原视频结构上重新演绎（保留主题，调整表现）。
• edit：对指定局部做精修（如换标题、换配音、调色）。
• extend：在原视频基础上延展内容。

返回结果同样是立即返回一个新的 task_id，用它轮询即可拿到迭代后的成片。

取结果

由于视频生产耗时较长，本接口在提交后立即返回 task_id，你需要用它去 Maestro 任务查询 API 轮询结果：

1
2
3
4
5
6
7

curl -X POST 'https://api.acedata.cloud/maestro/tasks' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "id": "f57e99c4f60f4373a15517742ce2357d"
}'

任务完成时会返回成片信息（每种语言对应一个 variant）。status 会经历 pending → planning → producing → succeeded（或 failed），轮询免费、不消耗积分。完整的响应格式与历史列表查询请参考 Maestro 任务查询 API 对接说明。

计费

任务完成后按实际成片计费，失败的任务不扣费。 计费以实际交付的成片时长与实际产出的语言数为准——例如请求 600 秒但最终成片 50 秒，只按约 50 秒计费；某个语言最终没有产出时，也不会收取该语言的 +6 加价。提交任务本身不单独计费（结果由 /maestro/tasks 免费轮询）。

单个成片的积分大致按下式估算：

1

积分 ≈ 0.85 × 成片时长秒 × 质量倍率 × 场景倍率 + 6 × max(语言数 − 1, 0)

• 质量倍率：draft 0.5× / standard 1×（默认）/ premium 2×。
• 场景倍率：drama 1.35× / avatar 1.15× / 其他 1×。

以标准档、非短剧 / 数字人、单语言为例，不同成片时长对应的积分约为：

错误处理

在调用 API 时，如果遇到错误，API 会返回相应的错误代码和信息。例如：

• 400 invalid_request：Bad request, possibly due to a missing prompt or invalid parameters.
• 401 invalid_token：Unauthorized, invalid or missing authorization token.
• 403 forbidden：Forbidden, insufficient balance or access.
• 429 too_many_requests：Too many requests, you have exceeded the rate limit.
• 500 api_error：Internal server error, something went wrong on the server.

错误响应示例

1
2
3
4
5
6
7
8

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

结论

通过本文档，您已经了解了如何使用 Maestro 视频生成 API：只需一句自然语言 prompt，即可自动完成脚本、素材、配音、配乐、剪辑、字幕与成片渲染，并支持指定视频类型、风格、音色、多语言输出以及在已有视频上迭代。希望本文档能帮助您更好地对接和使用该 API。如有任何问题，请随时联系我们的技术支持团队。

相关接口

• Maestro 任务查询 API 对接说明：用 POST /maestro/videos 返回的 task_id 查询任务状态与结果，或拉取历史任务列表（轮询免费）。

📘 Overview：OpenCode MCP Overview →

Black Forest Labs 出品的 Flux 系列是当前写实风格表现最强、图片编辑能力（Kontext）最方便的开源图像模型之一。在 OpenCode 里接上 Flux MCP Server 之后，可以直接让 AI 根据当前对话上下文生成或编辑图片，适合做商用素材和高保真插画。

Flux MCP 适合做产品 hero 图、写实人像、商业广告素材，以及通过 Kontext 模型做“按文字描述编辑现有图片”——比如换背景、换风格、改字。

获取 API Token

使用 Flux MCP Server 之前，需要先准备一个 Ace Data Cloud API Token。OpenCode 和 Claude Code 共用一套 Token，获取流程一样：

1. 打开 Ace Data Cloud 控制台 - 应用列表，获取您的 API Token，留作备用。
2. 如果你尚未登录或注册，会自动跳转到登录页面；登录注册之后会自动返回当前页面。
3. 首次申请时会有免费额度赠送，可以先免费体验 Flux MCP 服务。

一个 Token 可以使用 AceData Cloud 提供的全部 11 个 MCP Server，无需为 Flux 单独申请。文档和截图里建议只展示脱敏形式，例如 3b78cc40dd3b43db806a4300....，不要把完整 Token 贴到公开仓库、Issue、截图或聊天记录里。

想用 Claude Desktop / Claude.ai 网页版直接 OAuth 一键授权？请看 Flux MCP 的 Claude.ai / Desktop 教程。

配置 OpenCode

OpenCode 用一份 opencode.json 描述所有 MCP Server，文件可以放在两处，按下面”作用范围”选一种即可。两种位置的字段结构完全相同，区别只是优先级。

强烈推荐先把 Token 写到环境变量里：

1

export ACEDATACLOUD_API_KEY="替换为你的真实 Token"

然后在 opencode.json 里用 {env:ACEDATACLOUD_API_KEY} 占位符引用，避免真实 Token 写进文件。

全局：所有项目共用

文件位置：~/.config/opencode/opencode.json，适合”我自己的机器，一次配好，所有项目都能用”。

1
2
3
4
5
6
7
8
9
10
11
12

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "flux": {
      "type": "remote",
      "url": "https://flux.mcp.acedata.cloud/mcp",
      "enabled": true,
      "oauth": false,
      "headers": { "Authorization": "Bearer {env:ACEDATACLOUD_API_KEY}" }
    }
  }
}

⚠️ "oauth": false 不可省略。AceData 的 MCP Server 使用 Bearer Token 鉴权，不走 OAuth 流程；OpenCode 默认会把 401 当成 OAuth 挑战自动重定向，导致 opencode mcp list 出现 SSE error: Non-200 status code (401)。显式声明 "oauth": false 让 OpenCode 直接以 Authorization: Bearer ... 调用，opencode mcp debug flux 也会回显 OAuth explicitly disabled，代表生效。

项目级：仅当前项目生效

文件位置：当前项目根目录下的 opencode.json，会覆盖全局配置。适合团队共享、单仓库定制，或者只在某个项目里临时启用某个 MCP。

1
2
3
4
5
6
7
8
9
10
11
12

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "flux": {
      "type": "remote",
      "url": "https://flux.mcp.acedata.cloud/mcp",
      "enabled": true,
      "oauth": false,
      "headers": { "Authorization": "Bearer {env:ACEDATACLOUD_API_KEY}" }
    }
  }
}

如果项目级 opencode.json 会被提交到 Git，请确保用 {env:ACEDATACLOUD_API_KEY} 占位符而不是真实 Token，避免泄露。

💡 如果 Shell 里的 .env 没有显式 export，需要用 set -a && source .env && set +a 才能把变量传给 OpenCode 进程，否则 opencode debug config 会显示 "Authorization": "Bearer "（占位符没解析）。

真实运行结果

下面是在 OpenCode 1.15.13 里用隔离临时目录实际执行后的脱敏输出。命令使用真实 AceData Cloud Token，输出中的 Token 已替换成 357265014ad145fc8ab2....，临时配置已删除。

1
2
3
4
5
6
7
8
9
10
11

$ opencode --version
1.15.13

$ opencode mcp list

┌  MCP Servers
│
●  ✓ flux connected
│      https://flux.mcp.acedata.cloud/mcp
│
└  1 server(s)

看到 ✓ flux connected 就说明 Flux MCP 已经接入成功。如果显示 ✗ 或者 unauthorized，请检查 ACEDATACLOUD_API_KEY 是否设置、Token 是否复制完整、Authorization 前缀是否为 Bearer（注意大小写和空格）。

如需调试某一台 MCP 的连接细节：

1

opencode mcp debug flux

实际握手成功后，OpenCode 的 INFO 日志会输出 service=mcp key=flux transport=StreamableHTTP connected 和 service=mcp key=flux toolCount=6 两行（实测 6 个工具），代表 Flux MCP 已经准备好被模型调用。

🤖 选模型的实测建议：在 OpenCode 里要真正让模型主动调用 Flux MCP，请优先使用 OpenAI 系列模型（如 acedatacloud/gpt-5-mini、acedatacloud/gpt-5）。AceData 上 Claude 系列模型通过 OpenAI 兼容接口暴露时，工具调用经常返回 Improperly formed request（实测：acedatacloud/claude-haiku-4-5-20251001、acedatacloud/claude-sonnet-4-6 在挂载多个 MCP 时均报这个错）。只做对话不调用工具时，Claude 模型可以正常使用。

典型场景

配置完成后，直接在 OpenCode 会话里用自然语言即可调用，无需先切到 /mcp：

快速出图

1

用 Flux 生成一张赛博朋克风格的城市夜景，霓虹灯、雨夜、湿润街道

Kontext 编辑现有图

1

把这张图（链接 xxx）改成水彩画风格

生成产品 hero 图

1

生成一张 1024x1024 的产品 hero 图：黑色金属质感的耳机悬浮在白色背景

工具列表

下表列出主要工具（Flux MCP Server 实测共暴露 6 个工具，可通过 curl -X POST https://flux.mcp.acedata.cloud/mcp -H 'Authorization: Bearer <token>' -H 'Accept: application/json' -H 'Content-Type: application/json' --data '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' 获取完整清单）：

相关链接

• Flux MCP Server（GitHub）
• Claude + Flux MCP 图文教程（claude.ai / Desktop）
• OpenCode MCP Overview
• OpenCode 终端配置教程
• MCP 协议官网

github.com/AceDataCloud/SDK/go 是 Ace Data Cloud 官方 Go SDK，把 api.acedata.cloud 上的 chat completions / images / video / music / search 封装成 client.OpenAI().Chat().Completions().Create(...) 风格的方法链，自带 SSE 流式（基于 channel）、自动重试退避和类型化错误。

风格上对齐 context.Context + functional options，适合放进任何 Go 后端服务或 CLI。

源码与文档：

• SDK 仓库：https://github.com/AceDataCloud/SDK
• Go 模块：https://pkg.go.dev/github.com/AceDataCloud/SDK/go

安装

1

go get github.com/AceDataCloud/SDK/go

干净 Go 模块的版本检查输出：

1
2

$ go list -m github.com/AceDataCloud/SDK/go
github.com/AceDataCloud/SDK/go v0.0.0-20260505072132-4a3d921f9bb4

结果说明：

• 当前没有打 semver 标签，go get 拉到的是 commit 伪版本 v0.0.0-<timestamp>-<sha>；这个版本会被锁进 go.sum，团队成员拉同一份代码可以拿到完全一致的依赖。
• Go SDK 目前以 chat.completions（同步 + 流式）为主路径稳定，多媒体资源（images / video / audio）和 TaskHandle 轮询处于 alpha 阶段。需要这些能力的场景请优先选 TypeScript SDK 或 Python SDK。

准备 API Token

参考 SDK 总览 - 申请 API Token 取到 token，然后在 shell 里 export：

1

export ACEDATACLOUD_API_TOKEN={token}

构造客户端时通过 WithAPIToken(...) option 显式注入；Go SDK 不会自动读取环境变量，需要业务代码 os.Getenv 一下，这样在多账号或自测场景里更可控。

示例 1：chat.completions（非流式）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38

package main

import (
    "context"
    "fmt"
    "os"
    "time"

    adc "github.com/AceDataCloud/SDK/go"
)

func main() {
    client, err := adc.NewClient(adc.WithAPIToken(os.Getenv("ACEDATACLOUD_API_TOKEN")))
    if err != nil {
        panic(err)
    }
    ctx, cancel := context.WithTimeout(context.Background(), 60*time.Second)
    defer cancel()

    t0 := time.Now()
    res, err := client.OpenAI().Chat().Completions().Create(ctx, adc.ChatCompletionRequest{
        Model:     "gpt-4o-mini",
        Messages:  []map[string]any{{"role": "user", "content": "Reply with exactly: ADC_GO_SDK_OK"}},
        MaxTokens: 20,
    })
    if err != nil {
        panic(err)
    }
    fmt.Println("elapsed_ms", time.Since(t0).Milliseconds())
    fmt.Println("id", res["id"])
    fmt.Println("model", res["model"])
    choices := res["choices"].([]any)
    msg := choices[0].(map[string]any)["message"].(map[string]any)
    fmt.Println("content", msg["content"])
    usage := res["usage"].(map[string]any)
    fmt.Printf("usage prompt=%v completion=%v total=%v\n",
        usage["prompt_tokens"], usage["completion_tokens"], usage["total_tokens"])
}

程序运行结果：

1
2
3
4
5

elapsed_ms 6436
id chatcmpl-89DHExvFvBc4ciIPfolZYUOy7ivxv
model gpt-4o-mini
content ADC_GO_SDK_OK
usage prompt=16 completion=5 total=21

结果说明：

• id 是 OpenAI 兼容响应 ID，可以在控制台 使用历史 里搜到。
• content ADC_GO_SDK_OK 是模型真实输出，证明 SDK 没有篡改响应。
• 6.4 秒里大部分是首次 TLS 握手 + 上游模型生成，复用 client 实例之后延迟和 TS / Python 一致（约 2~3 秒）。
• 响应统一是 map[string]any，需要自己做类型断言；这是 Go SDK 当前的设计取舍——不引入泛型 struct 是为了让多模型路由不强依赖单一上游 schema。

示例 2：chat.completions（SSE 流式）

CreateStream 返回两个 channel：<-chan map[string]any 是逐帧解析好的 SSE chunk，<-chan error 在流结束（正常或出错）后才会有可读元素。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52

package main

import (
    "context"
    "fmt"
    "os"
    "time"

    adc "github.com/AceDataCloud/SDK/go"
)

func main() {
    client, err := adc.NewClient(adc.WithAPIToken(os.Getenv("ACEDATACLOUD_API_TOKEN")))
    if err != nil {
        panic(err)
    }
    ctx, cancel := context.WithTimeout(context.Background(), 60*time.Second)
    defer cancel()

    t0 := time.Now()
    chunks, errs := client.OpenAI().Chat().Completions().CreateStream(ctx, adc.ChatCompletionRequest{
        Model:     "gpt-4o-mini",
        Messages:  []map[string]any{{"role": "user", "content": "Count from 1 to 5 separated by spaces. Just the numbers."}},
        MaxTokens: 30,
    })

    first := int64(-1)
    cnt := 0
    collected := ""
    for chunk := range chunks {
        if first < 0 {
            first = time.Since(t0).Milliseconds()
        }
        cnt++
        if ch, ok := chunk["choices"].([]any); ok && len(ch) > 0 {
            if c0, ok := ch[0].(map[string]any); ok {
                if d, ok := c0["delta"].(map[string]any); ok {
                    if s, ok := d["content"].(string); ok {
                        collected += s
                    }
                }
            }
        }
    }
    if e, ok := <-errs; ok && e != nil {
        fmt.Println("stream_err", e)
    }
    fmt.Println("total_elapsed_ms", time.Since(t0).Milliseconds())
    fmt.Println("first_chunk_ms", first)
    fmt.Println("chunks", cnt)
    fmt.Println("collected", collected)
}

程序运行结果：

1
2
3
4

total_elapsed_ms 1816
first_chunk_ms 1633
chunks 13
collected 1 2 3 4 5

结果说明：

• 首帧 1633 ms，13 个 chunk 全部到齐用了 1816 ms——后 12 帧只用了 183 ms。
• range chunks 自然会在流结束时退出循环；errs channel 始终最多 yield 一个元素，配 ok 判断即可拿到错误。
• 这套 channel 风格的好处是可以直接 select 配合 context.Context 超时／取消，不需要额外封装。

示例 3：类型化错误处理

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

package main

import (
    "context"
    "errors"
    "fmt"

    adc "github.com/AceDataCloud/SDK/go"
)

func main() {
    bad, _ := adc.NewClient(adc.WithAPIToken("definitely-not-a-real-token"))
    _, err := bad.OpenAI().Chat().Completions().Create(context.Background(), adc.ChatCompletionRequest{
        Model:    "gpt-4o-mini",
        Messages: []map[string]any{{"role": "user", "content": "hi"}},
        MaxTokens: 5,
    })
    if err != nil {
        var apiErr *adc.APIError
        if errors.As(err, &apiErr) {
            fmt.Println("status:", apiErr.StatusCode)
            fmt.Println("code:", apiErr.Code)
            fmt.Println("message:", apiErr.Message)
        } else {
            fmt.Println("other err:", err)
        }
    }
}

adc.APIError 同时覆盖 401 / 403 / 404 / 422 / 429 / 5xx，业务代码用 errors.As 取到结构化字段即可。HTTP 状态码、上游 code 和 message 都保留原样。网络层错误（DNS 失败、连接被拒等）走 context.DeadlineExceeded、net.OpError 等标准 Go 错误，不会被吞掉。

配置选项（functional options）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

client, err := adc.NewClient(
    // 必填：API token；建议从环境变量读
    adc.WithAPIToken(os.Getenv("ACEDATACLOUD_API_TOKEN")),

    // 平台 API 根地址，默认 https://api.acedata.cloud
    adc.WithBaseURL("https://api.acedata.cloud"),

    // 单次请求超时，默认 5 分钟
    adc.WithTimeout(60*time.Second),

    // 自动重试次数，默认 2
    adc.WithMaxRetries(2),

    // 自定义请求头
    adc.WithHeader("x-app", "my-service/1.0"),
)

NewClient 返回 (*Client, error)：当 token 为空 且 没有传 WithPaymentHandler（X402）时会立即报错，便于在服务启动期就发现配置缺失。

进阶：复用 Client

Go SDK 内部用一个 *http.Client + http.Transport，自带连接池和 HTTP/2 复用。推荐在进程生命周期内只建一个 *adc.Client，然后跨 goroutine 共享——所有方法都是并发安全的。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

// pkg/acelearn/client.go
var sharedClient *adc.Client

func init() {
    var err error
    sharedClient, err = adc.NewClient(adc.WithAPIToken(os.Getenv("ACEDATACLOUD_API_TOKEN")))
    if err != nil {
        log.Fatal(err)
    }
}

func Chat(ctx context.Context, model, prompt string) (string, error) {
    res, err := sharedClient.OpenAI().Chat().Completions().Create(ctx, adc.ChatCompletionRequest{
        Model:    model,
        Messages: []map[string]any{{"role": "user", "content": prompt}},
    })
    if err != nil {
        return "", err
    }
    return res["choices"].([]any)[0].(map[string]any)["message"].(map[string]any)["content"].(string), nil
}

局限和路线图

当前稳定 / 推荐生产使用：

• ✅ client.OpenAI().Chat().Completions().Create 同步非流式
• ✅ client.OpenAI().Chat().Completions().CreateStream SSE 流式
• ✅ errors.As + APIError 错误处理
• ✅ 自动重试 + 指数退避

仍处于 alpha：

• 🚧 client.Images() / client.Video() / client.Audio() — 接口在演进中，建议先用 HTTP 直接调
• 🚧 TaskHandle 异步轮询 — 还没暴露到 Go SDK 表层
• 🚧 WithPaymentHandler（X402 链上付费）— 计划中，目前 X402 只支持 TypeScript 和 Python

如何查看剩余额度

通过 Ace Data Cloud 控制台 - 应用列表，即可查看当前账户的剩余额度。

通过 Ace Data Cloud 控制台 - 使用历史 即可查看所有使用历史和扣费详情。

了解更多

• 🟦 github.com/AceDataCloud/SDK/go on pkg.go.dev
• 🗂 SDK 源码
• 📘 TypeScript SDK 接入教程
• 🐍 Python SDK 接入教程
• 🔌 SDK + X402 支付钩子

X402 是基于 HTTP 402 Payment Required 的链上支付协议。通过 Ace Data Cloud 的 X402 能力，调用方可以不创建 API Token、不预充值账户余额，而是在每一次 API 请求中直接用 USDC 完成链上支付。

这组文档按真实接入顺序组织：先跑通一次最小请求，再接入 SDK，之后理解网络、计费方案、订单支付和 Facilitator。建议按下表从上到下阅读。

推荐接入路径

如果你只是想调用 Ace Data Cloud API，优先使用官方 SDK：

• TypeScript：@acedatacloud/sdk + @acedatacloud/x402-client
• Python：acedatacloud + acedatacloud-x402

公开源码与包地址：

SDK 会自动完成第一次无认证请求、解析 402 Payment Required、调用 payment handler、携带 PAYMENT-SIGNATURE 重试这些步骤。你只需要准备一个有 USDC 的钱包，并选择希望使用的网络。

如果你要让自己的 API 也支持 X402 收款，则需要阅读 Facilitator 文档，理解 paymentRequirements、paymentPayload、/verify 和 /settle 的关系。

支持状态

Ace Data Cloud X402 已在公开 API、官方 SDK、Facilitator 和链上结算路径完成验证。下表按开发者接入时最常用的能力维度汇总当前状态。

以下输出仅用于说明已验证路径的返回形态。实际接入时，请始终以当前 API 返回的 accepts 为准。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42

packages
@acedatacloud/sdk@2026.504.2 import ok
@acedatacloud/x402-client@2026.531.3 import ok
acedatacloud==2026.4.26.1 import ok
acedatacloud-x402==2026.5.31.3 import ok

API 402
status 402
accepts eip155:8453/exact, eip155:8453/upto, solana:5eykt4.../exact, eip155:1187947933/exact

TypeScript SDK
content ADC_TS_SDK_X402_OK

Python SDK
content ADC_PY_SDK_X402_OK

Base exact
content ADC_BASE_E2E_OK
tx 0x408430ab3451bc22a51e510cdb4b063d6b9686724fea7a31fc109af20f5cd2f3
explorer https://basescan.org/tx/0x408430ab3451bc22a51e510cdb4b063d6b9686724fea7a31fc109af20f5cd2f3

SKALE exact
content ADC_SKALE_E2E_OK
tx 0x9fd09901e74c763325fe118b2bc64765c3fca785b86b24a78b97964384db084f
explorer https://skale-base-explorer.skalenodes.com/tx/0x9fd09901e74c763325fe118b2bc64765c3fca785b86b24a78b97964384db084f

Base upto
content ADC_BASE_UPTO_OK
tx 0x4b0b836ce1cd1171cdbc37df1637150b024214ec28e7f6f2d09122f15cbfc036
explorer https://basescan.org/tx/0x4b0b836ce1cd1171cdbc37df1637150b024214ec28e7f6f2d09122f15cbfc036
signed ceiling 95215 atomic USDC
transfer value 3 atomic USDC

Solana exact
HTTP 402 -> HTTP 200
content ADC_SOLANA_E2E_OK
chain signature not confirmed in this run

Order payment
order 78481793-304e-47f7-bc0c-8231aec9cc1e state Finished pay_way X402
tx 0xfec08cc00a159ea1ec692b32faa9bf3d17595a986301169e689d94f58bc44151
explorer https://basescan.org/tx/0xfec08cc00a159ea1ec692b32faa9bf3d17595a986301169e689d94f58bc44151

说明：

• npm 和 PyPI 包都已在干净环境安装并导入成功。
• 未支付 API 请求返回 402，accepts 中包含 Base、SKALE 和 Solana 的可用支付方式。
• accepts[].network 是 CAIP-2 标识，客户端选网时必须按 CAIP-2 字符串匹配。
• TypeScript SDK 与 Python SDK 都能自动处理 402 并完成 paid retry。
• Base exact、SKALE exact、Base upto 和订单支付都有可公开打开的 explorer 地址。
• Base upto 的签名上限为 95215 atomic USDC，实际 settlement 为 3 atomic USDC，体现了后置计量按真实用量结算的特性。
• Solana exact 已验证 HTTP 402 -> HTTP 200 和模型输出。由于公开 RPC 查询可能限流，严格对账时建议使用自有 Solana RPC 或平台侧结算记录确认交易签名。

接入注意事项

开发者接入时，请优先关注当前请求返回的实时支付要求，而不是复制文档中的示例金额或地址：

• accepts[].maxAmountRequired 是当前请求可签名的最大金额。
• accepts[].asset 是本次请求要使用的 USDC 合约或 mint。
• accepts[].extra.chainId、accepts[].extra.facilitatorAddress 和 accepts[].extra.verifyingContract 会参与 EVM typed data 签名。
• upto 需要钱包先对目标链 USDC 授权 Permit2；未授权时会返回 PERMIT2_ALLOWANCE_REQUIRED。
• 如果明确希望使用后置计量，请在 TypeScript SDK 中传入 preferScheme: 'upto'，否则 SDK 会选择该网络下服务器返回的第一个可用 requirement。

可以公开核验的范围

接入前可以先核验这些公开入口和 SDK 行为：

• 未带 Authorization 或 PAYMENT-SIGNATURE 的 API 请求会返回 402 Payment Required，响应中的 accepts 是本次请求的唯一签名依据。
• TypeScript SDK 和 Python SDK 都提供 payment handler，SDK 传输层在收到 402 后会调用 handler 并重试一次。
• https://x402.acedata.cloud/.well-known/x402：返回 X402 discovery 文档和规范资源地址。
• https://facilitator.acedata.cloud/supported：返回 Facilitator 支持的网络与 scheme。
• X402Client 仓库包含高级链上验证工具，可用于确认签名、重试和 settlement 行为；工具输出不替代线上 API 返回的 accepts。

upto 属于后置计量结算，适合聊天补全、模型调用等真实用量在响应后才知道的 API。当前只有 Base 提供 upto；如果签名验证失败，请检查 chain id、facilitator 地址、spender、USDC 合约和 Permit2 allowance 是否与 402 响应一致。

xAI Grok 是一款非常强大的 AI 对话系统，只要输入提示词，就能在短短几秒内生成流畅自然的回复。Grok 以其独特的幽默风格和实时网络信息获取能力在业界独树一帜，如今，Grok 已在多个创新领域崭露头角，其影响力正快速扩大。无论是日常对话、创意写作，还是技术分析、代码调试，Grok 都能提供富有洞察力的智能协助，为用户的决策和创作带来全新维度的支持。

本文档主要介绍 Grok Chat Completion API 操作的使用流程，利用它我们可以轻松使用官方 Grok 的对话功能。

申请流程

要使用 Grok Chat Completion API，首先到 Ace Data Cloud 控制台 获取您的 API Token，留作备用。

如果你尚未登录或注册，会自动跳转到登录页面邀请你注册和登录，完成后会自动返回当前页面。

一个 API Token 即可调用平台所有服务，无需为每个服务单独申请。 首次申请会赠送免费额度，可免费体验；额度不足时可在 控制台 充值通用余额。

📘 完整文档：Grok Chat Completion API →

基本使用

接下来就可以在界面上填写对应的内容，如图所示：

在第一次使用该接口时，我们至少需要填写三个内容，一个是 authorization，直接在下拉列表里面选择即可。另一个参数是 model， model 就是我们选择使用 Grok 官网模型类别，这里我们主要有 8 种模型，详情可以看我们提供的模型。最后一个参数是messages，messages是我们输入的提问词数组，它是一个数组，表示可以同时上传多个提问词，每个提问词包含了 role 和 content，其中 role 表示提问者的角色，我们提供了三种身份，分别为 user 、assistant、system 。另一个 content 就是我们提问的具体内容。

同时您可以注意到右侧有对应的调用代码生成，您可以复制代码直接运行，也可以直接点击「Try」按钮进行测试。

常用可选参数：

• max_tokens：限制单次回复的最大 token 数。
• temperature：生成随机性，0-2 之间，值越大越发散。
• n：一次生成多少条候选回复。

调用之后，我们发现返回结果如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

{
  "id": "foaicmpl-13936918-cb99-49e1-b94c-bde98b482ed4",
  "model": "grok-4",
  "object": "chat.completion",
  "created": 1755839683,
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Yo! What's up? 😎 Ready to dive into whatever you're pondering about today?"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 8,
    "completion_tokens": 20,
    "total_tokens": 28,
    "prompt_tokens_details": {
      "cached_tokens": 0,
      "text_tokens": 0,
      "audio_tokens": 0,
      "image_tokens": 0
    },
    "completion_tokens_details": {
      "text_tokens": 0,
      "audio_tokens": 0,
      "reasoning_tokens": 0
    },
    "input_tokens": 0,
    "output_tokens": 0,
    "input_tokens_details": null
  }
}

返回结果一共有多个字段，介绍如下：

• id，生成此次对话任务的 ID，用于唯一标识此次对话任务。
• model，选择的 Grok 官网模型。
• choices，Grok 针对提问词给于的回答信息。
• usage：针对本次问答对 token 的统计信息。

其中 choices 是包含了 Grok 的回答信息，它里面的 choices 是 Grok回答的具体信息，可以发现如图所示。

可以看到，choices 里面的 content 字段包含了 Grok 回复的具体内容。

流式响应

该接口也支持流式响应，这对网页对接十分有用，可以让网页实现逐字显示效果。

如果想流式返回响应，可以更改请求头里面的 stream 参数，修改为 true。

修改如图所示，不过调用代码需要有对应的更改才能支持流式响应。

将 stream 修改为 true 之后，API 将逐行返回对应的 JSON 数据，在代码层面我们需要做相应的修改来获得逐行的结果。

Python 样例调用代码：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

import requests

url = "https://api.acedata.cloud/grok/chat/completions"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "grok-3",
    "messages": [{"role":"user","content":"Hello"}],
    "stream": True
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

输出效果如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45

data: {"id": "foaicmpl-503ab14f-3f22-46ab-9f91-3fb44773be38", "object": "chat.completion.chunk", "created": 1755839790, "model": "grok-3", "system_fingerprint": null, "choices": [{"delta": {"role": "assistant"}, "logprobs": null, "finish_reason": null, "index": 0}], "usage": null}

data: {"id": "foaicmpl-503ab14f-3f22-46ab-9f91-3fb44773be38", "object": "chat.completion.chunk", "created": 1755839790, "model": "grok-3", "system_fingerprint": null, "choices": [{"delta": {"content": "Yo, "}, "logprobs": null, "finish_reason": null, "index": 0}], "usage": null}

data: {"id": "foaicmpl-503ab14f-3f22-46ab-9f91-3fb44773be38", "object": "chat.completion.chunk", "created": 1755839790, "model": "grok-3", "system_fingerprint": null, "choices": [{"delta": {"content": "what"}, "logprobs": null, "finish_reason": null, "index": 0}], "usage": null}

data: {"id": "foaicmpl-503ab14f-3f22-46ab-9f91-3fb44773be38", "object": "chat.completion.chunk", "created": 1755839790, "model": "grok-3", "system_fingerprint": null, "choices": [{"delta": {"content": "'s g"}, "logprobs": null, "finish_reason": null, "index": 0}], "usage": null}

data: {"id": "foaicmpl-503ab14f-3f22-46ab-9f91-3fb44773be38", "object": "chat.completion.chunk", "created": 1755839790, "model": "grok-3", "system_fingerprint": null, "choices": [{"delta": {"content": "ood?"}, "logprobs": null, "finish_reason": null, "index": 0}], "usage": null}

data: {"id": "foaicmpl-503ab14f-3f22-46ab-9f91-3fb44773be38", "object": "chat.completion.chunk", "created": 1755839790, "model": "grok-3", "system_fingerprint": null, "choices": [{"delta": {"content": " Rea"}, "logprobs": null, "finish_reason": null, "index": 0}], "usage": null}

data: {"id": "foaicmpl-503ab14f-3f22-46ab-9f91-3fb44773be38", "object": "chat.completion.chunk", "created": 1755839790, "model": "grok-3", "system_fingerprint": null, "choices": [{"delta": {"content": "dy t"}, "logprobs": null, "finish_reason": null, "index": 0}], "usage": null}

data: {"id": "foaicmpl-503ab14f-3f22-46ab-9f91-3fb44773be38", "object": "chat.completion.chunk", "created": 1755839790, "model": "grok-3", "system_fingerprint": null, "choices": [{"delta": {"content": "o di"}, "logprobs": null, "finish_reason": null, "index": 0}], "usage": null}

data: {"id": "foaicmpl-503ab14f-3f22-46ab-9f91-3fb44773be38", "object": "chat.completion.chunk", "created": 1755839790, "model": "grok-3", "system_fingerprint": null, "choices": [{"delta": {"content": "ve i"}, "logprobs": null, "finish_reason": null, "index": 0}], "usage": null}

data: {"id": "foaicmpl-503ab14f-3f22-46ab-9f91-3fb44773be38", "object": "chat.completion.chunk", "created": 1755839790, "model": "grok-3", "system_fingerprint": null, "choices": [{"delta": {"content": "nto "}, "logprobs": null, "finish_reason": null, "index": 0}], "usage": null}

data: {"id": "foaicmpl-503ab14f-3f22-46ab-9f91-3fb44773be38", "object": "chat.completion.chunk", "created": 1755839790, "model": "grok-3", "system_fingerprint": null, "choices": [{"delta": {"content": "what"}, "logprobs": null, "finish_reason": null, "index": 0}], "usage": null}

data: {"id": "foaicmpl-503ab14f-3f22-46ab-9f91-3fb44773be38", "object": "chat.completion.chunk", "created": 1755839790, "model": "grok-3", "system_fingerprint": null, "choices": [{"delta": {"content": "ever"}, "logprobs": null, "finish_reason": null, "index": 0}], "usage": null}

data: {"id": "foaicmpl-503ab14f-3f22-46ab-9f91-3fb44773be38", "object": "chat.completion.chunk", "created": 1755839790, "model": "grok-3", "system_fingerprint": null, "choices": [{"delta": {"content": " you"}, "logprobs": null, "finish_reason": null, "index": 0}], "usage": null}

data: {"id": "foaicmpl-503ab14f-3f22-46ab-9f91-3fb44773be38", "object": "chat.completion.chunk", "created": 1755839790, "model": "grok-3", "system_fingerprint": null, "choices": [{"delta": {"content": "'re "}, "logprobs": null, "finish_reason": null, "index": 0}], "usage": null}

data: {"id": "foaicmpl-503ab14f-3f22-46ab-9f91-3fb44773be38", "object": "chat.completion.chunk", "created": 1755839790, "model": "grok-3", "system_fingerprint": null, "choices": [{"delta": {"content": "pond"}, "logprobs": null, "finish_reason": null, "index": 0}], "usage": null}

data: {"id": "foaicmpl-503ab14f-3f22-46ab-9f91-3fb44773be38", "object": "chat.completion.chunk", "created": 1755839790, "model": "grok-3", "system_fingerprint": null, "choices": [{"delta": {"content": "erin"}, "logprobs": null, "finish_reason": null, "index": 0}], "usage": null}

data: {"id": "foaicmpl-503ab14f-3f22-46ab-9f91-3fb44773be38", "object": "chat.completion.chunk", "created": 1755839790, "model": "grok-3", "system_fingerprint": null, "choices": [{"delta": {"content": "g ab"}, "logprobs": null, "finish_reason": null, "index": 0}], "usage": null}

data: {"id": "foaicmpl-503ab14f-3f22-46ab-9f91-3fb44773be38", "object": "chat.completion.chunk", "created": 1755839790, "model": "grok-3", "system_fingerprint": null, "choices": [{"delta": {"content": "out "}, "logprobs": null, "finish_reason": null, "index": 0}], "usage": null}

data: {"id": "foaicmpl-503ab14f-3f22-46ab-9f91-3fb44773be38", "object": "chat.completion.chunk", "created": 1755839790, "model": "grok-3", "system_fingerprint": null, "choices": [{"delta": {"content": "toda"}, "logprobs": null, "finish_reason": null, "index": 0}], "usage": null}

data: {"id": "foaicmpl-503ab14f-3f22-46ab-9f91-3fb44773be38", "object": "chat.completion.chunk", "created": 1755839790, "model": "grok-3", "system_fingerprint": null, "choices": [{"delta": {"content": "y?"}, "logprobs": null, "finish_reason": null, "index": 0}], "usage": null}

data: {"id": "foaicmpl-503ab14f-3f22-46ab-9f91-3fb44773be38", "object": "chat.completion.chunk", "created": 1755839790, "model": "grok-3", "system_fingerprint": null, "choices": [{"delta": {}, "logprobs": null, "finish_reason": "stop", "index": 0}], "usage": {"prompt_tokens": 0, "completion_tokens": 0, "total_tokens": 0, "prompt_tokens_details": {"cached_tokens": 0, "text_tokens": 0, "audio_tokens": 0, "image_tokens": 0}, "completion_tokens_details": {"text_tokens": 0, "audio_tokens": 0, "reasoning_tokens": 0}, "input_tokens": 0, "output_tokens": 0, "input_tokens_details": null}}

data: {"id": "foaicmpl-503ab14f-3f22-46ab-9f91-3fb44773be38", "object": "chat.completion.chunk", "created": 1755839790, "model": "grok-3", "system_fingerprint": "", "choices": [], "usage": {"prompt_tokens": 8, "completion_tokens": 18, "total_tokens": 26, "prompt_tokens_details": {"cached_tokens": 0, "text_tokens": 0, "audio_tokens": 0, "image_tokens": 0}, "completion_tokens_details": {"text_tokens": 0, "audio_tokens": 0, "reasoning_tokens": 0}, "input_tokens": 0, "output_tokens": 0, "input_tokens_details": null}}

data: [DONE]

可以看到，响应里面有许多 data ，data 里面的 choices 即为最新的回答内容，与上文介绍的内容一致。choices 是新增的回答内容，您可以根据结果来对接到您的系统中。同时流式响应的结束是根据 data 的内容来判断的，如果内容为 [DONE]，则表示流式响应回答已经全部结束。返回的 data 结果一共有多个字段，介绍如下：

• id，生成此次对话任务的 ID，用于唯一标识此次对话任务。
• model，选择的 Grok 官网模型。
• choices，Grok 针对提问词给于的回答信息。

JavaScript 也是支持的，比如 Node.js 的流式调用代码如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

const options = {
  method: "post",
  headers: {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
  },
  body: JSON.stringify({
    "model": "grok-3",
    "messages": [{"role":"user","content":"Hello"}],
    "stream": true
  })
};

fetch("https://api.acedata.cloud/grok/chat/completions", options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

Java 样例代码：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

JSONObject jsonObject = new JSONObject();
jsonObject.put("model", "grok-3");
jsonObject.put("messages", [{"role":"user","content":"Hello"}]);
jsonObject.put("stream", true);
MediaType mediaType = "application/json; charset=utf-8".toMediaType();
RequestBody body = jsonObject.toString().toRequestBody(mediaType);
Request request = new Request.Builder()
  .url("https://api.acedata.cloud/grok/chat/completions")
  .post(body)
  .addHeader("accept", "application/json")
  .addHeader("authorization", "Bearer {token}")
  .addHeader("content-type", "application/json")
  .build();

OkHttpClient client = new OkHttpClient();
Response response = client.newCall(request).execute();
System.out.print(response.body!!.string())

其他语言可以另外自行改写，原理都是一样的。

多轮对话

如果您想要对接多轮对话功能，需要对 messages 字段上传多个提问词，多个提问词的具体示例如下图所示：

Python 样例调用代码：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

import requests

url = "https://api.acedata.cloud/grok/chat/completions"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "grok-3",
    "messages": [{"role":"user","content":"Hello"},{"role":"assistant","content":"What model are you?"},{"role":"user","content":"What did I just say?"}]
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

通过上传多个提问词，就可以轻松实现多轮对话，可以得到如下回答：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

{
  "id": "foaicmpl-984ebc53-76b3-4d33-b0e8-0307ab4965af",
  "model": "grok-3",
  "object": "chat.completion",
  "created": 1755839996,
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "You said, \"Hello.\""
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 27,
    "completion_tokens": 6,
    "total_tokens": 33,
    "prompt_tokens_details": {
      "cached_tokens": 0,
      "text_tokens": 0,
      "audio_tokens": 0,
      "image_tokens": 0
    },
    "completion_tokens_details": {
      "text_tokens": 0,
      "audio_tokens": 0,
      "reasoning_tokens": 0
    },
    "input_tokens": 0,
    "output_tokens": 0,
    "input_tokens_details": null
  }
}

可以看到，choices 包含的信息与基本使用的内容是一致的，这个包含了 Grok 针对多个对话进行回复的具体内容，这样就可以根据多个对话内容来回答对应的问题了。

错误处理

在调用 API 时，如果遇到错误，API 会返回相应的错误代码和信息。例如：

• 400 token_mismatched：Bad request, possibly due to missing or invalid parameters.
• 400 api_not_implemented：Bad request, possibly due to missing or invalid parameters.
• 401 invalid_token：Unauthorized, invalid or missing authorization token.
• 429 too_many_requests：Too many requests, you have exceeded the rate limit.
• 500 api_error：Internal server error, something went wrong on the server.

错误响应示例

1
2
3
4
5
6
7
8

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

结论

通过本文档，您已经了解了如何使用 OpenAI Chat Completion API 轻松实现官方 OpenAI ChatGPT 的对话功能。希望本文档能帮助您更好地对接和使用该 API。如有任何问题，请随时联系我们的技术支持团队。

本文将介绍一种 Flux Images Generation API 对接说明，它是可以通过输入自定义参数来生成 Flux 官方的图片。

申请流程

要使用 Flux Images Generation API，首先到 Ace Data Cloud 控制台 获取您的 API Token，留作备用。

如果你尚未登录或注册，会自动跳转到登录页面邀请你注册和登录，完成后会自动返回当前页面。

一个 API Token 即可调用平台所有服务，无需为每个服务单独申请。 首次申请会赠送免费额度，可免费体验；额度不足时可在 控制台 充值通用余额。

📘 完整文档：Flux Images Generation API →

基本使用

首先先了解下基本的使用方式，就是输入提示词 prompt、 生成行为 action、图片尺寸 size，便可获得处理后的结果，首先需要简单地传递一个 action 字段，它的值为 generate，然后我们还需要输入提示词，具体的内容如下：

可以看到这里我们设置了 Request Headers，包括：

• accept：想要接收怎样格式的响应结果，这里填写为 application/json，即 JSON 格式。
• authorization：调用 API 的密钥，申请之后可以直接下拉选择。

另外设置了 Request Body，包括：

• action：此次图片生成任务的行为。
• size：图片生成结果的尺寸大小。flux-2-flex / flux-2-pro / flux-2-max 系列必须传入图片比例（如 1:1、16:9），不接受 1024x1024 这类像素尺寸，缺省会返回 400。
• count：生成图片的数量，默认值是 1，该参数只有在生成图片任务有效，编辑任务是无效的。
• prompt：提示词。
• model：生成模型，默认 flux-dev；最新旗舰为 flux-2-pro、flux-2-max（画质更高，需配合图片比例 size）。
• callback_url：需要回调结果的 URL。
• async：可选，设为 true 时接口立即返回 task_id，无需提供 callback_url，随后通过对应的任务查询接口轮询获取结果。

参数 size有一些特别限制，主要分为width x height宽高比例、x:y 图片比例俩种类型，具体的如下：

参考的图片比例： “21:9”, “16:9”, “4:3”, “3:2”, “1:1”, “2:3”, “3:4”, “9:16”, “9:21”。

选择之后，可以发现右侧也生成了对应代码，如图所示：

点击「Try」按钮即可进行测试，如上图所示，这里我们就得到了如下结果：

1
2
3
4
5
6
7
8
9
10

{
  "success": true,
  "task_id": "5456c749-3bbb-4f10-9eb8-cfbcac297500",
  "trace_id": "ae4eecb8-1dd6-45b4-bfb3-a1c48872536e",
  "data": [
    {
      "image_url": "https://platform2.cdn.acedata.cloud/flux/5456c749-3bbb-4f10-9eb8-cfbcac297500.jpg"
    }
  ]
}

返回结果一共有多个字段，介绍如下：

• success，此时视频生成任务的状态情况。
• task_id，此时视频生成任务 ID。
• trace_id，此时视频生成跟踪 ID。
• data，此时图像生成任务的结果列表。
  • image_url，此时图片生成任务的链接。
  • prompt，提示词。

可以看到我们得到了满意的图片信息，我们只需要根据结果中 data 的图片链接地址获取生成的 Flux 图片即可。

另外如果想生成对应的对接代码，可以直接复制生成，例如 CURL 的代码如下：

1
2
3
4
5
6
7
8
9
10

curl -X POST 'https://api.acedata.cloud/flux/images' \
-H 'authorization: Bearer {token}' \
-H 'accept: application/json' \
-H 'content-type: application/json' \
-d '{
  "action": "generate",
  "prompt": "A photorealistic studio product shot of a frosted-glass perfume bottle on wet black slate, single softbox key light, water droplets, dark moody background, 85mm macro.",
  "model": "flux-2-pro",
  "size": "1:1"
}'

编辑图片任务

如果想对某张图片进行编辑的话， 首先参数image_url必须传入需要编辑的图片链接，此时 action 只支持 edit，就可以指定如下内容：

• model：此次编辑图片任务所采用的模型，支持 flux-dev、flux-pro、flux-kontext-pro、flux-kontext-max、flux-2-flex、flux-2-pro、flux-2-max。
• image_url：上传需要编辑的图片。

填写样例如下：

填写完毕之后自动生成了代码如下：

对应的代码：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

import requests

url = "https://api.acedata.cloud/flux/images"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "action": "edit",
    "prompt": "a white siamese cat",
    "model": "flux-kontext-pro",
    "image_url": "https://cdn.acedata.cloud/ytj2qy.png"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

点击运行，可以发现会立即得到一个结果，如下：

1
2
3
4
5
6
7
8
9
10
11
12

{
  "success": true,
  "task_id": "2a7979ff-1f77-4380-92c6-a2dc37c3b4c8",
  "trace_id": "732b65c0-48d9-49f7-b568-64e5acffe4c0",
  "data": [
    {
      "prompt": "a white siamese cat",
      "image_url": "https://fal.media/files/monkey/aEUXJZ6Faj9YXUCQVs01Q_af0cea56c558441c9ba8df67b200812d.png",
      "timings": 1752744073
    }
  ]
}

可以看到，生成的效果是对原图片进行编辑的效果，结果与上文类似。

异步回调

由于 Flux Images Generation API 生成的时间相对较长，大约需要 1-2 分钟，如果 API 长时间无响应，HTTP 请求会一直保持连接，导致额外的系统资源消耗，所以本 API 也提供了异步回调的支持。

整体流程是：客户端发起请求的时候，额外指定一个 callback_url 字段，客户端发起 API 请求之后，API 会立马返回一个结果，包含一个 task_id 的字段信息，代表当前的任务 ID。当任务完成之后，生成图片的结果会通过 POST JSON 的形式发送到客户端指定的 callback_url，其中也包括了 task_id 字段，这样任务结果就可以通过 ID 关联起来了。

下面我们通过示例来了解下具体怎样操作。

首先，Webhook 回调是一个可以接收 HTTP 请求的服务，开发者应该替换为自己搭建的 HTTP 服务器的 URL。此处为了方便演示，使用一个公开的 Webhook 样例网站 https://webhook.site/，打开该网站即可得到一个 Webhook URL，如图所示：

将此 URL 复制下来，就可以作为 Webhook 来使用，此处的样例为 https://webhook.site/3d32690d-6780-4187-a65c-870061e8c8ab。

接下来，我们可以设置字段 callback_url 为上述 Webhook URL，同时填入相应的参数，具体的内容如图所示：

点击运行，可以发现会立即得到一个结果，如下：

1
2
3

{
  "task_id": "6a97bf49-df50-4129-9e46-119aa9fca73c"
}

稍等片刻，我们可以在 https://webhook.site/3d32690d-6780-4187-a65c-870061e8c8ab 上观察到生成图片的结果，如图所示：

内容如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

{
  "success": true,
  "task_id": "6a97bf49-df50-4129-9e46-119aa9fca73c",
  "trace_id": "9b4b1ff3-90f2-470f-b082-1061ec2948cc",
  "data": [
    {
      "prompt": "a white siamese cat",
      "image_url": "https://sf-maas-uat-prod.oss-cn-shanghai.aliyuncs.com/outputs/f4f8d407-377a-408a-82d0-427a5a836f09_0.png",
      "seed": 1698551532,
      "timings": {
        "inference": 3.328
      }
    }
  ]
}

可以看到结果中有一个 task_id 字段，其他的字段都和上文类似，通过该字段即可实现任务的关联。

错误处理

在调用 API 时，如果遇到错误，API 会返回相应的错误代码和信息。例如：

• 400 token_mismatched：Bad request, possibly due to missing or invalid parameters.
• 400 api_not_implemented：Bad request, possibly due to missing or invalid parameters.
• 401 invalid_token：Unauthorized, invalid or missing authorization token.
• 429 too_many_requests：Too many requests, you have exceeded the rate limit.
• 500 api_error：Internal server error, something went wrong on the server.

错误响应示例

1
2
3
4
5
6
7
8

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

结论

通过本文档，您已经了解了如何使用 Flux Images Generation API 可通过输入提示词来生成图片。希望本文档能帮助您更好地对接和使用该 API。如有任何问题，请随时联系我们的技术支持团队。

让你自己的产品支持「使用 Ace Data Cloud 登录」，并在用户授权后，代表用户读写其 Ace Data Cloud 资源（个人资料、API Token、订阅、用量、订单等）。底层是标准的 OAuth 2.0 授权码模式（Authorization Code）+ PKCE，与 GitHub / Google 登录的接法完全一致——你已有的任意 OAuth 客户端库都能直接用。

适合场景：你在做一个第三方应用 / Agent / MCP 客户端 / 自动化工作流，想让用户用 Ace Data Cloud 账号一键登录，并按需访问他在平台上的资源，而不必让用户手动复制粘贴 API Key。

名词 & 端点速查

所有端点都在 https://auth.acedata.cloud，可通过发现端点（Discovery）随时获取最新地址：

1

curl https://auth.acedata.cloud/.well-known/oauth-authorization-server

支持的能力：response_type=code、grant_types=authorization_code, refresh_token、code_challenge_methods=S256, plain、客户端认证方式 client_secret_post（机密客户端）/ none（PKCE 公开客户端）。

权限范围（Scope）

按「最小权限」申请，用户会在授权页看到你申请的每一项权限。

身份类（OIDC 兼容）

平台资源类

聚合类（自动展开）

特殊

典型组合：第三方「一键登录」=openid profile；MCP / IDE 客户端需要自动配 Key =openid profile credentials:read credentials:write；完整管理台 =openid profile email platform offline_access。

第 1 步：注册一个 OAuth 应用

打开 auth.acedata.cloud/user/oauth-apps →「创建应用」，填写：

1. 应用名称 / 描述 / Logo：会显示在用户的授权同意页。
2. 客户端类型（Client Type）：
   • 机密（confidential）——你有后端，能安全保管 client_secret（Web 服务、后端服务）。
   • 公开（public）——纯前端 / 桌面 / CLI / 移动端，无法保管密钥，必须用 PKCE。
3. 回调地址（Redirect URIs）：授权完成后用户被重定向回的地址，必须与你发起授权时传的 redirect_uri 完全一致，可填多个。
4. 权限范围（Scopes）：勾选上一节里你需要的 scope。

保存后拿到 client_id；机密客户端还会一次性显示 client_secret——立刻保存，关闭后无法再次查看（可在详情页「轮换密钥 / Rotate Secret」重新生成，旧密钥立即失效）。

每个账号最多创建 20 个 OAuth 应用。

第 2 步：把用户重定向到授权页

在你的应用里，把用户浏览器跳转到授权页，带上查询参数：

1
2
3
4
5
6
7
8

https://auth.acedata.cloud/oauth2/authorize
  ?response_type=code
  &client_id=<你的 client_id>
  &redirect_uri=<你注册的回调地址>
  &scope=openid%20profile%20credentials:read
  &state=<随机防 CSRF 串>
  &code_challenge=<PKCE 挑战值>          # 公开客户端必填
  &code_challenge_method=S256            # 公开客户端必填

• state：自己生成的随机串，回调时原样带回，用来防 CSRF，务必校验。
• PKCE（公开客户端必做，机密客户端也推荐）：先生成随机 code_verifier，再计算
  code_challenge = BASE64URL( SHA256( code_verifier ) )，把 code_challenge 放进授权 URL，
  code_verifier 自己留着第 4 步用。

用户登录并点击「同意」后，浏览器会被重定向回：

1

<redirect_uri>?code=<授权码>&state=<原样返回的 state>

若用户拒绝：<redirect_uri>?error=access_denied&error_description=...&state=...。

授权码有效期 10 分钟，且只能用一次。

第 3 步：用授权码换取令牌

在你的后端（机密客户端）或客户端（PKCE 公开客户端）用 code 调用令牌端点。

机密客户端（带 client_secret）：

1
2
3
4
5
6

curl -X POST https://auth.acedata.cloud/oauth2/token \
  -d grant_type=authorization_code \
  -d code=<上一步拿到的 code> \
  -d client_id=<你的 client_id> \
  -d client_secret=<你的 client_secret> \
  -d redirect_uri=<和第 2 步完全一致的回调地址>

公开客户端（PKCE，无 client_secret）：

1
2
3
4
5
6

curl -X POST https://auth.acedata.cloud/oauth2/token \
  -d grant_type=authorization_code \
  -d code=<code> \
  -d client_id=<你的 client_id> \
  -d code_verifier=<第 2 步生成的 code_verifier> \
  -d redirect_uri=<回调地址>

成功返回（refresh_token 仅在申请了 offline_access 时出现）：

1
2
3
4
5
6
7

{
  "access_token": "<JWT>",
  "token_type": "Bearer",
  "expires_in": 1296000,
  "scope": "openid profile credentials:read",
  "refresh_token": "<JWT，仅 offline_access 时>"
}

access_token 是一个 JWT，内含 scope 声明；有效期 15 天（expires_in 秒数）。Refresh Token 有效期 30 天。

第 4 步：用 Access Token 调用接口

把令牌放进 Authorization: Bearer 头即可。

读取用户信息（UserInfo，字段按已授权 scope 过滤）：

1
2

curl https://auth.acedata.cloud/api/v1/users/me \
  -H "Authorization: Bearer <access_token>"

调用平台资源接口（api.acedata.cloud，按 scope 鉴权）。例如已获 credentials:read：

1
2

curl https://api.acedata.cloud/api/v1/credentials/ \
  -H "Authorization: Bearer <access_token>"

平台后端会校验 JWT 里的 scope 声明——令牌只能访问用户授权过的资源。若访问了未授权的资源，会返回 403。

刷新令牌

Access Token 过期后，用 Refresh Token 换一对新令牌（需当初申请了 offline_access）：

1
2
3

curl -X POST https://auth.acedata.cloud/oauth2/token \
  -d grant_type=refresh_token \
  -d refresh_token=<你的 refresh_token>

返回结构同第 3 步；scope 会从原授权中原样保留。刷新后旧 Refresh Token 失效（轮换），请保存新的。

撤销令牌

1
2

curl -X POST https://auth.acedata.cloud/oauth2/revoke \
  -d token=<access_token 或 refresh_token>

真实案例：我们自己的 MCP 服务器就是这么接的

Ace Data Cloud 的 15+ 个 MCP 服务器（NanoBanana、Midjourney、Suno、Seedance、Kling…）在 Claude Desktop / Cursor 里出现的「Sign in with Ace Data Cloud」连接，走的就是这套流程：它们都是注册为 公开（PKCE） 类型的 OAuth 应用，申请 credentials 相关 scope，用户授权后 MCP 服务器即可代表用户调用 api.acedata.cloud——无需用户手动粘贴 API Key。你的接法和它们完全一样。

常见错误

错误响应统一为 { "error": "<code>", "error_description": "<人类可读说明>" }：

限制速查

SUNO 允许我们输入提示词来生成增强歌曲的风格。本文档讲解相关 API 的对接方法。

该 API 只有一个输入参数，就是 prompt，它是需要优化的风格提示词。

这里我们输入的 prompt 是 A song for Christmas。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

import requests

url = "https://api.acedata.cloud/suno/style"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "prompt": "A song for Christmas"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

结果如下：

1
2
3
4
5
6
7
8

{
  "success": true,
  "task_id": "8e887548-7185-48a9-b7cb-e51754f7b87b",
  "trace_id": "ac4ec363-4245-400b-9643-0b6fed8c6b20",
  "data": {
    "upsampled_tags": "Bright, festive bells and crisp acoustic guitar open, with sleigh bells and warm upright piano filling the verse. Lush strings sweep in for the pre-chorus, leading to a soaring full-band chorus enhanced by brass accents. The bridge softens with glockenspiel, then returns to a jubilant finale."
  }
}

可以看到，data 的 upsampled_tags 字段就是根据提示词优化后的风格参数。

做前端需要演示视频？写文档需要动态效果展示？现在你可以在 VS Code 里，用一句话让 GitHub Copilot 调用 Google Veo 生成高质量视频。不用切换窗口，不用学剪辑软件，聊天就能出片。

第 1 步：在 VS Code 中搜索并安装插件

1. 打开 VS Code 扩展市场（Cmd+Shift+X）
2. 搜索 Veo MCP，或直接搜索扩展 ID：acedatacloud.mcp-veo
3. 点击 Install，安装后按提示重载窗口

第 2 步：获取并填写 API Key

1. 打开 Ace Data Cloud 控制台 / Applications
2. 复制你的 API Key（同一个 Key 可用于全部 Ace Data Cloud MCP）
3. 按 Cmd+Shift+P，执行：Veo MCP: Set Ace Data Cloud API Key
4. 粘贴 API Key，回车保存（保存在 VS Code SecretStorage / 系统钥匙串）

如果要换 Key，可执行 Veo MCP: Clear Ace Data Cloud API Key 后重新设置。

第 3 步：验证已连通

1. 打开 GitHub Copilot Chat，切到 Agent 模式
2. 直接提需求并点名 veo，例如：用 veo 帮我完成这个任务
3. 首次调用时会自动走到该插件并使用你保存的 API Key

进阶：手动 mcp.json（可选）

如果你更偏好手动配置，也可以在项目里写 .vscode/mcp.json：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

{
  "servers": {
    "veo": {
      "type": "http",
      "url": "https://veo.mcp.acedata.cloud/mcp",
      "headers": {
        "Authorization": "Bearer ${input:acedata-api-key}"
      }
    }
  },
  "inputs": [
    {
      "id": "acedata-api-key",
      "type": "promptString",
      "description": "Ace Data Cloud API Key",
      "password": true
    }
  ]
}

第 3 步：验证已连通

1. 打开 GitHub Copilot Chat，切到 Agent 模式
2. 直接提需求并点名 veo，例如：用 veo 帮我完成这个任务
3. 首次调用时会自动走到该插件并使用你保存的 API Key

进阶：手动 mcp.json（可选）

如果你更偏好手动配置，也可以在项目里写 .vscode/mcp.json：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

{
  "servers": {
    "veo": {
      "type": "http",
      "url": "https://veo.mcp.acedata.cloud/mcp",
      "headers": {
        "Authorization": "Bearer ${input:acedata-token}"
      }
    }
  },
  "inputs": [
    {
      "id": "acedata-token",
      "type": "promptString",
      "description": "Ace Data Cloud API key",
      "password": true
    }
  ]
}

第 3 步：验证已连通

1. 打开 GitHub Copilot Chat，切到 Agent 模式
2. 直接提需求并点名 veo，例如：用 veo 帮我完成这个任务
3. 首次调用时会自动走到该插件并使用你保存的 API Key

进阶：手动 mcp.json（可选）

如果你更偏好手动配置，也可以在项目里写 .vscode/mcp.json：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

{
  "servers": {
    "veo": {
      "type": "http",
      "url": "https://veo.mcp.acedata.cloud/mcp",
      "headers": {
        "Authorization": "Bearer ${input:acedata-token}"
      }
    }
  },
  "inputs": [
    {
      "id": "acedata-token",
      "type": "promptString",
      "description": "Ace Data Cloud API key",
      "password": true
    }
  ]
}

实战示例

文字生成视频

1

> 帮我生成一段视频：一只猫在阳光下的花园里追蝴蝶，慢动作，电影质感

Copilot 调用 veo_text_to_video 工具，自动处理任务提交和状态轮询，最后返回视频链接。

图片生成视频

1

> 把这张产品照片变成一段动态展示视频，镜头慢慢推近，光影变化

上传图片后，Copilot 调用 veo_image_to_video 工具，基于图片生成流畅的动态视频。

带音频生成视频

1

> 生成一段带音频的视频：清晨的咖啡馆，咖啡机运作的声音，阳光透过玻璃窗洒在木桌上

Copilot 调用 veo_text_to_video 工具，veo3 / veo31 会同步生成原生音效，一步到位。

工具列表

其他编辑器配置

• Cursor — 在项目根目录创建 .cursor/mcp.json，使用 mcpServers 作为顶层 key，其余配置相同
• Claude Code — 终端命令行配置，详见 Claude Code + Veo MCP 教程
• Claude Desktop — 详见 Claude Desktop + Veo MCP 教程

相关链接

• Veo MCP Server (GitHub)
• Ace Data Cloud 平台
• MCP 协议官网

本文档主要介绍 Ace Data Cloud 全球代理的对接说明，包括申请方法、实用方法等具体内容。

申请方法

要使用全球服务，可以首先到「申请页面」进行申请，首次申请有 1 积分免费额度。

如果您尚未登录，则会自动跳转到登录页面，登录之后继续申请即可。

使用方法

申请完毕之后，可以到「控制台」中查看本人的申请结果，如图所示：

点击 「Credentials」，即可查看使用全球代理服务的用户名及密码，以冒号分隔，其中用户名是 8 位，密码是 32 位，如图所示：

本代理是一种轮换代理（Rotating Proxy），因此使用的时候只需要设置一个固定的代理地址和端口即可，代理的地址和端口分别是 global.proxy.acedata.cloud 和 30007，本代理是 HTTP/HTTPS/SOCKS 协议的代理，可以用于请求 HTTP 和 HTTPS 协议的网站。

注意：本代理只能在中国境外网络环境下使用，中国大陆地区无法使用。

命令测试

有了代理的用户名密码之后，最方便的方法便是通过 curl 命令行进行测试，如尚未安装，请参考 https://curl.se/ 安装即可。

假如当前代理的用户名密码是 1f78266a:eff0896726224fa2a99fe82dd1f07562，我们可以用如下 curl 命令进行测试：

1

curl -x 1f78266a:eff0896726224fa2a99fe82dd1f07562@global.proxy.acedata.cloud:30007 https://ipinfo.io

这里我们使用 curl 的 -x 参数指定了代理地址，代理协议默认是 HTTP/HTTPS，这里请求的 URL 是 https://ipinfo.io，这个站点可以返回请求该站点的真实 IP 地址和 IP 所在地域。

注意：上述用户名密码可能无效，请自行替换成你的用户名密码。

运行结果如下：

1
2
3
4
5
6
7
8
9
10
11
12

{
  "ip": "66.206.249.77",
  "hostname": "host-66-206-249-77.public.eastlink.ca",
  "city": "Kirkland Lake",
  "region": "Ontario",
  "country": "CA",
  "loc": "48.1446,-80.0377",
  "org": "AS11260 EastLink",
  "postal": "P2N",
  "timezone": "America/Toronto",
  "readme": "https://ipinfo.io/missingauth"
}

可以看到，返回结果的 country 是 CA，代表加拿大。如果再次运行，可以得到不一样的结果，每次请求都是随机的 IP 出口。

代码对接

下面以 Python 为例演示该代理的设置方法：

1
2
3
4
5
6
7
8
9
10
11
12

import requests

proxy = 'http://{proxy_username}:{proxy_password}@global.proxy.acedata.cloud:30007'

proxies = {
    'http': proxy,
    'https': proxy
}

for _ in range(3):
    resp = requests.get('https://ipinfo.io', proxies=proxies)
    print(resp.text)

这里我们首先声明了代理的 URL 并定义为 proxy 变量，协议是 http 协议，后面跟随隧道代理的用户名和密码（即控制台展示的用户名和密码，二者以冒号分隔），后面再跟一个 @ 符号，再跟代理的地址和端口即可。

注意：您需要将上述代码中的 {proxy_username}:{proxy_password}替换为您的代理用户名密码，最终结果类似 proxy = 'http://1f78266a:eff0896726224fa2a99fe82dd1f07562@global.proxy.acedata.cloud:30007'，注意没有 { 和 } 字符。

接着声明了一个 proxies 变量，配置了两个键值对，键名分别为 http 和 https，其键值都是 proxy，代表对于 HTTP 和 HTTPS 协议的网站，都是用 proxy 变量定义的代理来进行请求。接下来定义了三次循环进行代理的测试。

运行结果如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

{
  "ip": "103.190.205.165",
  "hostname": "assigned-for-client.adnsl.com",
  "city": "Paltan",
  "region": "Dhaka Division",
  "country": "BD",
  "loc": "23.7362,90.4143",
  "org": "AS38203 ADN Telecom Ltd.",
  "postal": "1000",
  "timezone": "Asia/Dhaka",
  "readme": "https://ipinfo.io/missingauth"
}
{
  "ip": "74.111.25.181",
  "hostname": "pool-74-111-25-181.syrcny.fios.verizon.net",
  "city": "Syracuse",
  "region": "New York",
  "country": "US",
  "loc": "43.0481,-76.1474",
  "org": "AS701 Verizon Business",
  "postal": "13201",
  "timezone": "America/New_York",
  "readme": "https://ipinfo.io/missingauth"
}
{
  "ip": "207.113.168.248",
  "city": "LaPorte",
  "region": "Indiana",
  "country": "US",
  "loc": "41.6106,-86.7225",
  "org": "AS13428 Surf Air Wireless, LLC",
  "postal": "46350",
  "timezone": "America/Chicago",
  "readme": "https://ipinfo.io/missingauth"
}

可以看到，每次运行的结果得到的代理 IP 都是随机的，而且 IP 所在地域确实是来源于全球不同国家不同城市。

当然，上述的代理设置方式实际上是一个相对简洁的设置方式。

实际上上述代码等价于在请求的时候设置了一个额外的 Headers - Proxy Authorization，所以上述代码还可以改写如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

import requests
import base64

proxy_host = 'global.proxy.acedata.cloud'
proxy_port = '30007'
proxy_username = '{proxy_username}' # 8位用户名
proxy_password = '{proxy_password}' # 32位密码

credentials = base64.b64encode(
    f'{proxy_username}:{proxy_password}'.encode()).decode()

proxies = {
    'http': f'http://{proxy_host}:{proxy_port}',
    'https': f'http://{proxy_host}:{proxy_port}'
}

headers = {
    'Proxy-Authorization': f'Basic {credentials}'
}

for _ in range(3):
    resp = requests.get('https://ipinfo.io',
                        proxies=proxies, headers=headers)
    print(resp.text)

可以看到，这里我们通过 Proxy-Authorization 这个请求头额外设置了代理的用户名和密码（需要进行 Base64 编码），这样的代码运行效果也是一样的。

对于其他语言，比如 JavaScript 的 axios，也可以使用类似的设置方式：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25