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

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)

响应示例

请求成功后，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
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85

{
  "items": [
    {
      "_id": "668cb90e550a4144a5834557",
      "id": "8c89e97b-6a79-4406-b2ce-e00f92540b4e",
      "application_id": "3d25be99-4676-44d3-90bb-23086bc25300",
      "created_at": 1720498446.039,
      "credential_id": "b7f9aaa1-43d8-471f-a826-cd0f4733fec5",
      "request": {
        "aspect_ratio": "1:1",
        "callback_url": null,
        "content": "https://huyinfu.space",
        "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": "44d33486-0527-451f-afc2-df11aab7e049",
        "type": "link"
      },
      "response": {
        "image_url": "https://platform.cdn.acedata.cloud/qrart/8c89e97b-6a79-4406-b2ce-e00f92540b4e.png",
        "image_width": 768,
        "image_height": 768,
        "seed": 2701847236953402,
        "success": true
      }
    },
    {
      "_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
      }
    }
  ],
  "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"
}

结论

通过本文档，您已经了解了如何使用 Artistic QR Tasks API 进行查询单个或批量二维码任务的所有具体详情信息。希望本文档能帮助您更好地对接和使用该 API。如有任何问题，请随时联系我们的技术支持团队。

Claude Code 原生通过 ANTHROPIC_BASE_URL 与 ANTHROPIC_AUTH_TOKEN 两个环境变量决定请求发往哪里，把它们指向 Ace Data Cloud 即可用更低的价格、无需 Anthropic 官方订阅来使用 Claude Code。手动编辑 .claude/settings.json 对新手并不友好，而 CC Switch 提供了一个图形界面，帮你把这两个变量一键写好、并在多套供应商之间即时切换。

本文介绍如何用 CC Switch 把 Claude Code 接入 Ace Data Cloud。

什么是 CC Switch

CC Switch（官网 ccswitch.io）是一个开源、跨平台的桌面端配置管理器，用于统一管理 Claude Code、Claude Desktop、Codex、Gemini CLI、OpenCode、OpenClaw、Hermes 等多个 AI 编程工具的供应商配置。它基于 Tauri 2 构建，采用 MIT 协议开源，在 GitHub 上已获得超过 11 万 Star（参见 farion1231/cc-switch）。

它的核心价值在于（详见官方 User Manual）：

• 免手动改配置：不用再手写 settings.json / config.toml / .env，图形界面填一次即可。
• 一键切换：预存多套供应商，从主界面或系统托盘即时切换。
• 原子写入：所有数据存于本地 SQLite 数据库（~/.cc-switch/cc-switch.db），采用「临时文件 + 重命名」的原子写入，避免配置损坏。

CC Switch 的工作原理是在底层动态覆盖 Claude Code 的 ANTHROPIC_BASE_URL 和 ANTHROPIC_AUTH_TOKEN，把原本发往 Anthropic 官方的请求重定向到你配置的第三方接口（本例即 Ace Data Cloud）。这一机制在社区的图文教程中也有详细说明。

CC Switch 官方主界面与「添加供应商」面板如下（截图来自 CC Switch 官方仓库）：

申请 API Token

要使用 Claude Code，首先到 Ace Data Cloud 控制台，获取你的 API Token，留作备用。

如果你尚未登录或注册，会自动跳转到登录页面邀请你注册和登录，登录注册之后会自动返回当前页面。首次申请时会有免费额度赠送，可以免费体验 Claude Code 服务。

提示：也可以前往 Claude Messages 服务页面 点击「Acquire」获取凭证，即赠免费额度；额度不足时可在 控制台 - 通用余额 充值。

下载与安装 CC Switch

前往 CC Switch 的 Releases 页面（或直接下载最新版本），按操作系统选择对应安装包。以下安装方式均来自官方 README：

安装完成后启动 CC Switch，准备添加供应商。

首次启动时，CC Switch 可以把你已有的 CLI 配置导入为默认供应商（参见官方 Quick Start），避免覆盖原有配置。

添加 Ace Data Cloud 供应商

CC Switch 内置了 50+ 供应商预设，但目前不含 Ace Data Cloud，因此我们使用「Custom（自定义）」方式添加。以下步骤对应官方文档 2.1 Add Provider。

1. 在 CC Switch 顶部切换到 Claude Code 应用。
2. 点击右上角的 +（Add Provider）按钮打开添加面板，在 App-specific Provider 标签下操作。
3. 在预设下拉框中选择 Custom，然后填写配置。

CC Switch 官方「添加供应商」面板如下（截图来自 CC Switch 官方仓库）：

按如下信息填写：

选择 Custom 后，也可以直接在 JSON 编辑框中填入 Claude 配置。Ace Data Cloud 提供原生兼容 Anthropic Messages API 的代理，因此使用默认的 ANTHROPIC_* 环境变量即可（配置格式参见官方 Claude Configuration Format）：

1
2
3
4
5
6

{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "{token}",
    "ANTHROPIC_BASE_URL": "https://api.acedata.cloud"
  }
}

其中 {token} 替换为你在 Ace Data Cloud 控制台复制的 API Token。核对无误后点击 Add 完成添加。

API 格式（Advanced Options）：Ace Data Cloud 使用原生 Anthropic Messages 协议，因此高级选项中的 API Format 保持默认的 Anthropic Messages 即可，无需开启本地路由或格式转换。

启用并切换供应商

添加完成后，在 Claude Code 供应商列表中找到 Ace Data Cloud 卡片，点击 Enable（启用） 即可（参见官方 2.2 Switch Provider）。你也可以从系统托盘菜单直接点击供应商名称进行即时切换，无需打开完整界面。

是否需要重启？ 根据官方 FAQ，Claude Code 支持「热切换」——切换供应商后无需重启即可生效；其余大多数工具（如 Codex、Gemini CLI）则需要重启对应 CLI 或终端。

CC Switch 启用供应商时，会把上面的配置写入 Claude Code 的配置文件（用户级 ~/.claude/settings.json）。因此，无论你在终端里运行 claude，还是使用 VS Code 的 Claude Code 扩展，都会读取到同一份配置。配置文件的位置与格式参见官方 5.1 配置文件说明。

在终端与 VS Code 中使用

CC Switch 只负责写入配置，Claude Code 本体仍需单独安装。启用供应商后：

• 终端 CLI：安装并运行 claude 即可，完整步骤见 Claude Code 终端配置教程。进入交互界面后输入 /status，应能看到 Anthropic base URL: https://api.acedata.cloud。

  

• VS Code 扩展：在扩展市场安装 Claude Code 扩展，完整步骤见 Claude Code VS Code 配置教程。由于扩展和 CLI 共享同一份配置，CC Switch 写好后 VS Code 扩展会直接复用，无需再手动填写。

• GitHub Actions：如果你想在 CI/CD 中使用，参见 Claude Code GitHub Actions 配置教程（该场景通过 Secrets 注入变量，通常不使用 CC Switch）。

远程开发（Remote - SSH）

如果你通过 VS Code Remote - SSH 在远程服务器上开发，远程端读不到你本机的环境变量。此时可以借助 CC Switch 的本地代理（Local Proxy）功能：在 CC Switch 中开启本地代理后，它会在本机监听一个端口并转发请求；再通过 SSH 的 RemoteForward 把该端口转发到远程主机，远程的 Claude Code 即可复用本地供应商。本地代理的配置说明见官方 4.1 Proxy Service，Remote - SSH 的完整图文步骤可参考社区教程 Golden-Promise/vscode-cc-switch。

查看额度与用量

• 通过 Ace Data Cloud 控制台 - 应用列表 查看当前账户的剩余额度。
• 通过 Ace Data Cloud 控制台 - 使用历史 查看所有请求记录与扣费详情。

常见问题

• 为什么无法删除当前正在使用的供应商？ CC Switch 遵循「最小侵入」原则，始终保留一个已启用配置，避免删除全部配置后 CLI 工具无法使用。详见官方 FAQ。
• 如何切回官方登录？ 从预设列表添加一个官方登录（Official Login）供应商，切换后按照官方登录 / OAuth 流程操作即可（参见官方 Quick Start）。
• 配置数据存在哪里？ 供应商、MCP、Prompts、Skills 等数据存于 ~/.cc-switch/cc-switch.db（SQLite），设备级 UI 偏好存于 ~/.cc-switch/settings.json，自动备份位于 ~/.cc-switch/backups/（参见官方 FAQ）。

参考来源

• CC Switch 项目仓库：https://github.com/farion1231/cc-switch
• CC Switch 官网：https://ccswitch.io/
• CC Switch 用户手册：https://github.com/farion1231/cc-switch/blob/main/docs/user-manual/en/README.md
• 添加供应商（2.1 Add Provider）：https://github.com/farion1231/cc-switch/blob/main/docs/user-manual/en/2-providers/2.1-add.md
• 切换供应商（2.2 Switch Provider）：https://github.com/farion1231/cc-switch/blob/main/docs/user-manual/en/2-providers/2.2-switch.md
• 本地代理（4.1 Proxy Service）：https://github.com/farion1231/cc-switch/blob/main/docs/user-manual/en/4-proxy/4.1-service.md
• 社区图文教程（VS Code + cc-Switch）：https://github.com/Golden-Promise/vscode-cc-switch
• Claude Code 官方 VS Code 文档：https://code.claude.com/docs/en/vs-code
• Ace Data Cloud Claude Messages 服务：https://platform.acedata.cloud/documents/claude-messages

📘 Overview：Claude Desktop MCP Overview →

Fish Audio 是高保真 TTS 引擎，支持自定义音色、多种采样率和格式（mp3 / wav / opus）。模型可选 s1 / s2-pro，延迟可控。

配置 Claude Desktop

claude.ai 网页版和 Claude Desktop 都支持远程 MCP Connector：

1. 打开 https://claude.ai/customize/connectors（或 Claude Desktop 的 Settings → Connectors）。

2. 点击 Add custom connector，Name 填 fish 或 Fish，URL 填：

   1	https://fish.mcp.acedata.cloud/mcp

3. 首次连接会跳转到 AceData Cloud 完成 OAuth 授权，确认后即可在对话中调用。

Fish 语音 能做什么？

Fish Audio 是高保真 TTS 引擎，支持自定义音色、多种采样率和格式（mp3 / wav / opus）。模型可选 s1 / s2-pro，延迟可控。

把它接到 Claude.ai 或 Claude Desktop，下面这些场景都能直接在对话里完成：

• 用 fish_generate_audio 把这段中文合成成 mp3，用默认音色

• 把这段英文合成成 wav，采样率 44100，使用音色 ID xxxx

• 把这段播客脚本合成成 mp3，bitrate 128，低延迟模式

注意事项

• 远程 MCP 计费在 AceData Cloud 端按调用扣费，首次注册会送免费额度。
• OAuth 授权后，Connector 会绑定到你授权时使用的 AceData Cloud 账号。
• 一个 AceData Cloud 账号可以授权所有 MCP Connector，无需为 Fish 语音 单独申请额度。

工具

相关链接

• Fish Audio MCP Server（GitHub）
• Fish Audio MCP on PyPI
• Claude Desktop MCP Overview
• MCP 协议官网

查询由 POST /maestro/videos 创建的视频任务的状态与结果。轮询免费,不消耗积分。

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

查询单个任务

1
2
3
4

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

返回(每种语言对应一个 variant):

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

{
  "id": "f57e99c4f60f4373a15517742ce2357d",
  "status": "succeeded",
  "elapsed": 312,
  "request": { "prompt": "…", "langs": ["zh-cn", "en"], "aspect": "9:16", "duration": 20 },
  "response": {
    "success": true,
    "data": {
      "variants": [
        { "lang": "zh-cn", "aspect": "9:16", "kind": "video", "title": "什么是向量数据库", "output_url": "https://…/zh.mp4" },
        { "lang": "en", "aspect": "9:16", "kind": "video", "title": "What is a vector database", "output_url": "https://…/en.mp4" }
      ],
      "project": { "tarball_url": "https://…/project.tar.gz", "outputs": ["https://…/zh.mp4", "https://…/en.mp4"] },
      "progress": [ { "stage": "producing", "message": "rendering scene 2", "pct": 60, "t": 1750000000 } ],
      "stage": "succeeded"
    }
  }
}