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

📘 完整指南：在 Codex CLI 里用全部 AceData Cloud MCP →

Face Transform = 关键点 + 美颜 + 年龄 / 性别变换 + 换脸 + 卡通化 + 活体检测，7 项面部能力。 通过 MCP 接入 Codex CLI 后，可以直接在对话里调用，不用切窗口、不用复制粘贴。

获取 API Token

到 AceData Cloud 平台 注册账号，复制首页的 API Token——一个 Token 即可使用全部 AceData Cloud MCP Server。详细步骤见 完整指南。

配置

编辑配置：~/.codex/config.toml

1
2
3
4
5

[mcp_servers.face]
url = "https://face.mcp.acedata.cloud/mcp"
type = "http"

http_headers = { "Authorization" = "Bearer 你的Token" }

保存后下一次 codex 会话启动时自动加载工具。

使用示例

用 face_beautify 给这张人像做美颜：磨皮 30、瘦脸 50

把这张人像（链接 xxx）变得年轻 10 岁

把 source.jpg 的脸换到 target.jpg 上，输出换脸结果

工具

相关链接

• Face Transform MCP Server (GitHub)
• Face Transform MCP on PyPI
• AceData Cloud 平台
• MCP 协议官网

为某个 Application 签发一枚 API 凭证（Credential）——即调用 https://api.acedata.cloud/** 业务接口（OpenAI、Midjourney、Suno、Veo 等）时用的 32 位 Token。

⚠️ 完整 Token 明文只在本接口的响应中返回一次。列表 / 详情接口都是脱敏的。请务必当场保存到密码管理器、环境变量或机密配置系统里。

ℹ️ 本接口属于 AceDataCloud 平台管理 API，统一前缀 https://platform.acedata.cloud/api/v1/。完整接口索引见获取 AceDataCloud 平台文档列表。

接口概览

鉴权说明（如何获取账户令牌）

请求头：

1

Authorization: Bearer platform-v1-92eb****629c

如何获取账户令牌：

1. 控制台一键创建（推荐）：登录 AceDataCloud 平台 → Account Token 控制台 → 点「创建」即可。
2. API 创建：详见管理 AceDataCloud 平台账户令牌。

请求体

请求示例

cURL

1
2
3
4
5
6
7
8
9
10
11

curl -X POST 'https://platform.acedata.cloud/api/v1/credentials/' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer platform-v1-92eb****629c' \
  -H 'content-type: application/json' \
  -d '{
    "application_id": "82f57141-2323-4453-8730-60f7d833a2da",
    "name": "production-server-01",
    "amount": 50.0,
    "expired_at": "2026-12-31T23:59:59Z",
    "client_ip_allowlist": ["203.0.113.7/32"]
  }'

Python

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

import requests

PLATFORM_TOKEN = "platform-v1-92eb****629c"
APPLICATION_ID = "82f57141-2323-4453-8730-60f7d833a2da"

resp = requests.post(
    "https://platform.acedata.cloud/api/v1/credentials/",
    headers={
        "accept": "application/json",
        "authorization": f"Bearer {PLATFORM_TOKEN}",
        "content-type": "application/json",
    },
    json={
        "application_id": APPLICATION_ID,
        "name": "production-server-01",
        "amount": 50.0,  # 此凭证最多消耗 50 Credit
    },
    timeout=10,
)

if resp.status_code == 201:
    cred = resp.json()
    print("✅ 完整 Token（请立即保存）：", cred["token"])
    print("ID =", cred["id"])
else:
    print(resp.status_code, resp.text)

Node.js

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

const PLATFORM_TOKEN = 'platform-v1-92eb****629c'

const r = await fetch('https://platform.acedata.cloud/api/v1/credentials/', {
  method: 'POST',
  headers: {
    authorization: `Bearer ${PLATFORM_TOKEN}`,
    'content-type': 'application/json',
  },
  body: JSON.stringify({
    application_id: '82f57141-2323-4453-8730-60f7d833a2da',
    name: 'production-server-01',
    amount: 50.0,
  }),
})

const cred = await r.json()
console.log('完整 Token（仅此一次！）:', cred.token)

响应示例（HTTP 201）

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

{
  "id": "df3e1b1b-9e72-4c4f-9a83-1e23f7c8b4d6",
  "user_id": "89518d07-5560-4b05-92c1-667f3ddf6a4b",
  "application_id": "82f57141-2323-4453-8730-60f7d833a2da",
  "name": "production-server-01",
  "token": "ac1234567890abcdef1234567890abcdef",
  "amount": 50.0,
  "used_amount": 0.0,
  "remaining_amount": 50.0,
  "disabled": false,
  "expired_at": "2026-12-31T23:59:59Z",
  "tags": null,
  "metadata": null,
  "client_ip_allowlist": ["203.0.113.7/32"],
  "used_at": null,
  "created_at": "2026-04-26T07:55:00Z",
  "updated_at": "2026-04-26T07:55:00Z"
}

⚠️ 这是 token 完整明文唯一会出现的地方。再次列表 / 详情查询会变成 ac****ef 这种脱敏格式。

使用刚创建的凭证

把 token 放到 Authorization: Bearer ... 头里调用业务接口：

1
2
3
4

curl 'https://api.acedata.cloud/v1/chat/completions' \
  -H 'authorization: Bearer ac1234567890abcdef1234567890abcdef' \
  -H 'content-type: application/json' \
  -d '{"model":"gpt-4.1","messages":[{"role":"user","content":"Hello"}]}'

错误处理

实用提示

• 生产环境必设 amount：凭证一旦泄露，限额能让损失限定在指定金额内。50 Credit 是个不错的起点。
• expired_at 用于临时凭证：演示账号、临时活动、与外包合作时设个短期过期，避免遗忘清理。
• client_ip_allowlist 是最强保险：把凭证锁定在生产服务器 IP 上，泄露到 GitHub 也无法使用。
• name 一定要起有意义：未来你可能有几十枚凭证，没好名字根本认不出哪个是哪个。
• 要拿”无限额、无 IP 限制、无过期”的凭证：把 amount、expired_at、client_ip_allowlist 都不传即可，但强烈不建议在公网项目里这样做。

相关接口

• 创建 AceDataCloud 平台服务申请 — 先有 Application 才能创建凭证
• 获取 AceDataCloud 平台 API 凭证列表
• 轮换 AceDataCloud 平台 API 凭证 — 不删旧凭证就轮换 Token
• 删除 AceDataCloud 平台 API 凭证
• 获取 AceDataCloud 平台 API 调用记录 — 查看凭证调用流水

NextChat（前身 ChatGPT-Next-Web）是中文社区广为人知的开源 AI 客户端，主打「一键部署 + 跨平台 + PWA」，可以在 Vercel / Cloudflare / Docker 上快速部署一个属于自己的 AI 网站。它原生支持自定义 OpenAI 兼容端点，因此可以接入 Ace Data Cloud，一份 API Token 同时访问 Claude、GPT、Gemini、Grok、DeepSeek、Kimi、GLM 等 60+ 大模型。本文介绍配置流程。

申请流程

要在 NextChat 中接入 Ace Data Cloud，首先到 Ace Data Cloud 控制台，获取您的 API Token，留作备用。

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

在首次申请时会有免费额度赠送，可以免费体验 Ace Data Cloud 的模型服务。

下载 NextChat

可以使用桌面版（Releases 页 下载 .exe / .dmg / AppImage）、Web 在线版，或自行部署到 Vercel / Cloudflare / Docker（见下文进阶章节）。

配置 Ace Data Cloud

启动 NextChat，进入 设置 → 模型服务：

NextChat 会自动在接口地址后拼接 /v1/chat/completions，因此只填根域名即可：

在「自定义模型名」框里用英文逗号分隔填写模型。NextChat 支持特殊语法：+模型名 添加、-模型名 隐藏、模型名=显示名 自定义显示名、-all 先全部隐藏。推荐最干净的写法：

1

-all,+gpt-5=GPT-5,+claude-opus-4-8=Claude Opus 4.8,+gemini-3.1-pro=Gemini 3.1 Pro,+grok-4=Grok 4,+deepseek-v3=DeepSeek V3

推荐模型

下面这些模型 ID 均已通过 Ace Data Cloud GET /v1/models 与 POST /v1/chat/completions 验证可用：

完整模型清单请以 Ace Data Cloud 服务文档 为准。

验证对接

如果不确定问题出在 NextChat 还是网络，可以先用 curl 直接验证端点（把 {token} 替换为你的 Token）：

1
2
3
4
5
6
7

curl -X POST 'https://api.acedata.cloud/v1/chat/completions' \
  -H 'Authorization: Bearer {token}' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gpt-5",
    "messages": [{"role": "user", "content": "ping"}]
  }'

返回 OpenAI 兼容的 chat.completion 对象即说明 Token 与端点都已就绪；若返回 HTTP 403 used_up 则表示 Token 有效但余额不足，到 控制台 充值即可。

进阶：一键部署到自己的域名

NextChat 支持部署一个属于自己的 AI 网站。以 Docker 为例（把 {token} 替换为你的 Token）：

1
2
3
4
5
6
7
8

docker run -d \
  --name nextchat \
  -p 3000:3000 \
  -e OPENAI_API_KEY={token} \
  -e BASE_URL=https://api.acedata.cloud \
  -e CODE=your-password \
  -e CUSTOM_MODELS="-all,+gpt-5,+claude-opus-4-8,+gemini-3.1-pro,+grok-4,+deepseek-v3" \
  yidadaa/chatgpt-next-web

Vercel / Cloudflare 部署时在项目的环境变量里配置相同的 OPENAI_API_KEY、BASE_URL、CODE、CUSTOM_MODELS 即可。CODE 支持英文逗号分隔多个访问密码，便于按人统计用量。以上环境变量的完整说明（BASE_URL 默认 https://api.openai.com、CUSTOM_MODELS 的 +/-/=/-all/+all 语法）请以 NextChat 官方 README 为准。

常见问题

提示 404 Not Found

通常是接口地址写成了 .../openai 或 .../openai/v1。改成 https://api.acedata.cloud，让 NextChat 自己拼接 /v1/chat/completions。

模型下拉里没有添加的模型

检查 CUSTOM_MODELS 格式，每个模型前必须有 +；如果用了 -all，要确保后面用 + 重新加回需要的模型。

提示 401 Unauthorized

请确认 API Key 中粘贴的是 Ace Data Cloud 的 Token（不含 Bearer 前缀、无多余空格），且所属应用余额充足。

了解更多

• NextChat GitHub ｜ NextChat 在线版
• NextChat 环境变量官方说明（README）
• Ace Data Cloud OpenAI Chat Completions API 文档
• Ace Data Cloud 服务列表
• Ace Data Cloud 控制台

AnythingLLM 是一款定位「文档 → 私有 ChatGPT」的开源客户端，核心概念是 Workspace——每个 Workspace 是一组文档、一组用户与一组 Agent 工具，独立隔离。它专为文档对话设计，提供桌面 App 与 Docker 双形态。在 LLM 供应商中，它内置了 OpenAI (Generic) 这一项，可填写自定义 Base URL，因此能直接把对话模型指向 Ace Data Cloud。本文介绍配置流程。

申请流程

要在 AnythingLLM 中接入 Ace Data Cloud，首先到 Ace Data Cloud 控制台，获取您的 API Token，留作备用。

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

在首次申请时会有免费额度赠送，可以免费体验 Ace Data Cloud 的模型服务。

下载 AnythingLLM

个人使用可下载 桌面版，向量库（LanceDB）跑在本地，搜文档完全离线、仅调模型时联网；团队多用户场景用 Docker 部署。

配置对话模型

启动 AnythingLLM，进入 Settings → LLM Preference，Provider 选择 OpenAI (Generic)（不要选普通的 OpenAI，那个固定指向 api.openai.com，没有自定义 Base URL）。官方文档参见 OpenAI (Generic) LLM Provider。

注意 Base URL 的路径规则：

配置 Embedding 模型

AnythingLLM 的核心是 RAG，需要一个嵌入模型把文档向量化。它的 Embedding Preference 与 LLM Preference 是相互独立的两套配置——参见 Embedder 配置总览。其内置的 AnythingLLM Embedder（Built-in / Native） 直接在本地运行，开箱即用、零配置，是默认且推荐的选择：

进入 Settings → Embedding Preference，Provider 保持默认的 AnythingLLM Embedder 即可，无需填写任何密钥。它会在本地完成文档向量化，原文与向量都存在本地 LanceDB，不上云。

AnythingLLM 的 Embedder 候选项（云端：OpenAI / Azure OpenAI / Cohere；本地：Built-in、LM Studio、LocalAI、Ollama）均按各自固定形态接入。其中云端 OpenAI 嵌入固定指向 api.openai.com、不支持自定义 Base URL；若希望走自定义端点，可使用 Generic OpenAI Embedder（同样带 Base URL 字段，可指向 Ace Data Cloud 的 text-embedding-3-large）或本地 LocalAI Embedder。本文对话模型走 Ace Data Cloud，嵌入则使用 AnythingLLM 自带的本地 Embedder，二者互不影响。

推荐模型

下面这些对话模型 ID 均可在 AnythingLLM 的 OpenAI (Generic) Provider 中填入 Selected Model 使用：

完整模型清单与可用性请以 Ace Data Cloud 服务文档 为准。

验证对接

如果不确定问题出在 AnythingLLM 还是网络，可以先用 curl 直接验证端点（把 {token} 替换为你的 Token）：

1
2
3
4
5
6
7

curl -X POST 'https://api.acedata.cloud/v1/chat/completions' \
  -H 'Authorization: Bearer {token}' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gpt-5",
    "messages": [{"role": "user", "content": "ping"}]
  }'

返回 OpenAI 兼容的 chat.completion 对象即说明 Token 与端点都已就绪；若返回 HTTP 403 used_up 则表示 Token 有效但余额不足，到 控制台 充值即可。

进阶：Workspace 与文档对话

新建 Workspace 后上传 PDF / Word / Markdown 等文档，AnythingLLM 会按段落切分、用本地 Embedder 生成向量并存入本地 LanceDB。对话时它会先检索相关片段，再把片段与你的问题一起交给对话模型（即 Ace Data Cloud）回答，并在回答下方标注引用来源。每个 Workspace 顶部可切换 Query（只基于文档回答）与 Chat（混合通用知识）模式，严肃场景建议用 Query 模式避免幻觉。Docker 部署时可用 GENERIC_OPEN_AI_BASE_PATH、GENERIC_OPEN_AI_API_KEY、GENERIC_OPEN_AI_MODEL_PREF 等环境变量预设同样的对话模型接入，并开启多用户模式。

常见问题

提示 404 / connection fail

通常是 Base URL 写成了 .../openai/v1 或漏了 /v1。改成 https://api.acedata.cloud/v1。

上传文档后无法对话

请确认 Settings → Embedding Preference 里选了可用的 Embedder（默认的 AnythingLLM Embedder 即可本地运行，无需额外配置），并重新上传文档以生成向量。

提示 401 Unauthorized

请确认 API Key 中粘贴的是 Ace Data Cloud 的 Token（不含 Bearer 前缀、无多余空格），且所属应用余额充足。

本地文档会上传到云端吗

不会。文档原文存在本地 LanceDB，只有检索命中的片段与你的问题会发给模型。

了解更多

• AnythingLLM 官网 ｜ AnythingLLM GitHub ｜ Docker 部署文档
• AnythingLLM OpenAI (Generic) LLM Provider 文档
• AnythingLLM Embedder 配置总览
• Ace Data Cloud OpenAI Chat Completions API 文档
• Ace Data Cloud 服务列表
• Ace Data Cloud 控制台

Flux Tasks API 的主要功能是通过输入 Flux Images Generation API 生成的任务ID来查询该任务的执行情况。

本文档将详细介绍 Flux Tasks API 的对接说明，帮助您轻松集成并充分利用该 API 的强大功能。通过 Flux Tasks API ，您可以轻松实现查询 Flux Images Generation API 的任务执行情况。

申请流程

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

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

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

📘 完整文档：Flux Images Generation API →

请求示例

Flux Tasks API 可以用于查询 Flux Images Generation API 的结果。关于怎样使用 Flux Images Generation API，请参考文档 Flux Images Generation API 。

我们以 Flux Images Generation API 服务返回的任务ID一个为例，演示如何使用该 API。假设我们有一个任务ID：2db0168c-2373-4367-8d9a-9dc778802e8a，接下来演示如何通过传入一个任务ID来。

任务示例图

设置请求头和请求体

Request Headers 包括：

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

Request Body 包括：

• id：上传的任务ID。
• action：对任务的操作方式。

设置如下图所示：

代码示例

可以发现，在页面右侧已经自动生成了各种语言的代码，如图所示：

部分代码示例如下：

CURL

1
2
3
4
5
6
7
8

curl -X POST 'https://api.acedata.cloud/flux/tasks' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "id": "2c454ff3-4f8f-47f0-8147-acb29a84d1c2",
  "action": "retrieve"
}'

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/flux/tasks"

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

payload = {
    "id": "2c454ff3-4f8f-47f0-8147-acb29a84d1c2",
    "action": "retrieve"
}

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

响应示例

请求成功后，API 将返回此处图片任务的详情信息。例如：

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

{
  "_id": "677de81d550a4144a5f4cf62",
  "id": "2db0168c-2373-4367-8d9a-9dc778802e8a",
  "api_id": "deefc5d7-7f22-43e9-929e-f2b6afee60b7",
  "application_id": "001c2f84-2a4a-4c4d-ba3f-8a89f43b5be2",
  "created_at": 1736304669.779,
  "credential_id": "b00bddd3-140f-4343-a9a2-affb312b60de",
  "request": {
    "action": "generate",
    "size": "1024x1024",
    "prompt": "a white siamese cat"
  },
  "trace_id": "6624929c-bb80-40c0-81e8-d96af8405d19",
  "user_id": "ad7afe47-cea9-4cda-980f-2ad8810e51cf",
  "response": {
    "success": true,
    "task_id": "2db0168c-2373-4367-8d9a-9dc778802e8a",
    "trace_id": "6624929c-bb80-40c0-81e8-d96af8405d19",
    "data": [
      {
        "prompt": "a white siamese cat",
        "image_url": "https://sf-maas-uat-prod.oss-cn-shanghai.aliyuncs.com/outputs/57d9ff7c-5a00-409e-9dcc-90f35b38d16e_0.png",
        "seed": 281520112,
        "timings": {
          "inference": 3.193
        }
      }
    ]
  }
}

返回结果一共有多个字段，request 字段就是发起任务时的 request body，同时response 字段是任务完成后返回的response body。字段介绍如下。

• id，生成此图片任务的 ID，用于唯一标识此次图片生成任务。
• request，查询图片任务中的请求信息。
• response，查询图片任务中的返回信息。

批量查询操作

这是是针对多个任务ID来进行查询图片任务详情，与上面不同的是需要将action选中为retrieve_batch

Request Body 包括：

• ids：上传的任务ID数组。
• action：对任务的操作方式。

设置如下图所示：

代码示例

可以发现，在页面右侧已经自动生成了各种语言的代码，如图所示：

部分代码示例如下：

CURL

1
2
3
4
5
6
7
8

curl -X POST 'https://api.acedata.cloud/flux/tasks' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "ids": ["2db0168c-2373-4367-8d9a-9dc778802e8a","72bdd69d-290d-4710-a6d4-60c78968865a"],
  "action": "retrieve_batch"
}'

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/flux/tasks"

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

payload = {
    "ids": ["2db0168c-2373-4367-8d9a-9dc778802e8a","72bdd69d-290d-4710-a6d4-60c78968865a"],
    "action": "retrieve_batch"
}

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

响应示例

请求成功后，API 将返回此次所有批量图片任务的具体详情信息。例如：

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
53
54
55
56
57
58
59
60
61
62
63
64
65

{
  "items": [
    {
      "_id": "677de81d550a4144a5f4cf62",
      "id": "2db0168c-2373-4367-8d9a-9dc778802e8a",
      "api_id": "deefc5d7-7f22-43e9-929e-f2b6afee60b7",
      "application_id": "001c2f84-2a4a-4c4d-ba3f-8a89f43b5be2",
      "created_at": 1736304669.779,
      "credential_id": "b00bddd3-140f-4343-a9a2-affb312b60de",
      "request": {
        "action": "generate",
        "size": "1024x1024",
        "prompt": "a white siamese cat"
      },
      "trace_id": "6624929c-bb80-40c0-81e8-d96af8405d19",
      "user_id": "ad7afe47-cea9-4cda-980f-2ad8810e51cf",
      "response": {
        "success": true,
        "task_id": "2db0168c-2373-4367-8d9a-9dc778802e8a",
        "trace_id": "6624929c-bb80-40c0-81e8-d96af8405d19",
        "data": [
          {
            "prompt": "a white siamese cat",
            "image_url": "https://sf-maas-uat-prod.oss-cn-shanghai.aliyuncs.com/outputs/57d9ff7c-5a00-409e-9dcc-90f35b38d16e_0.png",
            "seed": 281520112,
            "timings": {
              "inference": 3.193
            }
          }
        ]
      }
    },
    {
      "_id": "677de950550a4144a5f52963",
      "id": "72bdd69d-290d-4710-a6d4-60c78968865a",
      "api_id": "deefc5d7-7f22-43e9-929e-f2b6afee60b7",
      "application_id": "001c2f84-2a4a-4c4d-ba3f-8a89f43b5be2",
      "created_at": 1736304976.278,
      "credential_id": "b00bddd3-140f-4343-a9a2-affb312b60de",
      "request": {
        "action": "generate",
        "size": "1024x1024",
        "prompt": "a white siamese cat"
      },
      "trace_id": "1dca4b49-d31d-42e6-83d9-7f0c56f62d31",
      "user_id": "ad7afe47-cea9-4cda-980f-2ad8810e51cf",
      "response": {
        "success": true,
        "task_id": "72bdd69d-290d-4710-a6d4-60c78968865a",
        "trace_id": "1dca4b49-d31d-42e6-83d9-7f0c56f62d31",
        "data": [
          {
            "prompt": "a white siamese cat",
            "image_url": "https://sf-maas-uat-prod.oss-cn-shanghai.aliyuncs.com/outputs/57b5c7e5-3436-466d-86ed-583ede4a3d7c_0.png",
            "seed": 1437672535,
            "timings": {
              "inference": 3.175
            }
          }
        ]
      }
    }
  ],
  "count": 2
}

返回结果一共有多个字段，其中items是包含了批量图片任务的具体详情信息，每个图片任务的具体信息与上文的字段一样，字段信息如下。

• items，批量图片任务的所有具体详情信息。它是一个数组，每个数组的元素和上文查询单个任务的返回结果格式是一样的。
• count，此处批量查询图片任务的个数。

错误处理

在调用 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 Tasks API 进行查询单个或批量图片任务的所有具体详情信息。希望本文档能帮助您更好地对接和使用该 API。如有任何问题，请随时联系我们的技术支持团队。

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

申请流程

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

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

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

📘 完整文档：Pika Videos Generation API →

基本使用

首先先了解下基本的使用方式，就是输入提示词 prompt、 生成行为 action、参考图片 image_url 以及模型 model，便可获得处理后的结果，首先需要简单地传递一个 action 字段，它的值为 generate，然后我们还需要输入模型，目前文生视频只支持 1.5，具体的内容如下：

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

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

另外设置了 Request Body，包括：

• model：生成视频的模型，支持 2.0、1.5，目前文生视频只支持 1.5，视频生视频只支持 2.0。
• action：此次视频生成任务的行为，当前仅支持 generate。
• effect：此次视频生成任务采用的官方特效，文生图/图生图时可选，见文末模版列表。
• image_url：需要上传的参考图片链接或者 Base64 编码。
• video_url：视频生视频模式下的参考视频链接。
• aspect_ratio：宽高比，图片模式下不传；视频模式下按宽高比字符串填写。
• prompt：提示词。
• negative_prompt：需要规避的反向提示词。
• callback_url：需要回调结果的 URL。
• async：可选，设为 true 时接口立即返回 task_id，无需提供 callback_url，随后通过对应的任务查询接口轮询获取结果。

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

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

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

{
  "success": true,
  "task_id": "1bc50b89-ce4e-4046-8297-0a2f39ed89ea",
  "trace_id": "b7dd6242-9367-4b49-b0af-f7748ab14447",
  "data": [
    {
      "id": "39a8723a-de78-4e7b-a2bd-59116c3d5d61",
      "state": "complete",
      "prompt": "moving",
      "model": "1.5",
      "quality": "720p",
      "video_url": "https://cdn.pika.art/v1/39a8723a-de78-4e7b-a2bd-59116c3d5d61/moving_seed1223321842.mp4",
      "image_url": "https://cdn.pika.art/v1/39a8723a-de78-4e7b-a2bd-59116c3d5d61/poster.jpg",
      "duration": 5
    }
  ]
}

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

• success，此时视频生成任务的状态情况。
• task_id，此时视频生成任务ID。
• trace_id，此时视频生成跟踪ID。
• data，此时视频生成任务的结果列表。
  • id，此时视频生成任务的视频ID。
  • image_url，此时视频生成任务的封面链接。
  • video_url，此时视频生成任务的视频链接。
  • duration，此时视频生成任务的时长。
  • state，此时视频生成任务的状态。

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

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

1
2
3
4
5
6
7
8
9
10

curl -X POST 'https://api.acedata.cloud/pika/videos' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "action": "generate",
  "effect": "Ta-da",
  "prompt": "moving",
  "model": "1.5"
}'

视频生视频任务

如果想视频生视频任务任务， 首先参数video_url必须传入参考视频链接，此时 model 只支持 2.0，就可以指定如下内容：

• effect：该视频生视频任务采用的特效，目前只支持：”Pink Hair”、”Its Computer”、”Its Alive”、”Duplicate it”、”Wizard Cat”。
• model：此次生成视频任务所采用的模型，视频生视频任务目前支持者 2.0。
• video_url：上传参考视频的视频链接。

填写样例如下：

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

对应的代码：

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/pika/videos"

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

payload = {
    "action": "generate",
    "effect": "Pink Hair",
    "prompt": "moving",
    "model": "2.0",
    "video_url": "https://cdn.acedata.cloud/0slqxa.mp4"
}

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

{
  "success": true,
  "task_id": "a852042b-987b-4378-8699-7c2d33b4f36d",
  "trace_id": "49944c40-e948-4640-a1b3-732379883203",
  "data": [
    {
      "id": "d4472f11-bbce-4512-8054-cab1c04e3a8b",
      "state": "complete",
      "prompt": "Pink Hair",
      "model": "Pro",
      "quality": "1080p",
      "video_url": "https://cdn.pika.art/v1/d4472f11-bbce-4512-8054-cab1c04e3a8b/Pink_Hair_seed776225645.mp4",
      "image_url": "https://cdn.pika.art/v1/d4472f11-bbce-4512-8054-cab1c04e3a8b/poster.jpg",
      "duration": 5.041666666666667
    }
  ]
}

可以看到，生成的效果是视频生建视频的，结果与上文类似。

异步回调

由于 Pika Videos 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": "c372e7bc-1877-4b6d-9732-e1b9e16c06c0"
}

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

内容如下：

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

{
    "success": true,
    "task_id": "c372e7bc-1877-4b6d-9732-e1b9e16c06c0",
    "trace_id": "781cc036-926b-44d2-83ea-4045bf8e85d4",
    "data": [
        {
            "id": "458d50a4-43d1-4339-927a-c2f7d43fa570",
            "video_url": "https://cdn.pika.art/v1/458d50a4-43d1-4339-927a-c2f7d43fa570/moving_seed3878215573.mp4",
            "image_url": "https://cdn.pika.art/v1/458d50a4-43d1-4339-927a-c2f7d43fa570/thumbnail.jpg",
            "duration": 5,
            "state": "succeeded"
        }
    ]
}

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

目前所支持的模版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"
}

结论

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

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

功能概览

Flux MCP Server 提供以下核心功能：

• 文本生成图像 — 通过文本提示词生成高质量图像
• 图像编辑 — 基于文本指令编辑已有图像
• 多模型支持 — 支持 Flux Pro、Flux Dev、Flux Schnell、Flux Kontext 等多种模型
• 模型查询 — 查看所有可用模型及其能力
• 任务查询 — 监控生成进度并获取结果

前置准备

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

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

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

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

1

https://flux.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://flux.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": {
    "flux": {
      "type": "http",
      "url": "https://flux.mcp.acedata.cloud/mcp",
      "headers": {
        "Authorization": "Bearer 你的API Token"
      }
    }
  }
}

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

Claude Code（终端命令行）

1
2

claude mcp add flux --transport http https://flux.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": {
    "flux": {
      "type": "http",
      "url": "https://flux.mcp.acedata.cloud/mcp",
      "headers": {
        "Authorization": "Bearer 你的API Token"
      }
    }
  }
}

Cursor

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

1
2
3
4
5
6
7
8
9
10

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

其他支持 MCP 的客户端

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

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

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

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

安装

pip 安装（推荐）：

1

pip install mcp-flux-pro

或源码安装：

1
2
3

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

安装完成后，即可使用 mcp-flux-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": {
    "flux": {
      "command": "mcp-flux-pro",
      "env": {
        "ACEDATACLOUD_API_TOKEN": "你的API Token"
      }
    }
  }
}

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

1
2
3
4
5
6
7
8
9
10
11

{
  "mcpServers": {
    "flux": {
      "command": "uvx",
      "args": ["mcp-flux-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": {
    "flux": {
      "command": "mcp-flux-pro",
      "env": {
        "ACEDATACLOUD_API_TOKEN": "你的API Token"
      }
    }
  }
}

或者使用 uvx：

1
2
3
4
5
6
7
8
9
10
11

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

可用工具列表

使用示例

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

• 「帮我用 Flux 生成一张赛博朋克风格的城市夜景」
• 「把这张照片的背景改成海滩」
• 「用 Flux Kontext Pro 模型编辑这张图片，把衣服颜色改成红色」
• 「列出所有可用的 Flux 模型」

更多信息

• GitHub 仓库：AceDataCloud/FluxMCP
• PyPI 包：mcp-flux-pro
• API 文档：Flux 图像生成 API

列出当前账户已签发的全部 API 凭证（Credential）——也就是调用 https://api.acedata.cloud/** 业务接口时用的 32 位 Token。

ℹ️ 本接口属于 AceDataCloud 平台管理 API，统一前缀 https://platform.acedata.cloud/api/v1/。完整接口索引见获取 AceDataCloud 平台文档列表。

API 凭证 vs 账户令牌

新手最容易混淆——再强调一次：

详见管理 AceDataCloud 平台账户令牌。

接口概览

鉴权说明（如何获取账户令牌）

请求头：

1

Authorization: Bearer platform-v1-92eb****629c

获取方式：登录 AceDataCloud 平台 → Account Token 控制台 → 点击「创建」按钮。详见管理 AceDataCloud 平台账户令牌。

必传查询参数

⚠️ 必须带 ?user_id=<your_user_id>。列表接口逐对象做权限校验，没传时第一个非己对象就会返回 403 permission_denied。

获取 user_id：打开 https://auth.acedata.cloud/user/profile。

查询参数

请求示例

cURL

1
2
3
4

USER_ID=89518d07-5560-4b05-92c1-667f3ddf6a4b
curl "https://platform.acedata.cloud/api/v1/credentials/?user_id=${USER_ID}&limit=20" \
  -H 'accept: application/json' \
  -H 'authorization: Bearer platform-v1-92eb****629c'

Python

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

import requests

PLATFORM_TOKEN = "platform-v1-92eb****629c"
USER_ID = "89518d07-5560-4b05-92c1-667f3ddf6a4b"

resp = requests.get(
    "https://platform.acedata.cloud/api/v1/credentials/",
    headers={
        "accept": "application/json",
        "authorization": f"Bearer {PLATFORM_TOKEN}",
    },
    params={"user_id": USER_ID, "limit": 100},
    timeout=10,
)
data = resp.json()
print(f"共 {data['count']} 枚凭证")
for c in data["items"]:
    print(f"  {c['name']:30s}  {c['token'][:8]}...{c['token'][-4:]}  上次使用: {c.get('used_at') or '从未'}")

Node.js

1
2
3
4
5
6
7
8

const USER_ID = '89518d07-5560-4b05-92c1-667f3ddf6a4b'
const url = new URL('https://platform.acedata.cloud/api/v1/credentials/')
url.searchParams.set('user_id', USER_ID)

const r = await fetch(url, {
  headers: { authorization: 'Bearer platform-v1-92eb****629c' },
})
console.log(await r.json())

响应示例（HTTP 200）

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

{
  "count": 5,
  "items": [
    {
      "id": "df3e1b1b-9e72-4c4f-9a83-1e23f7c8b4d6",
      "user_id": "89518d07-5560-4b05-92c1-667f3ddf6a4b",
      "application_id": "82f57141-2323-4453-8730-60f7d833a2da",
      "name": "production-server-01",
      "token": "ac****ab",
      "amount": null,
      "used_amount": 12.34,
      "remaining_amount": null,
      "disabled": false,
      "expired_at": null,
      "tags": ["prod"],
      "metadata": null,
      "client_ip_allowlist": null,
      "used_at": "2026-04-26T08:30:00Z",
      "created_at": "2026-04-26T07:55:00Z",
      "updated_at": "2026-04-26T08:30:00Z"
    }
  ]
}

⚠️ 列表接口的 token 字段是脱敏的（前 2 + **** + 后 2 字符）。需要完整 Token 时请到创建 AceDataCloud 平台 API 凭证接口在创建当时保存。如果忘了保存只能轮换或删除重建。

响应字段说明

错误处理

实用提示

• token 脱敏不可逆——只有在创建或轮换那一刻完整明文返回一次，请务必当场存进密码管理器。
• 生产环境强烈推荐设 amount 限额：通过创建凭证时指定，可避免凭证泄露后被无限制扣费。
• 僵尸凭证清理：used_at 为 null 或长时间未更新的，可以批量删除。

相关接口

• 创建 AceDataCloud 平台 API 凭证
• 删除 AceDataCloud 平台 API 凭证
• 轮换 AceDataCloud 平台 API 凭证
• 获取 AceDataCloud 平台 API 调用记录

Safety defaults

• EmailDeliveryControl.sending_enabled defaults to false in PostgreSQL.
• EMAIL_MARKETING_ALLOW_REAL_RECIPIENTS defaults to false.
• The worker claims no recipients unless both controls permit delivery.
• Test-only mode claims only normalized addresses in EMAIL_MARKETING_TEST_RECIPIENTS.
• Do not reuse verification SMTP credentials or send to real users during rollout.

Tencent SES setup

The sender identity is mailer.acedata.cloud in ap-hongkong. DNS must pass all four Tencent checks:

• MX for mailer.acedata.cloud
• SPF TXT for mailer.acedata.cloud
• DKIM TXT for qcloudhk1024._domainkey.mailer.acedata.cloud
• DMARC TXT for _dmarc.mailer.acedata.cloud

The sender address is news@mailer.acedata.cloud. Campaign templates are created from locked campaign content in the admin console and must be approved by Tencent before scheduling.

Event callback

Tencent SES does not expose callback configuration through its public API. Configure it in the Tencent SES console only after the backend route is deployed.

Retrieve the callback URL without committing or copying the secret into source files:

1
2
3

KUBECONFIG=/path/to/hk-kubeconfig
CALLBACK_PATH=$(kubectl --kubeconfig "$KUBECONFIG" -n acedatacloud get secret email-marketing -o jsonpath='{.data.EMAIL_MARKETING_CALLBACK_PATH_SECRET}' | base64 --decode)
printf 'https://platform.acedata.cloud/api/v1/email-marketing/events/tencent/%s/\n' "$CALLBACK_PATH"

Register that HTTPS URL for SES delivery events. Then mark the registration complete and restart only the affected workloads:

1
2
3
4

kubectl --kubeconfig "$KUBECONFIG" -n acedatacloud patch secret email-marketing --type merge \
  -p "$(printf '{\"stringData\":{\"EMAIL_MARKETING_CALLBACK_REGISTERED\":\"true\"}}')"
kubectl --kubeconfig "$KUBECONFIG" -n acedatacloud rollout restart deployment/platform-backend
kubectl --kubeconfig "$KUBECONFIG" -n acedatacloud rollout restart deployment/platform-backend-email-worker

Scheduling fails closed until provider health reports the identity enabled, callback registered, and every campaign template approved.

Seed rollout

1. Keep EMAIL_MARKETING_ALLOW_REAL_RECIPIENTS=false.
2. Keep exactly the owner-approved seed addresses in EMAIL_MARKETING_TEST_RECIPIENTS.
3. Refresh audience profiles and create a campaign using a narrow preset.
4. Lock content, preview and freeze the audience, then create Tencent templates.
5. Wait for both locale templates to be approved.
6. Enable the database control with the typed test confirmation.
7. Release only the canary wave and verify callbacks, delivery, unsubscribe, and suppression behavior.
8. Disable the database control after the test.

Moving to real recipients requires a separate owner decision, changing the deployment secret to EMAIL_MARKETING_ALLOW_REAL_RECIPIENTS=true, restarting the workloads, and using the stronger typed confirmation shown by the admin API.

Recovery

• Pause globally first by setting EmailDeliveryControl.sending_enabled=false in the admin console.
• reconcile_email_delivery recovers expired leases and never retries a provider request with an ambiguous outcome.
• Ambiguous sends become OutcomeUnknown after the reconciliation window and require manual review.
• Provider/user suppressions cannot be manually deactivated; only ManualSafety suppressions can be removed with an audit reason.
• Recipient PII is purged after the configured retention period; hashes and aggregate delivery records remain for safety and reporting.

本文将介绍 Veo Upsample API 的对接说明。该接口用于对一段已经生成的 Veo 视频进行升采样或者输出动图预览。

申请流程

要使用 API，需要先到 Veo 服务对应页面申请。如果你尚未登录或注册，会自动跳转到登录页面。

基本使用

调用本接口需要传入两个参数：

• video_id：来源视频的任务 ID。可以是 /veo/videos、/veo/extend、/veo/reshoot、/veo/objects 任意接口生成的视频 ID。
• action：升采样动作，支持以下三种：
  • 1080p：把视频升采样到 1080p 分辨率。
  • 4k：把视频升采样到 4K 分辨率。
  • gif：把视频转换为动图（GIF）预览。

请求示例：

1
2
3
4
5
6
7
8

curl -X POST 'https://api.acedata.cloud/veo/upsample' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "video_id": "dd01fc69-e1f7-4b68-aa8c-463f6b748d11",
    "action": "4k"
  }'

返回结果与 /veo/videos 相同，仍然是异步任务结构，可以通过 task_id 在 /veo/tasks 接口查询任务状态：

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

{
  "success": true,
  "task_id": "8f5a90ae-3f86-4c4f-86f7-7126f5e92c76",
  "trace_id": "0f3e09c2-4c2e-46ea-9cdc-a31ec48b7c12",
  "data": [
    {
      "id": "253eedc47f1c4eb2a370ed2312168f4b",
      "video_url": "https://platform.cdn.acedata.cloud/veo/8f5a90ae.mp4",
      "created_at": "2025-07-25 16:07:43",
      "complete_at": "2025-07-25 16:10:28",
      "state": "succeeded"
    }
  ]
}

返回字段说明：

• success：升采样任务是否提交成功。
• task_id：本次升采样任务的 ID。
• data：升采样后的视频结果。
  • video_url：升采样后的视频地址。

计费说明

• action=1080p：0.16 Credit / 次
• action=4k：0.50 Credit / 次
• action=gif：0.13 Credit / 次

如果传入的 action 不在以上枚举内，会被默认计费为 0.50 Credit。建议显式传入支持的值。

异步回调

接口同样支持异步模式，传入 callback_url 即可在任务完成后通过 POST 请求回调结果。若无公网回调地址，也可将 async 设为 true，接口同样立即返回 task_id，随后通过对应的任务查询接口轮询获取结果。

无论你在做舆情监测、价格比价、内容采集、站点巡检还是多地域可用性测试，IP 都是第一道门槛。频繁、集中、异常的请求，极易被系统识别并封禁。Ace Data Cloud 的 ADSL 轮换代理服务，提供来自移动/联通/电信等真实拨号线路的海量出口 IP，天然更接近真实用户画像，显著降低封禁率，让你的数据流程稳定“过白”。

关键链接

• 服务页（申请/Acquire）：https://platform.acedata.cloud/services/adsl
• 网关与端口：adsl.proxy.acedata.cloud:30005

可视化引导与控制台示意

• 申请页面：
• 控制台查看申请记录：
• 查看用户名/密码凭证：

为什么是 ADSL 轮换代理

• 真实居民网络：非机房段，贴近日常用户行为特征，更难被识别为“机器人”。
• 规模庞大：覆盖国内百余城市，每日数十万级出口 IP，避免小池子反复命中。
• 使用简单：固定网关与端口，账号密码即可走代理；HTTP/HTTPS/SOCKS 全支持。
• 按量计费：控制成本，先拿免费额度验证，再按需扩容。

适合什么场景

• 舆情与合规监测：稳定抓取公开页面，降低频繁封 IP 的概率；
• 价格与竞品比对：多地域请求更真实，数据更接近用户端所见；
• 站点巡检与 A/B：模拟真实访问路径，监控不同省市的体验差异；
• 账号分发运营：降低同源特征，减少风控触发（请遵守各平台政策与法律法规）。

接入 3 步走

1. 申请开通：在 Ace Data Cloud 平台进入 ADSL 代理服务，点击 Acquire 获取凭证（通常附带免费额度）。
2. 设置代理：固定网关 adsl.proxy.acedata.cloud 与端口 30005，填入分配的 8 位用户名与 32 位密码。
3. 开始请求：在爬虫/脚本/服务中设置 HTTP/HTTPS/SOCKS 代理，即刻生效。

示例（curl）：

1

curl -x <username>:<password>@adsl.proxy.acedata.cloud:30005 https://ipinfo.io

示例（Python requests）：

1
2
3
4
5

proxies = {
  'http': 'http://<username>:<password>@adsl.proxy.acedata.cloud:30005',
  'https': 'http://<username>:<password>@adsl.proxy.acedata.cloud:30005'
}
requests.get('https://ipinfo.io', proxies=proxies)

更多语言快速接入

• Node.js（axios + Proxy-Authorization）

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

const axios = require('axios');
const base64 = (s) => Buffer.from(s).toString('base64');
const host = 'adsl.proxy.acedata.cloud';
const port = '30005';
const user = '<username>'; // 8位
const pass = '<password>'; // 32位
axios.get('https://ipinfo.io', {
  proxy: false,
  headers: { 'Proxy-Authorization': `Basic ${base64(`${user}:${pass}`)}` },
  httpAgent: new (require('http-proxy-agent'))(`http://${host}:${port}`),
  httpsAgent: new (require('https-proxy-agent'))(`http://${host}:${port}`)
}).then(res => console.log(res.data));

和你的数据栈无缝衔接

• 多语言、多框架：requests、axios、Java/Go/Node……全家桶平滑对接；
• 可观测更友好：支持 Proxy-Authorization 头与固定网关配置，便于分层与排错；
• 安全与合规：账号级隔离与额度可控，方便审计与限流策略。

小贴士：稳定性的三个关键

• 合理并发：根据目标站点与任务类型设置请求间隔与并发上限；
• UA 与行为：模拟真实 UA、Referer 与滚动行为，降低反爬信号；
• 本地缓存：对稳定内容做缓存与增量抓取，减少不必要请求。

现在就让数据顺利回家

进入 Ace Data Cloud 平台，开通 ADSL 轮换代理。让每一次请求都更像“真实用户”，给你的增长与风控留出更大的操作空间。

SUNO 允许我们创建新版的Persona-v2-vox 版:歌手风格，与旧版本不同的需要先获取vox_audio_id。本文档讲解创建新版Persona-v2-vox的 对接方法。

首选需要该 API获取vox_audio_id参数值， 该API可以输入多个个输入参数，比如 audio_id、vocal_start、vocal_end，它是参考歌曲ID以及选定的时间范围。

这里我们输入的 audio_id 是 42599b24-fb14-4cd3-a444-e15ffde3661b。

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/suno/vox"

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

payload = {
    "audio_id": "42599b24-fb14-4cd3-a444-e15ffde3661b",
    "vocal_end": 30,
    "vocal_start": 20
}

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
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67

{
  "success": true,
  "task_id": "9d5ce870-18e3-4c17-a1d9-7ef5a07918e9",
  "trace_id": "c31b50cd-0dbe-4e53-a7a5-83965dc5ad6b",
  "data": {
    "id": "24f0827e-5847-4011-b9b7-fc0b62032b65",
    "source_clip_id": "42599b24-fb14-4cd3-a444-e15ffde3661b",
    "status": "complete",
    "vocal_audio_url": "https://cdn1.suno.ai/processed_24f0827e-5847-4011-b9b7-fc0b62032b65_vocals.m4a",
    "vocal_end_s": 30,
    "vocal_start_s": 20,
    "wave_response": {
      "waveform_aggregates": [
        {
          "data": [
            [
              -4,
              4,
              -50,
              73,
              -2517,
              2887,
              
              294
            ],
            [
              -5,
              4,
              296
            ]
          ],
          "mip_map_level": 11
        },
       
        {
          "data": [
            [
              -19576,
              20406,
              -16717,
              16980,
              -18926,
              20807,
              -20029,
              20103,
              -16437,
              20899
            ],
            [
              -19578,
              20406,
              -16720,
              16980,
              -18825,
              20051,
              -20029,
              20103,
              -16453,
              20903
            ]
          ],
          "mip_map_level": 20
        }
      ]
    }
  }
}

可以看到，data 的 id 字段就是我们想要的vox_audio_id，然后我们去Persona API创建新版的Persona-v2-vox:歌手风格，具体输入如下所示：

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/suno/persona"

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

payload = {
    "name": "test",
    "audio_id": "42599b24-fb14-4cd3-a444-e15ffde3661b",
    "vocal_end": 30,
    "vocal_start": 20,
    "vox_audio_id": "24f0827e-5847-4011-b9b7-fc0b62032b65"
}

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

调用后得到如下结果：

1
2
3
4
5
6
7

{
  "success": true,
  "task_id": "e04b06a1-ff61-48e2-9fcc-15284bd18481",
  "data": {
    "persona_id": "49bef16d-6a09-49d1-8c24-a81663698b98"
  }
}

然后我们可以根据上面的persona_id值进行新版的Persona-v2-vox:歌手风格进行创作，具体的创作方法和Suno 歌曲生成 API 对接说明一致，最后我们就可以通过Suno Vox API来实现新版的Persona-v2-vox:歌手风格进行创作歌曲。

OpenCode 本身擅长读代码、改文件、跑命令、解释报错；MCP 则让它在同一个终端会话里继续调用外部工具。AceData Cloud 把音乐、图片、视频、搜索、短链这些能力做成托管式远程 MCP Server，你不需要本地启动服务，也不需要为每个工具维护不同账号。

这篇是总览入口，重点帮你判断：OpenCode MCP 能做什么、该先接哪个服务、每个服务的详细教程在哪里。具体配置写法、Token 获取、global / project 两种位置的差异，放在下面每篇单服务文章里展开。

如果你的 OpenCode 还不能正常调用模型，请先看 OpenCode 终端配置教程。如果你想直接对接 Claude Code 而不是 OpenCode，请看 Claude Code MCP 总览。

为什么要在 OpenCode 里接 MCP

OpenCode 是完全开源的终端编程 Agent，它的强项是”原生终端体验 + 任意模型可换”。接入 MCP 之后，它可以把”写完代码 → 补 README 配图 → 做发布素材 → 查参考资料 → 压短链分享”这一长串本来需要切换浏览器和工具的工作，全部在终端会话里完成。

和 IDE 类工具相比，OpenCode 更适合：

• SSH 远程开发场景（无 GUI 也能完整使用 MCP）
• 用脚本/CI 把 MCP 调用拼接进自动化流程
• 喜欢键盘流、不希望被插件挡住屏幕的工程师

AceData Cloud 提供哪些 MCP Server

一个 AceData Cloud API Token 可以使用以下全部 MCP Server。你可以只接一个，也可以按工作流组合多个。

上表的「工具数」是 2026-05-31 用 opencode mcp list + JSON-RPC tools/list 实测得到，10 个 MCP Server 共暴露 109 个工具。

推荐怎么选

如果你只是想先确认 MCP 能跑通，建议从 Google 搜索 MCP 或 ShortURL MCP 开始：调用快、结果直观、成本低。做内容和营销素材时，可以从 Flux / Seedream / Midjourney 里选一个图像服务；需要视频时再接 Luma / Veo / Seedance；需要音乐或 BGM 时接 Suno。

配置在哪里写

OpenCode 用同一份 opencode.json 描述供应商和 MCP。两种位置只是优先级不同：

• 全局：~/.config/opencode/opencode.json，所有项目共用，适合”我自己的机器，一次配好”。
• 项目级：当前项目根目录下的 opencode.json，仅对该项目生效，会覆盖全局，适合团队共享或单仓库定制。

无论放在哪里，结构都是相同的，每个服务一段 mcp.<name> 配置：

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

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

字段说明：

{env:ACEDATACLOUD_API_KEY} 让 OpenCode 在启动时从环境变量里读取 Token，避免把真实 Token 直接写入文件。建议在 ~/.zshrc / ~/.bashrc 里 export ACEDATACLOUD_API_KEY="你的Token"。如果 Token 写在没有 export 的 .env 文件里，需要用 set -a && source .env && set +a 把它导出到 OpenCode 进程，否则 opencode debug config 会显示 "Authorization": "Bearer "（占位符未解析）。

配置示例里不会写完整 Token，只会用类似 357265014ad145fc8ab2.... 的形式展示。真实 Token 请只保存在你本机配置或私有环境变量中。

真实连通性验证

以下结果来自 OpenCode 1.15.13，在隔离临时目录中把 10 个 AceData MCP 同时写入 opencode.json，再运行 opencode mcp list 得到。Token 已脱敏（357265014ad145fc8ab2....），临时配置已删除。

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

$ opencode --version
1.15.13

$ opencode mcp list

┌  MCP Servers
│
●  ✓ suno connected
│      https://suno.mcp.acedata.cloud/mcp
●  ✓ midjourney connected
│      https://midjourney.mcp.acedata.cloud/mcp
●  ✓ flux connected
│      https://flux.mcp.acedata.cloud/mcp
●  ✓ seedream connected
│      https://seedream.mcp.acedata.cloud/mcp
●  ✓ nanobanana connected
│      https://nanobanana.mcp.acedata.cloud/mcp
●  ✓ luma connected
│      https://luma.mcp.acedata.cloud/mcp
●  ✓ veo connected
│      https://veo.mcp.acedata.cloud/mcp
●  ✓ seedance connected
│      https://seedance.mcp.acedata.cloud/mcp
●  ✓ serp connected
│      https://serp.mcp.acedata.cloud/mcp
●  ✓ shorturl connected
│      https://shorturl.mcp.acedata.cloud/mcp
│
└  10 server(s)

调试单个 MCP 连接：

1

opencode mcp debug shorturl

选模型的实测建议

要在 OpenCode 中真正”对话 + 调用 MCP 工具”两件事一起做，模型选择有讲究。下面是用 AceData Token 实际测试得到的结论：

已知限制：当 opencode.json 中同时启用多个 MCP 时，Claude 系列模型容易在上游返回 Improperly formed request。原因是部分 MCP 工具的 JSON Schema（anyOf 等用法）超出了 Anthropic 接口的严格校验范围。要让 Claude 同时对话 + 调用工具，建议先在 opencode.json 中把暂时不用的 MCP 的 enabled 改成 false，只保留必要的几个；或者直接换成 OpenAI 系列模型作为对话模型。

常见工作流

终端里写 README 顺手生图

让 OpenCode 先读懂你新功能的 README 草稿，再调用 Midjourney / Flux / Seedream 生成 banner，最后把图片 URL 直接贴回 README。

远程服务器排查问题 + 搜资料

SSH 到服务器后启动 opencode，让它结合本地日志和 Google 搜索 MCP 找到匹配的社区帖子或 issue，再用 ShortURL MCP 把相关链接压成短链发到群里。

发版素材一条龙

让 OpenCode 根据 CHANGELOG 用 Suno 写一段 30 秒 BGM、用 Veo 生成预览视频、用 Flux 出一张主视觉，整个过程不离开终端。

下一步

从上面的表格里选一个服务进入单独教程，先在项目 opencode.json 里跑通单服务。确认 opencode mcp list 显示 ✓ connected 后，再决定是否把它升级到全局 ~/.config/opencode/opencode.json，让所有项目都能直接调用。

相关链接

• OpenCode 官方文档
• OpenCode 配置参考
• OpenCode 终端配置教程
• 所有 MCP Server 列表
• REST API 文档

📘 Overview：OpenCode MCP Overview →

Seedance 在“短视频 / 竖屏素材 / 动作演绎”上的表现尤其稳定，可以一次性给出带音频的成片，非常适合直接用作社交媒体素材。在 OpenCode 里接上 Seedance MCP Server 后，可以从需求一句话直接出动效视频，省去剪辑、配音的中间步骤。

Seedance MCP 适合做 Reels / 抖音 / 小红书短视频、产品 demo 动效、技术分享开场片头等“短而有冲击力”的视频场景。

获取 API Token

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

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

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

想用 Claude Desktop / Claude.ai 网页版直接 OAuth 一键授权？请看 Seedance 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": {
    "seedance": {
      "type": "remote",
      "url": "https://seedance.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 seedance 也会回显 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": {
    "seedance": {
      "type": "remote",
      "url": "https://seedance.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
│
●  ✓ seedance connected
│      https://seedance.mcp.acedata.cloud/mcp
│
└  1 server(s)

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

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

1

opencode mcp debug seedance

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

🤖 选模型的实测建议：在 OpenCode 里要真正让模型主动调用 Seedance 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

生成一段竖屏短视频：少女在樱花树下转身，慢动作，唯美光影

图生视频

1

用这张图做封面，生成一段镜头慢慢推进的视频

生成视频片头

1

生成一段 3 秒的视频片头：一个发光的代码符号 </> 从模糊变清晰，背景有粒子特效，科技蓝色调

工具列表

下表列出主要工具（Seedance MCP Server 实测共暴露 7 个工具，可通过 curl -X POST https://seedance.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"}' 获取完整清单）：

相关链接

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

BYOK（Bring Your Own Key）让你在 Nexior / Studio 的对话界面里，直接使用自己已有的上游服务商 API Key，完全绕开平台的账号池和积分计费。配置后该模型的对话请求会用你的 Key 直接打到 OpenAI / Anthropic / Google / xAI / DeepSeek / Moonshot / Zhipu —— 平台只做转发和工具拼装，不消耗任何积分。

适合场景：你已经有上游账号 + 余额，希望复用平台的 UI（云历史、Artifacts、引用、工具调用、Connector），但不想按平台的零售价付钱。

支持的提供商

每个 Provider 可保存多把 Key（例如个人 Key + 公司 Key），并通过 Label 区分。

5 分钟实操

第 1 步：打开 BYOK 设置

登录 studio.acedata.cloud → 右上角头像 → Settings → Custom API Key。

第 2 步：添加一把 OpenAI Key

1. 点 Add API Key；
2. Provider 选 OpenAI；
3. Label（可选）：My Work ID；
4. API Key：粘贴你的 sk-...；
5. Custom Base URL（可选）：留空走官方地址；如要走代理（例如 https://openai.acedata.cloud），把整段 base URL 填这里；
6. 勾选 Active 后保存。

第 3 步：开始对话

回到聊天，模型选 gpt-5.5 / gpt-5-pro / gpt-4.1 任一 OpenAI 模型，发一条消息。Studio 会优先匹配你已激活的 BYOK Key，并在对话顶部显示 BYOK · OpenAI 徽章 —— 看到这个徽章说明这条对话没消耗平台积分。

如果同一 Provider 有多把 Key，Studio 会按最近使用 + Label 优先选；你也能在徽章上点击切换。

注意事项

1. 只覆盖该 Provider 的模型：例如配置 OpenAI Key 只影响 GPT 系列，切到 Claude 仍会扣平台积分（除非你也配了 Anthropic Key）。
2. 工具调用、引用、Artifacts、Connector 不受影响：这些都是平台侧的能力，不论是否走 BYOK 都正常工作。
3. 错误处理透明：上游 401 / 429 / 5xx 会原样返回到对话，让你能直接看到上游 Key 的状态。
4. Key 加密保存：平台只在转发请求时解密；不写日志、不会出现在客户端。
5. 临时停用：把 Active 关掉而不删，下一条对话立即回退到平台积分计费。
6. 不支持流式生效切换：对话进行中不会改用 BYOK，新建对话或刷新页面后生效。

常见问题

Q：自定义 Base URL 怎么配？
A：场景 1（境内代理）：填 https://openai.acedata.cloud/v1，请求会先走 AceData Cloud 边缘再到 OpenAI；场景 2（私有网关）：填你公司内部的 OpenAI 兼容网关。注意末尾不要带斜杠、不要带 /chat/completions。

Q：能跟订阅 / 充值并存吗？
A：能。BYOK 优先于积分计费；当 BYOK Key 失效（401）时不会自动 fallback 到积分，会直接报错让你修 Key。

Q：能管理团队成员的 Key 吗？
A：当前 BYOK 是个人维度的。团队 / 站长可以在 Subsite 维度统一配置上游账号池，请参考 Subsite 教程。

相关链接

• Studio 在线体验
• Connector 教程
• Subsite 白标教程

Grok Tasks API 的主要功能是通过输入 Grok Videos Generation API 生成的任务 ID 来查询该任务的执行情况。

本文档将详细介绍 Grok Tasks API 的对接说明，帮助您轻松集成并查询 Grok Videos Generation API 的任务执行情况。

申请流程

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

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

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

📘 完整文档：Grok Videos Generation API →

请求示例

Grok Tasks API 可以用于查询 Grok Videos Generation API 的结果。

设置请求头和请求体

Request Headers 包括：

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

Request Body 包括：

• id：要查询的任务 ID。
• action：对任务的操作方式，单个查询填写 retrieve。

CURL 代码示例

1
2
3
4
5
6
7
8

curl -X POST 'https://api.acedata.cloud/grok/tasks' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "id": "b8976e18-32dc-4718-9ed8-1ea090fcb6ea",
  "action": "retrieve"
}'

响应示例

请求成功后，API 将返回此处任务的详情信息。其中 request 字段是发起任务时的 request body，response 字段是任务完成后返回的 response body，例如：

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

{
  "id": "b8976e18-32dc-4718-9ed8-1ea090fcb6ea",
  "request": {
    "prompt": "A cinematic shot of a kitten chasing a butterfly in a sunlit garden",
    "model": "grok-imagine-video-1.5-fast",
    "resolution": "480p",
    "duration": 8
  },
  "type": "videos",
  "response": {
    "success": true,
    "task_id": "b8976e18-32dc-4718-9ed8-1ea090fcb6ea",
    "trace_id": "fb751e1e-4705-49ea-9fd4-5024b7865ea2",
    "data": [
      {
        "id": "grok-imagine-video-1.5-fast:41eb9a5f-3b2d-4d1e-9f5a-6c2f1a0b9e77",
        "video_url": "https://cdn.acedata.cloud/c8cbf53aa0.mp4",
        "state": "succeeded"
      }
    ]
  }
}

字段介绍如下：

• id：生成任务的 ID，用于唯一标识此次生成任务。
• request：查询任务中的请求信息。
• response：查询任务中的返回信息。

批量查询操作

针对多个任务 ID 查询任务详情时，将 action 设置为 retrieve_batch，并通过 ids 传入任务 ID 数组：

Request Body 包括：

• ids：要查询的任务 ID 数组。
• action：对任务的操作方式，批量查询填写 retrieve_batch。

1
2
3
4
5
6
7
8

curl -X POST 'https://api.acedata.cloud/grok/tasks' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "ids": ["b8976e18-32dc-4718-9ed8-1ea090fcb6ea"],
  "action": "retrieve_batch"
}'

Artistic QR Tasks API 的主要功能是通过输入 Artistic QR Generation API 生成的任务ID来查询该任务的执行情况。

本文档将详细介绍 Artistic QR Tasks API 的对接说明，帮助您轻松集成并充分利用该 API 的强大功能。通过 Artistic QR Tasks API ，您可以轻松实现查询 Artistic QR Generation API 的任务执行情况。

申请流程

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

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

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

📘 完整文档：Artistic QR Generation API →

请求示例

Artistic QR Tasks API 可以用于查询 Artistic QR Generation API 一个 API 的结果。关于怎样使用 Artistic QR Generation API，请参考文档 Artistic QR Generation API 。

我们以 Artistic QR Generation API 服务返回的任务ID一个为例，演示如何使用该 API。假设我们有一个任务ID：e2c65b20-a970-431e-99c1-76721e799df8，接下来演示如何通过传入一个任务ID来。

任务示例图

设置请求头和请求体

Request Headers 包括：

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

Request Body 包括：

• id：上传的任务ID。
• action：对任务的操作方式。

设置如下图所示：

代码示例

可以发现，在页面右侧已经自动生成了各种语言的代码，如图所示：

部分代码示例如下：

CURL

1
2
3
4
5
6
7
8

curl -X POST 'https://api.acedata.cloud/qrart/tasks' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "id": "e2c65b20-a970-431e-99c1-76721e799df8",
  "action": "retrieve"
}'

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/qrart/tasks"

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

payload = {
    "id": "e2c65b20-a970-431e-99c1-76721e799df8",
    "action": "retrieve"
}

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

响应示例

请求成功后，API 将返回此处二维码任务的详情信息。例如：

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

{
  "_id": "668cb62c550a4144a582e372",
  "id": "e2c65b20-a970-431e-99c1-76721e799df8",
  "application_id": "3d25be99-4676-44d3-90bb-23086bc25300",
  "created_at": 1720497708.318,
  "credential_id": "6e80fca1-9a49-4507-ae8e-601dbd0ab3ca",
  "request": {
    "aspect_ratio": "1:1",
    "callback_url": null,
    "content": "https://platform.acedata.cloud",
    "content_image_url": null,
    "ecl": "H",
    "image_origin": null,
    "marker_shape": "square",
    "negative_prompt": null,
    "padding_level": 5,
    "padding_noise": 0,
    "pattern": "custom",
    "pixel_style": "square",
    "position": "center",
    "preset": "",
    "prompt": "mexican tacos",
    "qrw": 2,
    "ratio": null,
    "rotate": 0,
    "seed": null,
    "steps": 20,
    "sub_marker": "square",
    "timeout": null,
    "trace_id": "a99ecc24-eda0-45c6-bb5f-98060c30b490",
    "type": "link"
  },
  "response": {
    "image_url": "https://platform.cdn.acedata.cloud/qrart/e2c65b20-a970-431e-99c1-76721e799df8.png",
    "image_width": 768,
    "image_height": 768,
    "seed": 5324369603686616,
    "success": true
  }
}

返回结果一共有多个字段，request 字段就是发起任务时的 request body，同时response 字段是任务完成后返回的response body，其结果和 Artistic QR Generation API 的请求和返回一致。字段介绍如下。

• id，生成此二维码任务的 ID，用于唯一标识此次二维码生成任务。
• request，查询二维码任务中的请求信息。
• response，查询二维码任务中的返回信息。

批量查询操作

这是是针对多个二维码任务ID来进行查询二维码任务详情，与上面不同的是需要将action选中为retrieve_batch

Request Body 包括：

• ids：上传的任务ID数组。
• action：对任务的操作方式。

设置如下图所示：

代码示例

可以发现，在页面右侧已经自动生成了各种语言的代码，如图所示：

部分代码示例如下：

CURL

1
2
3
4
5
6
7
8

curl -X POST 'https://api.acedata.cloud/qrart/tasks' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "ids": ["8c89e97b-6a79-4406-b2ce-e00f92540b4e","e2c65b20-a970-431e-99c1-76721e799df8"],
  "action": "retrieve_batch"
}'

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/qrart/tasks"

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

payload = {
    "ids": ["8c89e97b-6a79-4406-b2ce-e00f92540b4e","e2c65b20-a970-431e-99c1-76721e799df8"],
    "action": "retrieve_batch"
}

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