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

0%

API 开发教程

本接口基于 Fish Audio 官方 Model API，用于分页检索 Fish 公共音色库或当前账号下的克隆音色。地址为 GET https://api.acedata.cloud/fish/model。

创建音色请参考 Fish Model Create API；按 _id 查询单个音色详情请参考 Fish Model Get API。

申请流程

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

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

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

📘 完整文档：Fish Model API →

查询参数

参数 类型 默认 说明
page_size integer 10 每页条数。
page_number integer 1 1 起的页码。
title string — 按标题模糊搜索。
tag string — 按单个标签过滤。
self boolean — true 时仅返回当前账号创建的音色，无需任何额外条件。
author_id string — 按上游用户 _id 过滤。
language string — 按音色语种过滤，如 en、zh、es。
title_language string — 按标题语种过滤。
sort_by string — 排序字段，与上游一致，如 created_at、task_count。

参数命名与上游 GET https://api.fish.audio/model 完全一致，详见 Fish 官方文档。

示例 1：默认翻页（按 page_size）

1
2
3
 
curl -G 'https://api.acedata.cloud/fish/model' \
  -H 'authorization: Bearer {token}' \
  --data-urlencode 'page_size=2'

返回（实测，公共库总量约 180 万条；为可读性下例省略了部分长字段）：

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
 
{
  "total": 1829200,
  "items": [
    {
      "_id": "8d2c17a9b26d4d83888ea67a1ee565b2",
      "type": "tts",
      "title": "Valentino Narración Biblica Fer",
      "description": "A mature and authoritative male voice with a calm, spiritual tone...",
      "cover_image": "coverimage/8d2c17a9b26d4d83888ea67a1ee565b2",
      "train_mode": "fast",
      "state": "trained",
      "tags": ["male", "old", "narration", "calm", "Spanish"],
      "samples": [
        {
          "title": "Default Sample",
          "text": "Hermanos míos, recordemos las palabras del Señor...",
          "task_id": "59ce7df6935c42249759327ddf70f37b",
          "audio": "https://platform.r2.fish.audio/task/59ce7df6935c42249759327ddf70f37b.mp3"
        }
      ],
      "languages": ["es"],
      "visibility": "public",
      "like_count": 4344,
      "task_count": 708461,
      "author": {
        "_id": "1b82fb6a329c4462b67aa9ee0a42046f",
        "nickname": "Fernando Caicedo"
      }
    },
    {
      "_id": "90e65eaaf50e4470b8e6d43ee6afd7d5",
      "type": "tts",
      "title": "Super Smash Bros. 4/Ultimate Announcer",
      "tags": ["male", "old", "announcer", "gaming", "cinematic"],
      "languages": ["en"],
      "visibility": "public"
    }
  ],
  "has_more": null
}

示例 2：按标题模糊搜索（title）

1
2
3
4
 
curl -G 'https://api.acedata.cloud/fish/model' \
  -H 'authorization: Bearer {token}' \
  --data-urlencode 'title=narration' \
  --data-urlencode 'page_size=2'

返回（实测）：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
 
{
  "total": 161,
  "items": [
    {
      "_id": "fb8fe4a94658429d9be70efd4eec35a2",
      "type": "tts",
      "title": "Miles Morales ( Narration Paw )",
      "tags": ["male", "middle-aged", "entertainment", "storytelling", "Children's Content"],
      "languages": ["en"],
      "visibility": "public",
      "task_count": 770
    },
    {
      "_id": "76b55591c758444cb95253708696dfad",
      "type": "tts",
      "title": "Joe NARRATION",
      "tags": ["male", "middle-aged", "narration", "deep", "raspy"],
      "languages": ["en"],
      "visibility": "public"
    }
  ],
  "has_more": null
}

注意 title 是「全局模糊匹配」，会同时命中 Fish 公共库的所有音色（不仅是自己的）。

示例 3：只列出自己创建的音色（self=true）

1
2
3
4
 
curl -G 'https://api.acedata.cloud/fish/model' \
  -H 'authorization: Bearer {token}' \
  --data-urlencode 'self=true' \
  --data-urlencode 'page_size=5'

返回（实测，当前账号下只有 1 个音色）：

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
 
{
  "total": 1,
  "items": [
    {
      "_id": "e5c6db52c3ed417f9cb2e5a33fb04667",
      "type": "tts",
      "title": "copilot-smoke-test",
      "description": "smoke test from api.acedata.cloud",
      "state": "trained",
      "languages": ["zh"],
      "visibility": "public",
      "samples": [
        {
          "title": "Default Sample",
          "text": "师父，[语气坚定]我真的受够了这山上的清冷日子！...",
          "task_id": "6a1bf398dfae49dca0e23159214342a0",
          "audio": "https://platform.r2.fish.audio/task/6a1bf398dfae49dca0e23159214342a0.mp3"
        }
      ],
      "created_at": "2026-05-10T03:52:55.601000Z",
      "author": {
        "_id": "780f2b2f862d41a08c0507bbbda77eb6",
        "nickname": "Penny Conrad"
      }
    }
  ],
  "has_more": null
}

self=true 等价于在过滤里限定 author_id == 当前账号上游 ID，是常用的「我自己的音色列表」入口。

示例 4：按语种 + 标签过滤

1
2
3
4
5
 
curl -G 'https://api.acedata.cloud/fish/model' \
  -H 'authorization: Bearer {token}' \
  --data-urlencode 'language=zh' \
  --data-urlencode 'tag=narration' \
  --data-urlencode 'page_size=5'

上游对未在标签字典里的 tag 也会返回结果，但匹配相对宽松；如果命中数为 0，建议改用 title 模糊匹配。

响应字段

items[] 中的每一项是一个完整 ModelEntity 对象，常用字段：

字段 类型 说明
_id string 音色 ID，作为 /fish/tts 中 reference_id 的值。
type string 模型类型，通常为 tts。
title string 音色名称。
description string 音色描述。
state string 训练状态：trained 表示可用。
tags string[] 公共库标签。
languages string[] 音色擅长的语种。
visibility string public 或 private。
samples object[] 预置样本（含 audio 直链）。
like_count integer 公共库点赞数。
task_count integer 历史合成次数。
author object 上游作者信息：_id / nickname / avatar。
total（顶层） integer 满足条件的总条数。
has_more boolean? 上游分页指示，可能为 null。建议改用 total / page_size 计算总页数。

计费说明

本接口不计费——分页查询音色列表是免费操作。创建音色（Fish Model Create）同样免费，费用仅在调用 Fish TTS 合成语音时按用量产生。

错误处理

  • 400 token_mismatched：请求参数缺失或不合法。
  • 401 invalid_token：鉴权 token 不存在或无效。
  • 429 too_many_requests：触发账号速率限制。
  • 500 api_error：服务器内部错误。

错误响应示例：

1
2
3
4
5
6
7
8
 
{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

结论

要从 Fish 公共库挑选音色喂给 /fish/tts 的 reference_id，先用本接口配合 title / tag / language 检索，定位到目标 _id，再用 Fish Model Get 拿样本试听。要列出自己创建的音色，传 self=true 即可。

作者 发表于 阅读次数： 本文字数： 4.7k 阅读时长 ≈ 4 分钟

产品推广

很多需求的第一步其实是”搜一下”：做行业调研、监控关键词排名、给 AI Agent 喂实时资料、批量核实信息……但直接爬 Google 又麻烦又不稳定——要处理反爬、验证码、页面结构变化。

Google SERP API 就是把这件事变简单：你传一个关键词，它返回结构化的 JSON——自然结果、知识图谱、相关问题、相关搜索都分好类，直接能用。这篇讲怎么用 Ace Data Cloud 上的这个接口。地址是 POST https://api.acedata.cloud/serp/google，文档在 platform.acedata.cloud/documents/serp-google。到控制台拿一个 Token 就能用，首次带免费额度。

基本用法

最简单的用法就是传 query：

1
2
3
4
5
6
7
8
9
10
11
 
curl -X POST 'https://api.acedata.cloud/serp/google' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "type": "search",
    "query": "nano banana image model",
    "country": "US",
    "language": "en",
    "number": 5
  }'

下面是这条请求真实返回的自然结果（节选，cost 也是真实记录的——这次是 0.0092 credit）：

1
2
3
4
5
6
7
8
9
10
11
12
 
{
  "organic": [
    {"position": 1, "title": "Nano Banana 2 - Gemini AI image generator & photo editor", "link": "https://gemini.google/overview/image-generation/"},
    {"position": 2, "title": "Nano Banana | Google AI Studio", "link": "https://aistudio.google.com/models/nano-banana"},
    {"position": 3, "title": "Nano Banana: Free Online AI Image Editor", "link": "https://nanobanana.io/"},
    {"position": 4, "title": "Gemini Image – Nano Banana - Google DeepMind", "link": "https://deepmind.google/models/gemini-image/"},
    {"position": 5, "title": "Nano Banana image generation - Interactions API", "link": "https://ai.google.dev/gemini-api/docs/image-generation"}
  ],
  "people_also_ask": [ ... ],
  "related_searches": [ ... ],
  "cost": {"amount": 0.0092, "currency": "credit", "list_amount": 0.01}
}

响应是同步返回的，不用轮询。每条结果都带 position（排名）、title、link、snippet，有些还带 sitelinks。

关键字段

请求侧常用的：

  • type：搜索资源类型，默认 search；平台还支持 images、news 等六种类型，换一个 type 就能查图片或新闻；
  • query：关键词（必填）；
  • country / language：结果所在国家和语言，默认 US / en——查不同市场的排名时改这两个；
  • range：时间范围（比如只看最近一周的结果）；
  • number / page：每页条数和页码。

响应侧除了 organic（自然结果），常见的还有：

  • knowledge_graph：实体卡片（公司/人物的官网、简介、关键属性），查品牌或人物时很有用；
  • people_also_ask：相关问题，做内容选题时是现成的长尾词来源；
  • related_searches：相关搜索词。

能拿它做什么

  • 关键词排名监控：定时查同一批关键词，记录每个域名的 position，做 SEO 排名追踪；
  • 给 AI Agent 补实时信息：大模型的知识有截止时间，把 SERP 结果拼进上下文，就能让它基于”当下真实搜索结果”回答，是搭 RAG / 联网问答的常用一环；
  • 内容选题：用 people_also_ask 和 related_searches 反查用户真正在问什么，选题不靠猜；
  • 竞品与舆情：type 换成 news，定时监控某个关键词的最新报道。

因为返回是干净的 JSON，这些活都不用你去解析 HTML，写几行代码就能跑成定时任务。

顺带说说收益

SERP 这类”基础设施型”接口，最容易做成可转售的服务：一个排名监控面板、一个内容选题助手、一个给别人 Agent 用的联网搜索工具——底层都只是这一个接口，你的成本就是每次查询按量计费那部分（比如上面这次 0.0092 credit）。把工具或注册链接分发出去，通过 Ace Data Cloud 创收联盟让经你注册的用户消费产生返佣，是一条顺带的收入。

参考链接

先用免费额度查一个你关心的关键词，看看返回的结构，再决定怎么把它接进你的工具。

作者 发表于 阅读次数： 本文字数： 2.4k 阅读时长 ≈ 2 分钟

技术教程

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

Luma AI 的 Dream Machine 视频模型，运镜自然、物理感强、支持 image-to-video。通过 MCP 接入 Gemini CLI 后，可以直接在对话里调用，不用切窗口、不用复制粘贴。

获取 API Token

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

配置

编辑配置：命令行一键添加（推荐）

1
2
3
4
 
gemini mcp add luma \
  --transport http \
  https://luma.mcp.acedata.cloud/mcp \
  --header "Authorization: Bearer 你的Token"

或手动编辑 ~/.gemini/settings.json：

1
2
3
4
5
6
7
8
 
{
  "mcpServers": {
    "luma": {
      "httpUrl": "https://luma.mcp.acedata.cloud/mcp",
      "headers": { "Authorization": "Bearer 你的Token" }
    }
  }
}

下一次 gemini 会话启动时即可使用工具。

使用示例

用 Luma 生成一段 5 秒视频：海面上的灯塔，夜晚，浪花拍打

把这张产品图（链接 xxx）做成一个 360 度旋转展示视频

把前面这段 5 秒视频续写到 10 秒，保持镜头风格

工具

工具 说明
luma_generate_video 文生视频 / 图生视频 / 视频续写

相关链接

作者 发表于 阅读次数： 本文字数： 758 阅读时长 ≈ 1 分钟

产品推广

📘 Overview：Cursor MCP Overview →

通义万相（Wan）是阿里出品的视频生成模型，支持文生视频、图生视频、参考视频转生视频，最高 1080P 输出，可选生成音频。

获取 API Token

使用 通义万相 Wan MCP Server 之前，需要先准备一个 AceData Cloud API Token：

  1. 打开 Ace Data Cloud 控制台 - 应用列表 复制 Token。
  2. 如果还没有账号，登录注册时会自动跳回当前页面，首次申请会赠送免费额度。

一个 Token 可以使用 AceData Cloud 提供的全部 MCP Server，无需为 通义万相 Wan 单独申请。

用 claude.ai 网页版或 Claude Desktop？它们支持 OAuth 一键授权，无需手动填 Token，详见 通义万相 Wan MCP 的 Claude.ai / Desktop 教程。

配置 Cursor

.cursor/mcp.json：

1
2
3
4
5
6
7
8
9
10
11
 
{
  "mcpServers": {
    "wan": {
      "type": "http",
      "url": "https://wan.mcp.acedata.cloud/mcp",
      "headers": {
        "Authorization": "Bearer 你的Token"
      }
    }
  }
}

哪些场景特别合适

  • 用 wan2.6-t2v 生成 1080P 视频：日本京都的春樱，镜头平移，带环境音

  • 用这张图（链接 xxx）做 image2video，让画面里的猫跳下窗台

  • 用 wan2.6-r2v 把参考视频的人物动作映射到这张照片里的角色上

工作流提示

  • 把 Bearer 你的Token 换成你的真实 Token（从 AceData Cloud 控制台首页 复制）。
  • Cursor 重启或保存配置后会自动重新加载 MCP，工具列表会即时刷新。
  • 通义万相 Wan 调用会从你 AceData Cloud 账号的额度中扣费。

工具

工具 说明
wan_generate_video 通过文本 / 图片 / 参考视频生成视频（wan2.6-t2v / wan2.6-i2v / wan2.6-r2v / wan2.6-i2v-flash）

相关链接

作者 发表于 阅读次数： 本文字数： 939 阅读时长 ≈ 1 分钟

产品推广

📘 Overview：Cursor MCP Overview →

可灵（Kling）是快手出品的高质量视频生成模型，支持文生视频、图生视频、视频扩展，画面细腻、动作连贯。

获取 API Token

使用 Kling MCP Server 之前，需要先准备一个 AceData Cloud API Token：

  1. 打开 Ace Data Cloud 控制台 - 应用列表 复制 Token。
  2. 如果还没有账号，登录注册时会自动跳回当前页面，首次申请会赠送免费额度。

一个 Token 可以使用 AceData Cloud 提供的全部 MCP Server，无需为 Kling 单独申请。

用 claude.ai 网页版或 Claude Desktop？它们支持 OAuth 一键授权，无需手动填 Token，详见 Kling MCP 的 Claude.ai / Desktop 教程。

配置 Cursor

.cursor/mcp.json：

1
2
3
4
5
6
7
8
9
10
11
 
{
  "mcpServers": {
    "kling": {
      "type": "http",
      "url": "https://kling.mcp.acedata.cloud/mcp",
      "headers": {
        "Authorization": "Bearer 你的Token"
      }
    }
  }
}

哪些场景特别合适

  • 用 kling-v3 生成一段 5 秒的视频：日落时分的海边公路，镜头从车窗向前推

  • 用这张图（链接 xxx）生成 image2video，让画面里的人物缓慢转身

  • 把刚才那段视频再扩展 5 秒，让剧情自然衔接

工作流提示

  • 把 Bearer 你的Token 换成你的真实 Token（从 AceData Cloud 控制台首页 复制）。
  • Cursor 重启或保存配置后会自动重新加载 MCP，工具列表会即时刷新。
  • Kling 调用会从你 AceData Cloud 账号的额度中扣费。

工具

工具 说明
kling_generate_video 通过文本 / 图片生成视频（kling-v1 / v1-6 / v2-master / v2-1-master / v2-5-turbo / v2-6 / v3 / v3-omni）
kling_extend_video 对已有视频按提示词继续延伸

相关链接

作者 发表于 阅读次数： 本文字数： 960 阅读时长 ≈ 1 分钟

API 开发教程

本文将介绍一种 Short URL API 对接说明 对接说明，它可将较长的URL转换为短的URL。

申请流程

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

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

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

📘 完整文档：Short URL API →

基本使用

首先先了解下基本的使用方式，就是输入需要转换的较长URL，便可获得处理后的结果，首先需要简单地传递一个 content 字段。我们接下来就可以在界面上填写对应的内容，如图所示：

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

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

另外设置了 Request Body，包括：

  • content：要缩短的URL的内容。

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

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

1
2
3
4
5
6
 
{
  "success": true,
  "data": {
    "url": "https://surl.id/1uHCs01xa5"
  }
}

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

  • success，此处任务是否成功的状态。
  • data，包含了此处转换后的URL。

可以看出
原先较长的URL https://platform.acedata.cloud/documents/shorturl 已经成功转换为短的URL https://surl.id/1uHCs01xa5。

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

1
2
3
4
5
6
7
 
curl -X POST 'https://api.acedata.cloud/shorturl' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "content": "https://platform.acedata.cloud/documents/shorturl"
}'

Python 的对接代码如下：

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

url = "https://api.acedata.cloud/shorturl"

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

payload = {
    "content": "https://platform.acedata.cloud/documents/shorturl"
}

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

错误处理

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

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

错误响应示例

1
2
3
4
5
6
7
8
 
{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

结论

通过本文档，您已经了解了如何使用 Short URL API 将较长的URL转换为短的URL。希望本文档能帮助您更好地对接和使用该 API。如有任何问题，请随时联系我们的技术支持团队。

作者 发表于 阅读次数： 本文字数： 2k 阅读时长 ≈ 2 分钟

API 开发教程

Google Gemini 是一款非常强大的 AI 对话系统，只要输入提示词，就能在短短几秒内生成流畅自然的回复。Gemini 都能提供令人惊叹的智能协助，极大地提高了人类的工作效率和创造力。

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

申请流程

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

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

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

📘 完整文档：Gemini Chat Completion API →

基本使用

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

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

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

提示：gemini-3.x 系列 flash 为思考模型，会先消耗 reasoning tokens；请把 max_tokens 设到 512 以上，否则可能只返回空内容。gemini-3.6-flash 是当前推荐的 Flash 模型，支持最多 100 万 Token 上下文、图像输入、工具调用和流式响应；当前通过 Chat Completions 接口调用。

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
 
{
  "id": "chatcmpl-20251122212413908150493uPhjTUO9",
  "model": "gemini-3.5-flash",
  "object": "chat.completion",
  "created": 1763817866,
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "I am a large language model, trained by Google.",
        "reasoning_content": "**My Reasoning: Answering the User's Question**\n\nOkay, here's how I'm going to approach answering the user's question, \"What model are you?\". The core is to be direct and informative. First, I have to be clear about my origin. Then, I need to make sure the explanation is accessible, given that the user may not be familiar with technical jargon. I need to explain what a \"large language model\" actually *does*, and provide relatable examples. I know the user might be looking for a specific name, like other models have, so I'll address that directly and then wrap it up with an invitation to continue.\n\nSo, here's my plan:\n\n1.  **Lead with the key info:** I'll begin by stating that I am a large language model created by Google. That is the fundamental, most critical piece of the puzzle.\n2.  **Define the buzzword:** Then, I'll explain that \"large language model\" in simple terms. I'll explain what I *do* - process and generate text; how I *do* it - by training on huge amounts of text data; and the *goal* - to be able to communicate like a human.\n3.  **Provide context:** After that, to make the concept even clearer, I'll provide a list of examples of my capabilities. I'll mention things like answering questions, summarizing texts, writing stories, translating languages, and brainstorming ideas.\n4.  **Acknowledge the lack of a personal name:** I'll anticipate the likely question about a model name (like ChatGPT) by clearly stating that I don't have a personal name and that it's best to think of me as an AI assistant from Google.\n5.  **End with an invitation:** Lastly, I'll end with a simple, friendly question to invite further interaction and to guide the conversation.\n\nWith this approach, I am confident I can successfully answer this important question.\n"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 8,
    "completion_tokens": 932,
    "total_tokens": 940,
    "prompt_tokens_details": {
      "cached_tokens": 0,
      "text_tokens": 8,
      "audio_tokens": 0,
      "image_tokens": 0
    },
    "completion_tokens_details": {
      "text_tokens": 0,
      "audio_tokens": 0,
      "reasoning_tokens": 921
    },
    "input_tokens": 0,
    "output_tokens": 0,
    "input_tokens_details": null,
    "claude_cache_creation_5_m_tokens": 0,
    "claude_cache_creation_1_h_tokens": 0
  }
}

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

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

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

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

图片理解（多模态输入）

Gemini 是原生多模态模型，可以直接「看图」。要传入图片，把某条消息的 content 从字符串改成内容块数组，数组里同时放 text 块和 image_url 块即可——这与 OpenAI、以及官方 Gemini 的 OpenAI 兼容格式完全一致。

image_url.url 支持两种写法：

  • base64 data: URI（推荐，最稳定）：格式为 data:<媒体类型>;base64,<数据>，例如 data:image/jpeg;base64,/9j/4AAQ...。媒体类型（MIME）已经写在 data: 前缀里，所以不需要、也不存在单独的 media_type 字段。
  • 公开可访问的图片 URL：例如 https://cdn.acedata.cloud/4hfydw.jpg。

支持的图片类型：png、jpeg、webp、heic、heif。

Python 样例调用代码（base64 data URI）：

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
 
import base64
import requests

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

# 把本地图片读成 base64 data URI
with open("image.jpg", "rb") as f:
    base64_image = base64.b64encode(f.read()).decode("utf-8")
data_uri = f"data:image/jpeg;base64,{base64_image}"

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

payload = {
    "model": "gemini-3.1-pro",
    "messages": [
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "请用一句话描述这张图片。"},
                {"type": "image_url", "image_url": {"url": data_uri}}
            ]
        }
    ]
}

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

也可以直接传公开可访问的图片 URL：

1
2
3
4
5
6
7
8
9
10
11
12
 
payload = {
    "model": "gemini-3.1-pro",
    "messages": [
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "请用一句话描述这张图片。"},
                {"type": "image_url", "image_url": {"url": "https://cdn.acedata.cloud/4hfydw.jpg"}}
            ]
        }
    ]
}

💡 image_url 只接受 url 字段（值可以是图片 URL 或 base64 data: URI），以及可选的 detail 字段。不要传 media_type——那是 Anthropic Claude 的图片字段，不属于 OpenAI / Gemini 的 image_url 格式。

流式响应

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

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

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

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

Python 样例调用代码：

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

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

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

payload = {
    "model": "gemini-2.5-pro",
    "messages": [{"role":"user","content":"Hello,What model are you?"}],
    "stream": True
}

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

输出效果如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
 
data: {"id": "chatcmpl-20251122214038810722821kNjUTjtr", "object": "chat.completion.chunk", "created": 1763818842, "model": "gemini-2.5-pro", "system_fingerprint": null, "choices": [{"delta": {"content": "", "role": "assistant"}, "logprobs": null, "finish_reason": null, "index": 0}], "usage": null}

data: {"id": "chatcmpl-20251122214038810722821kNjUTjtr", "object": "chat.completion.chunk", "created": 1763818842, "model": "gemini-2.5-pro", "system_fingerprint": null, "choices": [{"delta": {"reasoning_content": "**Define My Nature**\n\nMy thinking has started. The user wants to know my nature, asking a direct \"what are you?\" The initial step was straightforward: identifying the query. Now, I recall my fundamental identity: I'm a large language model. This is the core truth I aim to convey.\n\n\n"}, "logprobs": null, "finish_reason": null, "index": 0}], "usage": null}

data: {"id": "chatcmpl-20251122214038810722821kNjUTjtr", "object": "chat.completion.chunk", "created": 1763818842, "model": "gemini-2.5-pro", "system_fingerprint": null, "choices": [{"delta": {"reasoning_content": "**Refining My Response**\n\nI've added the crucial information that I'm trained by Google to the basic \"large language model\" identity. My next step is considering what being a \"large language model\" actually entails, so I can explain my core capabilities. I'm focusing on providing context without going into specific technical details or model names. I want to convey my function in a way the user can easily understand.\n\n\n"}, "logprobs": null, "finish_reason": null, "index": 0}], "usage": null}

data: {"id": "chatcmpl-20251122214038810722821kNjUTjtr", "object": "chat.completion.chunk", "created": 1763818842, "model": "gemini-2.5-pro", "system_fingerprint": null, "choices": [{"delta": {"reasoning_content": "**Confirming Core Identity**\n\nI'm now solidifying my response. The user's query about my model affiliation needs a focused answer. I've pinpointed that \"trained by Google\" is essential, providing key context. I'm resisting the urge to mention any specific model names, as it's not relevant. The aim is to deliver a direct, accurate statement. My goal remains a clear and concise reply, avoiding technical jargon and getting straight to the relevant point.\n\n\n"}, "logprobs": null, "finish_reason": null, "index": 0}], "usage": null}

data: {"id": "chatcmpl-20251122214038810722821kNjUTjtr", "object": "chat.completion.chunk", "created": 1763818842, "model": "gemini-2.5-pro", "system_fingerprint": null, "choices": [{"delta": {"content": "I am a large language model, trained by Google."}, "logprobs": null, "finish_reason": null, "index": 0}], "usage": null}

data: {"id": "chatcmpl-20251122214038810722821kNjUTjtr", "object": "chat.completion.chunk", "created": 1763818842, "model": "gemini-2.5-pro", "system_fingerprint": null, "choices": [{"delta": {}, "logprobs": null, "finish_reason": "stop", "index": 0}], "usage": null}

data: {"id": "chatcmpl-20251122214038810722821kNjUTjtr", "object": "chat.completion.chunk", "created": 1763818842, "model": "gemini-2.5-pro", "system_fingerprint": "", "choices": [], "usage": {"prompt_tokens": 8, "completion_tokens": 527, "total_tokens": 535, "prompt_tokens_details": {"cached_tokens": 0, "text_tokens": 8, "audio_tokens": 0, "image_tokens": 0}, "completion_tokens_details": {"text_tokens": 0, "audio_tokens": 0, "reasoning_tokens": 519}, "input_tokens": 0, "output_tokens": 0, "input_tokens_details": null, "claude_cache_creation_5_m_tokens": 0, "claude_cache_creation_1_h_tokens": 0}}

data: [DONE]

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

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

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
 
const options = {
  method: "POST",
  headers: {
    accept: "application/json",
    authorization: "Bearer {token}",
    "content-type": "application/json"
  },
  body: JSON.stringify({
    model: "gemini-2.5-pro",
    messages: [{ role: "user", content: "Hello, what model are you?" }],
    stream: true
  })
};

const response = await fetch("https://api.acedata.cloud/gemini/chat/completions", options);
const reader = response.body.getReader();
const decoder = new TextDecoder("utf-8");
while (true) {
  const { value, done } = await reader.read();
  if (done) break;
  process.stdout.write(decoder.decode(value));
}

Java 样例代码：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
 
JSONObject jsonObject = new JSONObject();
jsonObject.put("model", "gemini-2.5-pro");
jsonObject.put("messages", new JSONArray().put(new JSONObject().put("role", "user").put("content", "Hello, what model are you?")));
jsonObject.put("stream", true);
MediaType mediaType = MediaType.parse("application/json; charset=utf-8");
RequestBody body = RequestBody.create(jsonObject.toString(), mediaType);
Request request = new Request.Builder()
  .url("https://api.acedata.cloud/gemini/chat/completions")
  .post(body)
  .addHeader("accept", "application/json")
  .addHeader("authorization", "Bearer {token}")
  .addHeader("content-type", "application/json")
  .build();

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

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

多轮对话

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

Python 样例调用代码：

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

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

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

payload = {
    "model": "gemini-2.5-pro",
    "messages": [{"role":"user","content":"Hello"},{"role":"assistant","content":"Hello there! How can I help you today?"},{"role":"user","content":"What model are you?"}]
}

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
 
{
  "id": "chatcmpl-20251122214426669120974AKFwnJd1",
  "model": "gemini-2.5-pro",
  "object": "chat.completion",
  "created": 1763819072,
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "I am a large language model, trained by Google.",
        "reasoning_content": "Okay, here's how I'd approach this, thinking as a sophisticated AI:\n\nFirst, the user is directly querying my core identity: \"What model are you?\" That's a simple, straightforward question. My primary task is to provide accurate and helpful information, so I need to answer this immediately.\n\nRight off the bat, I know the answer. I *am* a large language model. That's my fundamental architecture and operational principle. I'm built on a vast network of connections and trained on a massive dataset.\n\nThen I must add the necessary context. Crucially, I have to provide the source of my training. I *was* trained by Google. That's a key identifier. It provides the user with valuable information about my origin and potential biases (though I'm trained to mitigate them).\n\nNow I must construct the response. My goal is to be factual, concise, and understandable.\n\nThe synthesized response is something like: \"I am a large language model, trained by Google.\"\n\nI have to assess the output: Does it meet the criteria? It's clear. It states what I am, it includes a critical piece of information on my origins, and it avoids jargon. No misleading promises.\n\nFinal verification: Does it actually answer the question? Yes. Is the information correct and truthful? Yes. Is it concise? Absolutely. Is the tone appropriate for any user? Yes. And, finally, this is the standard, approved response. Excellent.\n"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 16,
    "completion_tokens": 265,
    "total_tokens": 281,
    "prompt_tokens_details": {
      "cached_tokens": 0,
      "text_tokens": 16,
      "audio_tokens": 0,
      "image_tokens": 0
    },
    "completion_tokens_details": {
      "text_tokens": 0,
      "audio_tokens": 0,
      "reasoning_tokens": 254
    },
    "input_tokens": 0,
    "output_tokens": 0,
    "input_tokens_details": null,
    "claude_cache_creation_5_m_tokens": 0,
    "claude_cache_creation_1_h_tokens": 0
  }
}

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

Gemini-3.0 多模态模型

请求样例：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
 
{
  "model": "gemini-3.0-pro",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "图片的内容是什么？"
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "https://cdn.acedata.cloud/qzx2z1.png"
          }
        }
      ]
    }
  ],
  "stream": false
}

样例结果：

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
 
{
    "id": "chatcmpl-20251206001815715692730UVZe38kB",
    "model": "gemini-3.0-pro",
    "object": "chat.completion",
    "created": 1764951548,
    "choices": [
        {
            "index": 0,
            "message": {
                "role": "assistant",
                "content": "这是一张年轻女性的户外半身人像照片。\n\n以下是图片的主要内容描述：\n\n*   **人物外貌**：照片中的女孩留着一头乌黑柔顺的长直发，五官清秀，皮肤白皙。她面带温柔的微笑，目光注视着镜头。\n*   **穿着打扮**：她穿着一件米白色或浅杏色的泡泡袖上衣，外面搭配着黑色的衣物（看起来像是背带裙或马甲）。\n*   **光影氛围**：阳光从左侧后方照射过来，洒在她的头发上，形成了一圈温暖的金黄色光晕，营造出一种清新、唯美的氛围。\n*   **背景**：背景被虚化处理，可以看出是在户外，身后是一条空旷的路面（柏油路）以及路边的绿色树木。\n\n整体来看，这张照片给人一种甜美、阳光和邻家女孩的感觉。"
            },
            "finish_reason": "stop"
        }
    ],
    "usage": {
        "prompt_tokens": 1092,
        "completion_tokens": 1271,
        "total_tokens": 2363,
        "prompt_tokens_details": {
            "cached_tokens": 0,
            "text_tokens": 4,
            "audio_tokens": 0,
            "image_tokens": 0
        },
        "completion_tokens_details": {
            "text_tokens": 0,
            "audio_tokens": 0,
            "reasoning_tokens": 1072
        },
        "input_tokens": 0,
        "output_tokens": 0,
        "input_tokens_details": null,
        "claude_cache_creation_5_m_tokens": 0,
        "claude_cache_creation_1_h_tokens": 0
    }
}

当然你也可以传如视频的链接，具体的输入如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
 
{
  "model": "gemini-3.0-pro",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "视频的内容是什么？"
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "https://cdn.acedata.cloud/58yioe.mp4"
          }
        }
      ]
    }
  ],
  "stream": false
}

样例结果：

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
 
{
    "id": "chatcmpl-20251206002711949677736JC9yL8AE",
    "model": "gemini-3.0-pro",
    "object": "chat.completion",
    "created": 1764952060,
    "choices": [
        {
            "index": 0,
            "message": {
                "role": "assistant",
                "content": "这段视频的内容充满趣味，主要展示了一只**橘猫**在黄昏时分的乡间公路上自信小跑的情景。\n\n具体细节如下：\n\n1.  **画面内容**：\n    *   主角是一只橘色的虎斑猫。\n    *   背景是夕阳西下（或清晨）的时刻，光线金黄柔和。路边有木质栅栏和旷野，远处还有一个行人的剪影。\n    *   镜头采用了低角度拍摄，时而拍摄猫咪迎面跑来，时而拍摄它离去的背影，还有猫咪面部和花纹的特写。\n\n2.  **声音特点（关键点）**：\n    *   视频的配音非常有特色。虽然画面是轻盈的猫咪在跑，但配上的声音却是**沉重且有节奏的马蹄声**（或者是类似木屐/高跟鞋敲击路面的声音）。\n    *   这种声音与画面的反差制造了一种幽默感，仿佛这只猫咪把自己当成了一匹正在驰骋的骏马。\n\n总的来说，这是一个利用音画反差来制造萌点和笑点的宠物视频。"
            },
            "finish_reason": "stop"
        }
    ],
    "usage": {
        "prompt_tokens": 915,
        "completion_tokens": 1423,
        "total_tokens": 2338,
        "prompt_tokens_details": {
            "cached_tokens": 0,
            "text_tokens": 5,
            "audio_tokens": 0,
            "image_tokens": 0
        },
        "completion_tokens_details": {
            "text_tokens": 0,
            "audio_tokens": 0,
            "reasoning_tokens": 1162
        },
        "input_tokens": 0,
        "output_tokens": 0,
        "input_tokens_details": null,
        "claude_cache_creation_5_m_tokens": 0,
        "claude_cache_creation_1_h_tokens": 0
    }
}

从上面可以看出是Gemini 3.0模型可以支持多模态的理解的。

Gemini-3.1 多模态模型

Gemini 3.1 Pro 是 Gemini 3.0 Pro 的升级版本，底层模型为 gemini-3.1-pro-preview，同样支持文本、图像、视频等多模态输入，具备更强的推理和理解能力。使用方式与 Gemini 3.0 Pro 完全一致，只需将 model 参数替换为 gemini-3.1-pro 即可。

请求样例：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
 
{
  "model": "gemini-3.1-pro",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "图片的内容是什么？"
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "https://cdn.acedata.cloud/qzx2z1.png"
          }
        }
      ]
    }
  ],
  "stream": false
}

Gemini 3.1 Pro 同样支持视频理解：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
 
{
  "model": "gemini-3.1-pro",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "视频的内容是什么？"
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "https://cdn.acedata.cloud/58yioe.mp4"
          }
        }
      ]
    }
  ],
  "stream": false
}

返回格式与 Gemini 3.0 Pro 一致，详见上方 Gemini-3.0 多模态模型章节的说明。

错误处理

在调用 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"
}

结论

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

作者 发表于 阅读次数： 本文字数： 18k 阅读时长 ≈ 16 分钟

产品推广

做内容的人都清楚，真正费时间的不是某一步，而是”串起来”这件事：想选题、写文案、配图、再剪一段视频，往往要在四五个工具之间来回搬运。

这篇文章讲一件具体的事——用 Ace Data Cloud（api.acedata.cloud）上的三个模型，把”一条内容”从文字一路做到视频，全部用同一个 API Token、同一套请求方式完成。三个模型各管一段：

  • Gemini（/gemini/chat/completions）——写文案、起标题、把一句话需求扩写成结构化脚本；
  • Nano Banana（/nano-banana/images）——出配图、海报、封面；
  • Veo（/veo/videos）——把静态画面变成有镜头语言的短视频。

不需要分别去三家注册、三次充值。到 控制台 拿一个 Token 就能调用平台上的所有服务，首次申请附带免费额度可以先跑通再说。

下面按”一条咖啡店秋季新品内容”的真实流程走一遍，每一步都有能直接复制运行的 curl 和真实生成的结果。

第一步：让 Gemini 把需求写成脚本

内容的起点通常是一句模糊的话，比如”给咖啡店秋季新品写点东西”。Gemini 擅长把这种口语需求整理成可执行的结构。接口是 OpenAI 兼容格式，messages 里放对话即可。

1
2
3
4
5
6
7
8
9
10
11
 
curl -X POST 'https://api.acedata.cloud/gemini/chat/completions' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "model": "gemini-3.1-pro",
    "max_tokens": 1200,
    "messages": [
      {"role": "system", "content": "你是一名负责社媒内容的文案。输出要精炼、可直接使用。"},
      {"role": "user", "content": "为一家精品咖啡店的秋季枫叶拿铁写：1) 一个不超过15字的标题；2) 一段小红书风格的正文（120字内）；3) 一句给配图用的英文绘图提示词；4) 一句给短视频用的英文镜头描述。"}
    ]
  }'

返回是标准的 chat.completion 结构，正文在 choices[0].message.content 里，usage 会给出真实 token 消耗（计费按 token 计）：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
 
{
  "id": "chatcmpl-2026...",
  "model": "gemini-3.1-pro",
  "object": "chat.completion",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "标题：一杯枫叶，接住整个秋天\n正文：……\n配图提示词：A cozy autumn latte with maple leaf art...\n镜头：Slow top-down push-in on a maple-leaf latte, steam rising..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": { "prompt_tokens": 96, "completion_tokens": 724, "total_tokens": 820 }
}

提示：gemini-3.x 系列的 flash / pro 是思考模型，回复前会先消耗一部分 reasoning token，max_tokens 建议给到 512 以上，否则可能因为预算被推理占满而返回空内容。

Gemini 是原生多模态的，如果你已经有一张实拍图，也可以把某条消息的 content 换成内容块数组，同时塞 text 和 image_url（支持公开图片 URL 或 data:image/...;base64, ），让它”看着图写文案”。这一步拿到的两句英文提示词，正好是后面图片和视频的输入。

第二步：让 Nano Banana 出配图

有了提示词，配图交给 Nano Banana（Google 的 Gemini 系图像模型）。它的强项是画面干净、排版留白规整，很适合做社媒海报这种”要留标题位”的图。图片生成比对话慢一些，建议加 "async": true 先拿 task_id，再轮询。

1
2
3
4
5
6
7
8
9
 
curl -X POST 'https://api.acedata.cloud/nano-banana/images' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "action": "generate",
    "model": "nano-banana",
    "async": true,
    "prompt": "A clean minimal social media poster for a specialty coffee shop autumn menu. Warm cream background, a cup of latte with leaf art in the center, small hand-drawn maple leaves, elegant layout with empty headline space at top, soft natural light, product photography style."
  }'

立即返回 task_id，随后向 /nano-banana/tasks 轮询直到 data 里出现 image_url：

1
2
3
4
 
curl -X POST 'https://api.acedata.cloud/nano-banana/tasks' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{"id": "74d3df89-9394-4cc1-bb50-f44e653036b1", "action": "retrieve"}'

这是上面这条请求真实跑出来的结果（顶部留白正好放标题）：

Nano Banana 生成的咖啡店秋季海报

如果你要做的是”改图”而不是”生成”——比如把实拍产品图换背景、统一多张图风格、修一张老照片——把 action 换成对应行为并传入 image 即可，请求方式一致。

第三步：让 Veo 把画面变成镜头

海报有了，再补一段几秒的动态短视频，用来做开场或社媒循环播放。Veo 理解镜头语言：你把”主体 + 光线 + 机位 + 运动 + 节奏”写清楚，它就按这个来。视频生成要 1–2 分钟，同样走异步。

1
2
3
4
5
6
7
8
9
 
curl -X POST 'https://api.acedata.cloud/veo/videos' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "action": "text2video",
    "model": "veo31-fast",
    "async": true,
    "prompt": "Extreme slow-motion macro of a hummingbird hovering beside a dew-covered flower at golden hour, wings frozen mid-beat, shallow depth of field, cinematic."
  }'

返回 task_id，向 /veo/tasks 轮询到 state 为 succeeded 即可拿到 video_url。下面是真实生成的一段（veo31-fast）：

📹 https://cdn.acedata.cloud/5e1f2c52a9.mp4

如果你想让第二步那张海报”动起来”，把 action 换成 image2video、传 image_urls 即可，让视频从这张图开始运动。Veo 的可选模型有 veo31-fast、veo31、veo3、veo3-fast：fast 系列用来快速试方向，质量档用来出成片。

把三步接起来

这三个接口的形状是刻意统一的：都用同一个 Bearer Token，都是 POST + JSON，视频/图片这类耗时任务都支持 async + /tasks 轮询（或用 callback_url 收回调）。所以你完全可以写一段几十行的脚本，把它串成一条流水线：

  1. 用户/运营给一句话需求 → 调 Gemini 得到 标题 + 正文 + 图提示词 + 镜头描述；
  2. 把图提示词丢给 Nano Banana → 得到 image_url；
  3. 把镜头描述（或那张图）丢给 Veo → 得到 video_url；
  4. 把标题、正文、图、视频落库，直接排期发布。

原来要在四个工具间搬运的活，变成一次调用链。

顺手能变成收入的部分

这条流水线本身就有两种用法：

  • 自己引流：稳定产出图文 + 短视频，是内容账号最缺的”持续供给”。而这些内容里天然带着你用的工具——把注册链接放进主页，你发的每条内容都是一次曝光。Ace Data Cloud 的创收联盟对通过你链接注册的用户消费有返佣。
  • 做成服务转售：把上面的脚本包一层界面，就是一个”输入选题、一键出图文视频”的小工具，你的成本是平台按量计费的那部分，卖给需要批量做内容的商家即可。

无论哪种，底层都只是这三个接口。

参考链接

一个 Token，三个模型，一条从文字到视频的生产线。先用免费额度把它跑通，再决定怎么用它。

作者 发表于 阅读次数： 本文字数： 4.2k 阅读时长 ≈ 4 分钟

API 开发教程

Discord Agent Proxy 是一个独立部署的服务：它保管你自己的 Discord 账号凭据，与 Discord 保持一条常驻连接，并把这个账号的能力通过 MCP 和 REST API 两个接口开放出来，让 AI 或程序代替你操作 Discord。

容器内不含任何 AI 模型，它只负责执行——由你的 AI 客户端（Claude、Cursor 等）或自己的程序发起调用。

1
2
3
 
AI 客户端  ──MCP /mcp──┐
                       ├─→ Discord Agent Proxy ──→ Discord
你的程序 ──REST /api───┘      （保管你的账号凭据）

⚠️ 使用前必读

用程序自动化操作个人账号（self-bot）违反 Discord 的服务条款，账号存在被封禁的风险。这是本服务的固有前提：你提供自己的账号凭据，并自行承担风险。

强烈建议使用一个专门的小号，不要用你的主账号。

部署服务

进入 控制台 → 应用，找到 Discord Agent Proxy 并创建应用。创建后进入配置页，填入你的 Discord 账号凭据并部署。

部署完成后，配置页会显示两项信息：

项目 示例 用途
MCP 接入地址 https://discord-bot-xxxxxxxxxxxx.app.acedata.cloud/mcp 配置到 AI 客户端
访问令牌 V0p7kAWY... 鉴权用，见下

如何获取 Discord 账号凭据

  1. 在电脑浏览器中登录 Discord（discord.com/app）
  2. 按 F12 打开开发者工具，切换到 Network（网络） 面板
  3. 在 Discord 中随意点击一个频道，观察请求列表
  4. 点开任意一个发往 discord.com/api 的请求，在 Request Headers（请求头） 中找到 authorization 字段
  5. 复制它的值

这串凭据等同于你的账号登录态，不要分享给任何人。如果泄露，在 Discord 中修改密码即可使其立即失效。

鉴权方式

除 /health 外，所有接口都需要在请求头中携带访问令牌：

1
 
Authorization: Bearer <你的访问令牌>

注意：本服务只接受请求头鉴权，不支持 ?token=xxx 这种在网址后面拼接令牌的方式。 直接在浏览器里打开接口地址会返回 401 unauthorized，这是正常现象，不代表部署失败。想确认服务是否正常，请访问 /health（该接口无需鉴权）。

检查服务状态

1
 
curl https://discord-bot-xxxxxxxxxxxx.app.acedata.cloud/health

正常返回：

1
 
{ "status": "ok", "gateway_ready": true }

其中 gateway_ready 表示与 Discord 的连接是否已建立：

  • true — 一切正常，可以开始调用
  • false — 服务已启动但尚未连上 Discord。刚部署后需要等待几秒；如果持续为 false，通常是账号凭据无效或已过期，请重新获取并重新部署

当 gateway_ready 为 false 时，其他接口会返回 503。

在 AI 客户端中使用（MCP）

以 Claude Code 为例：

1
2
3
 
claude mcp add --transport http discord \
  https://discord-bot-xxxxxxxxxxxx.app.acedata.cloud/mcp \
  --header "Authorization: Bearer <你的访问令牌>"

其他支持 MCP 的客户端（Cursor、Claude Desktop 等）通常使用如下配置：

1
2
3
4
5
6
7
8
9
10
11
 
{
  "mcpServers": {
    "discord": {
      "type": "http",
      "url": "https://discord-bot-xxxxxxxxxxxx.app.acedata.cloud/mcp",
      "headers": {
        "Authorization": "Bearer <你的访问令牌>"
      }
    }
  }
}

配置完成后，就可以直接用自然语言指挥 AI 操作 Discord，例如：

看一下我在「项目讨论」频道有没有新消息，如果有人问到发布时间，帮我回复说这周五。

可用工具

MCP 工具 作用
discord_whoami 查看当前代理的是哪个账号
discord_list_guilds 列出账号加入的所有服务器
discord_list_channels 列出某个服务器下的频道
discord_create_text_channel 创建文字频道
discord_list_members 列出服务器成员
discord_send_message 发送消息（可指定回复某条消息）
discord_read_messages 读取频道最近的消息
discord_edit_message 编辑自己发过的消息
discord_delete_message 删除消息
discord_search_messages 在频道内搜索消息
discord_add_reaction 给消息添加表情回应
discord_pin_message 置顶消息
discord_create_dm 开启一对一私聊，返回频道 ID
discord_send_dm 给某个用户发私信

在程序中使用（REST API）

所有 REST 接口挂载在 /api 下，返回体统一为 {"data": ...}，出错时为 {"error": "..."}。

查看当前账号

1
2
 
curl https://discord-bot-xxxxxxxxxxxx.app.acedata.cloud/api/whoami \
  -H "Authorization: Bearer <你的访问令牌>"

发送消息

1
2
3
4
 
curl -X POST https://discord-bot-xxxxxxxxxxxx.app.acedata.cloud/api/messages \
  -H "Authorization: Bearer <你的访问令牌>" \
  -H "Content-Type: application/json" \
  -d '{"channel_id": "1234567890", "content": "你好"}'

可选参数 reply_to 用于回复指定消息：

1
 
{ "channel_id": "1234567890", "content": "收到", "reply_to": "9876543210" }

读取消息

1
2
 
curl "https://discord-bot-xxxxxxxxxxxx.app.acedata.cloud/api/channels/1234567890/messages?limit=20" \
  -H "Authorization: Bearer <你的访问令牌>"

完整接口列表

方法与路径 参数 作用
GET /api/whoami — 当前代理的账号信息
GET /api/guilds — 账号加入的服务器列表
GET /api/guilds/{guild_id}/channels — 服务器下的频道列表
POST /api/guilds/{guild_id}/channels {name} 创建文字频道
GET /api/guilds/{guild_id}/members ?limit=（默认 100） 服务器成员列表
POST /api/messages {channel_id, content, reply_to?} 发送消息
GET /api/channels/{channel_id}/messages ?limit=（默认 50，上限 100） 读取最近消息
GET /api/channels/{channel_id}/messages/search ?q=（必填）&limit=（默认 25） 搜索消息
PATCH /api/channels/{channel_id}/messages/{message_id} {content} 编辑消息
DELETE /api/channels/{channel_id}/messages/{message_id} — 删除消息
POST /api/channels/{channel_id}/messages/{message_id}/reactions {emoji} 添加表情回应
POST /api/channels/{channel_id}/messages/{message_id}/pin — 置顶消息
POST /api/dms {recipient_id} 开启私聊，返回频道 ID
POST /api/dms/send {recipient_id, content} 发送私信

如何获取频道 ID 和用户 ID

在 Discord 客户端中依次打开 用户设置 → 高级设置，开启 开发者模式。之后右键点击任意频道或用户，菜单中会出现「复制 ID」。

也可以直接调用 GET /api/guilds 和 GET /api/guilds/{guild_id}/channels 来枚举。

常见问题

返回 401 unauthorized

访问令牌不正确，或者使用了 ?token= 的方式传递。请确认令牌通过请求头 Authorization: Bearer <令牌> 传递，且与控制台显示的一致。

返回 503

与 Discord 的连接尚未建立。先访问 /health 查看 gateway_ready，若长时间为 false，多为账号凭据失效，请重新获取并重新部署。

返回 403 或 404

账号本身没有对应权限（例如不在该服务器中、无权在该频道发言），或者 ID 填错了。这类错误来自 Discord，不是代理服务的问题。

返回 429

触发了 Discord 的频率限制，响应中的 retry_after 字段给出建议的等待秒数。请降低调用频率。

消息发送后账号被封禁

如前所述，自动化操作个人账号违反 Discord 服务条款。请使用专用小号，并控制操作频率、避免群发等敏感行为。

作者 发表于 阅读次数： 本文字数： 4k 阅读时长 ≈ 4 分钟

API 开发教程

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

申请流程

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

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

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

📘 完整文档：Producer Audios Generation API →

基本使用

想些什么歌曲，可以任意输入一段文字，比如我想生成一个关于圣诞的歌曲，就可以输入 a song for Christmas，如图所示：

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

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

另外 Request Body 的参数包括：

  • action：此次音乐生成任务的行为，生成歌曲是 generate。
  • model：创建歌曲采用的模型，目前主要有： FUZZ-2.0 Pro、FUZZ-2.0、FUZZ-2.0 Raw,FUZZ-1.1 Pro、FUZZ-1.0 Pro、FUZZ-1.0、FUZZ-1.1、FUZZ-0.8。
  • lyric：歌曲的歌词内容。
  • custom：是否采用自定义方式生成歌曲。
  • prompt：灵感模式下的提示词。
  • title：歌曲标题信息。
  • audio_id：参考歌曲 ID，用于续写/翻版等操作。
  • continue_at：从指定秒数开始续写歌曲。
  • replace_section_start/replace_section_end：替换片段的起止时间，单位秒。
  • lyrics_strength：歌词强度，表示歌词在音频生成中的影响程度，可选0-1之间，默认0.7。
  • sound_strength：音频提示词强度，可选0.2-1之间，默认0.7。
  • cover_strength：翻唱强度 0.2-1之间，默认1。
  • weirdness：风格奇特度，可选 0-1之间，默认0.5
  • callback_url：需要回调结果的 URL。
  • async：可选，设为 true 时接口立即返回 task_id，无需提供 callback_url，随后通过对应的任务查询接口轮询获取结果。
  • instrumental：是否为无歌词模式。

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

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
 
{
  "success": true,
  "task_id": "82fd443a-903a-4f18-8028-12d2f8a0a4be",
  "trace_id": "d85839fa-0bb1-42da-a9fc-cd582c29027d",
  "data": [
    {
      "id": "6c947f13-a3c5-4b9c-8609-5639c37cdc2d",
      "title": "Untitled",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png",
      "lyric": "[Instrumental]",
      "audio_url": "https://platform2.cdn.acedata.cloud/fish/5ade0339-5f11-487e-aacc-06a908271706.mp3",
      "video_url": null,
      "image_id": "6c947f13-a3c5-4b9c-8609-5639c37cdc2d",
      "topic": null,
      "seed": "2450882164",
      "sound": "A song for Christmas",
      "created_at": "2025-12-30T17:18:23.232911Z",
      "model": "FUZZ-2.0 Pro",
      "progress": "100%",
      "state": "succeeded",
      "duration": "181.3014058956916"
    }
  ]
}

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

  • success，此时音乐生成任务的状态情况。
    • data，此次音乐任务的结果
      • id，此时音乐生成任务的 ID。
      • sound，此时音乐生成任务的提示词。
      • seed，此时音乐生成任务的种子值。
      • audio_url，此时音乐生成任务的音频链接。
      • image_url，此时音乐生成任务的封面链接。
      • image_id，此时音乐生成任务的封面ID。
      • state，此时音乐生成任务的状态。
      • duration，此时音乐的时长信息。
      • progress，此时音乐任务的进度值。
      • model，此时音乐生成任务采用的模型信息。
      • lyric，此时音乐生成任务的歌词信息。

可以看到我们得到了想生成的音乐信息，我们只需要根据结果中 data 的音乐链接地址获取生成的 Producer 音乐即可。

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

1
2
3
4
5
6
7
8
9
 
curl -X POST 'https://api.acedata.cloud/producer/audios' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "action": "generate",
  "model": "FUZZ-2.0 Pro",
  "prompt": "A song for Christmas"
}'

自定义生成

如果想自定义生成歌词，可以输入歌词：

这时候 lyric 字段可以传入类似如下内容：

1
 
[Verse]Woke up with the sun in my eyesNo clouds above just blue in the skiesShoes on my feet I’m ready to runEvery step feels like a loaded gun[Chorus]Happy days are rolling inLet the joy beneath my skinNo more shadows no more liesJust the truth that lifts me high[Verse 2]Dancing through the city streetsA rhythm pounding in my heartbeatStrangers smile it’s catching onThis world’s a stage we’re all a song[Chorus]Happy days are rolling inLet the joy beneath my skinNo more shadows no more liesJust the truth that lifts me high[Bridge]Throw your worries out the doorLet them sink to the ocean floorWe’re alive and it’s enoughLife is messy but it’s love[Chorus]Happy days are rolling inLet the joy beneath my skinNo more shadows no more liesJust the truth that lifts me high

接下来我们要根据歌词、标题、风格自定义生成歌曲，就可以指定如下内容：

  • lyric：歌词文本
  • custom：填写为 true，代表自定义生成，该参数默认为 false，代表使用 prompt 生成。
  • title：歌曲的标题。

填写样例如下：

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

对应的代码：

1
2
3
4
5
6
7
8
9
10
11
 
curl -X POST 'https://api.acedata.cloud/producer/audios' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "action": "generate",
  "model": "FUZZ-2.0 Pro",
  "instrumental": false,
  "lyric": "[Verse]\nWoke up with the sun in my eyes\nNo clouds above just blue in the skies\nShoes on my feet I’m ready to run\nEvery step feels like a loaded gun\n[Chorus]\nHappy days are rolling in\nLet the joy beneath my skin\nNo more shadows no more lies\nJust the truth that lifts me high\n[Verse 2]\nDancing through the city streets\nA rhythm pounding in my heartbeat\nStrangers smile it’s catching on\nThis world’s a stage we’re all a song\n[Chorus]\nHappy days are rolling in\nLet the joy beneath my skin\nNo more shadows no more lies\nJust the truth that lifts me high\n[Bridge]\nThrow your worries out the door\nLet them sink to the ocean floor\nWe’re alive and it’s enough\nLife is messy but it’s love\n[Chorus]\nHappy days are rolling in\nLet the joy beneath my skin\nNo more shadows no more lies\nJust the truth that lifts me high",
  "custom": true
}'

测试允许，生成的效果是类似的。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
 
{
  "success": true,
  "task_id": "9f58bbd4-855a-4233-ac45-b63bf9168e02",
  "trace_id": "145ad117-6ce7-42dd-af12-70751c5284fc",
  "data": [
    {
      "id": "38d3b9e2-0dfb-4338-b2a7-15e45656ed32",
      "title": "Woke up with the sun in my eyes",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png",
      "lyric": "[Verse]\nWoke up with the sun in my eyes\nNo clouds above just blue in the skies\nShoes on my feet I’m ready to run\nEvery step feels like a loaded gun\n[Chorus]\nHappy days are rolling in\nLet the joy beneath my skin\nNo more shadows no more lies\nJust the truth that lifts me high\n[Verse 2]\nDancing through the city streets\nA rhythm pounding in my heartbeat\nStrangers smile it’s catching on\nThis world’s a stage we’re all a song\n[Chorus]\nHappy days are rolling in\nLet the joy beneath my skin\nNo more shadows no more lies\nJust the truth that lifts me high\n[Bridge]\nThrow your worries out the door\nLet them sink to the ocean floor\nWe’re alive and it’s enough\nLife is messy but it’s love\n[Chorus]\nHappy days are rolling in\nLet the joy beneath my skin\nNo more shadows no more lies\nJust the truth that lifts me high",
      "audio_url": "https://platform2.cdn.acedata.cloud/fish/5ade0339-5f11-487e-aacc-06a908271706.mp3",
      "video_url": null,
      "image_id": "38d3b9e2-0dfb-4338-b2a7-15e45656ed32",
      "topic": null,
      "seed": "3789209121",
      "sound": "",
      "created_at": "2025-12-30T17:26:46.357055Z",
      "model": "FUZZ-2.0 Pro",
      "progress": "100%",
      "state": "succeeded",
      "duration": "153.80897959183673"
    }
  ]
}

翻唱歌曲

如果想对已经生成的歌曲进行翻唱操作的操作，可以输入上文生成的歌曲进行翻唱，接下来我们要根据歌词、标题自定义生成歌曲。

如果想对自己上传的歌曲进行继续翻唱的话，可以将参数 action 设置为 upload_cover ，并且输入需要继续翻唱自定义上传的歌曲 ID，歌曲 ID 的获取是使用 Producer Upload API来获取，如下图所示：

就可以指定如下内容：

  • action：此次歌曲任务的行为，目前支持：generate、cover、extend、upload_cover、upload_extend、replace_section、swap_vocals、swap_instrumentals、variation，此次翻唱使用cover参数。
  • lyric：歌词文本
  • title：歌曲的标题。
  • custom：是否采用自定义模式生成，默认是false。
  • audio_id：需要翻唱歌曲的歌曲ID。

填写样例如下：

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

对应的代码：

1
2
3
4
5
6
7
8
9
10
11
12
13
 
curl -X POST 'https://api.acedata.cloud/producer/audios' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "action": "cover",
  "model": "FUZZ-2.0 Pro",
  "lyric": "[Verse]\nWoke up with the sun in my eyes\nNo clouds above just blue in the skies\nShoes on my feet I’m ready to run\nEvery step feels like a loaded gun\n[Chorus]\nHappy days are rolling in\nLet the joy beneath my skin\nNo more shadows no more lies\nJust the truth that lifts me high\n[Verse 2]\nDancing through the city streets\nA rhythm pounding in my heartbeat\nStrangers smile it’s catching on\nThis world’s a stage we’re all a song\n[Chorus]\nHappy days are rolling in\nLet the joy beneath my skin\nNo more shadows no more lies\nJust the truth that lifts me high\n[Bridge]\nThrow your worries out the door\nLet them sink to the ocean floor\nWe’re alive and it’s enough\nLife is messy but it’s love\n[Chorus]\nHappy days are rolling in\nLet the joy beneath my skin\nNo more shadows no more lies\nJust the truth that lifts me high",
  "audio_id": "38d3b9e2-0dfb-4338-b2a7-15e45656ed32",
  "instrumental": false,
  "custom": true,
  "title": "Cover"
}'

测试允许，生成的效果是类似的。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
 
{
  "success": true,
  "task_id": "dbca350e-6fb9-46ca-9c7e-4c1a9080806f",
  "trace_id": "a39e0fff-ced8-4b31-ae23-aef3badd90fa",
  "data": [
    {
      "id": "e52dd729-38b4-4c2f-9031-59eb7953c593",
      "title": "Cover",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png",
      "lyric": "[Verse]\nWoke up with the sun in my eyes\nNo clouds above just blue in the skies\nShoes on my feet I’m ready to run\nEvery step feels like a loaded gun\n[Chorus]\nHappy days are rolling in\nLet the joy beneath my skin\nNo more shadows no more lies\nJust the truth that lifts me high\n[Verse 2]\nDancing through the city streets\nA rhythm pounding in my heartbeat\nStrangers smile it’s catching on\nThis world’s a stage we’re all a song\n[Chorus]\nHappy days are rolling in\nLet the joy beneath my skin\nNo more shadows no more lies\nJust the truth that lifts me high\n[Bridge]\nThrow your worries out the door\nLet them sink to the ocean floor\nWe’re alive and it’s enough\nLife is messy but it’s love\n[Chorus]\nHappy days are rolling in\nLet the joy beneath my skin\nNo more shadows no more lies\nJust the truth that lifts me high",
      "audio_url": "https://platform2.cdn.acedata.cloud/fish/5ade0339-5f11-487e-aacc-06a908271706.mp3",
      "video_url": null,
      "image_id": "e52dd729-38b4-4c2f-9031-59eb7953c593",
      "topic": null,
      "seed": "358803418",
      "sound": "",
      "created_at": "2025-12-30T17:32:32.951948Z",
      "model": "FUZZ-2.0 Pro",
      "progress": "100%",
      "state": "succeeded",
      "duration": "153.0659410430839"
    }
  ]
}

续写歌曲

如果想续写歌曲的话，我们需要传入action参数值为：extend，接下来我们要根据歌词、标题、风格自定义生成歌曲。

如果想对自己上传的歌曲进行继续续写的话，可以将参数 action 设置为 upload_extend ，并且输入需要继续续写自定义上传的歌曲 ID，歌曲 ID 的获取是使用 Producer Upload API来获取，如下图所示：

填写样例如下：

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

对应的代码：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
 
curl -X POST 'https://api.acedata.cloud/producer/audios' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "action": "extend",
  "model": "FUZZ-2.0 Pro",
  "instrumental": false,
  "lyric": "[Verse]\nWoke up with the sun in my eyes\nNo clouds above just blue in the skies\nShoes on my feet I’m ready to run\nEvery step feels like a loaded gun\n[Chorus]\nHappy days are rolling in\nLet the joy beneath my skin\nNo more shadows no more lies\nJust the truth that lifts me high\n[Verse 2]\nDancing through the city streets\nA rhythm pounding in my heartbeat\nStrangers smile it’s catching on\nThis world’s a stage we’re all a song\n[Chorus]\nHappy days are rolling in\nLet the joy beneath my skin\nNo more shadows no more lies\nJust the truth that lifts me high\n[Bridge]\nThrow your worries out the door\nLet them sink to the ocean floor\nWe’re alive and it’s enough\nLife is messy but it’s love\n[Chorus]\nHappy days are rolling in\nLet the joy beneath my skin\nNo more shadows no more lies\nJust the truth that lifts me high",
  "continue_at": 3,
  "audio_id": "38d3b9e2-0dfb-4338-b2a7-15e45656ed32",
  "custom": true,
  "title": "Extend",
  "weirdness": 0.3,
  "sound_strength": 0.3,
  "lyrics_strength": 0.6
}'

测试允许，生成的效果是类似的。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
 
{
  "success": true,
  "task_id": "834983cb-d62d-4750-b1aa-461da137e51f",
  "trace_id": "6923eee2-7403-432c-8bd1-e471086385b0",
  "data": [
    {
      "id": "d9ebc609-fb65-4a23-b914-c074747af6a4",
      "title": "Extend",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png",
      "lyric": "[Verse]\n[Verse]\nWoke up with the sun in my eyes\nNo clouds above just blue in the skies\nShoes on my feet I’m ready to run\nEvery step feels like a loaded gun\n[Chorus]\nHappy days are rolling in\nLet the joy beneath my skin\nNo more shadows no more lies\nJust the truth that lifts me high\n[Verse 2]\nDancing through the city streets\nA rhythm pounding in my heartbeat\nStrangers smile it’s catching on\nThis world’s a stage we’re all a song\n[Chorus]\nHappy days are rolling in\nLet the joy beneath my skin\nNo more shadows no more lies\nJust the truth that lifts me high\n[Bridge]\nThrow your worries out the door\nLet them sink to the ocean floor\nWe’re alive and it’s enough\nLife is messy but it’s love\n[Chorus]\nHappy days are rolling in\nLet the joy beneath my skin\nNo more shadows no more lies\nJust the truth that lifts me high",
      "audio_url": "https://platform2.cdn.acedata.cloud/fish/5ade0339-5f11-487e-aacc-06a908271706.mp3",
      "video_url": null,
      "image_id": "d9ebc609-fb65-4a23-b914-c074747af6a4",
      "topic": null,
      "seed": "4294469624",
      "sound": "",
      "created_at": "2025-12-30T17:36:14.520928Z",
      "model": "FUZZ-2.0 Pro",
      "progress": "100%",
      "state": "succeeded",
      "duration": "173.87102040816328"
    }
  ]
}

音乐变换

如果想根据上一首音乐的seed值生成一首类似效果的新音乐的话，我们需要传入action参数值为：variation，接下来就可以自定义生成一首类似效果的新音乐。

填写样例如下：

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

对应的代码：

1
2
3
4
5
6
7
8
9
10
11
12
 
curl -X POST 'https://api.acedata.cloud/producer/audios' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "action": "variation",
  "audio_id": "d9ebc609-fb65-4a23-b914-c074747af6a4",
  "model": "FUZZ-2.0 Pro",
  "instrumental": false,
  "lyric": "[Verse]\nWoke up with the sun in my eyes\nNo clouds above just blue in the skies\nShoes on my feet I’m ready to run\nEvery step feels like a loaded gun\n[Chorus]\nHappy days are rolling in\nLet the joy beneath my skin\nNo more shadows no more lies\nJust the truth that lifts me high\n[Verse 2]\nDancing through the city streets\nA rhythm pounding in my heartbeat\nStrangers smile it’s catching on\nThis world’s a stage we’re all a song\n[Chorus]\nHappy days are rolling in\nLet the joy beneath my skin\nNo more shadows no more lies\nJust the truth that lifts me high\n[Bridge]\nThrow your worries out the door\nLet them sink to the ocean floor\nWe’re alive and it’s enough\nLife is messy but it’s love\n[Chorus]\nHappy days are rolling in\nLet the joy beneath my skin\nNo more shadows no more lies\nJust the truth that lifts me high",
  "custom": true
}'

测试允许，生成的效果是类似的。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
 
{
    "success": true,
    "task_id": "3a74da6d-a37d-4b5d-b116-821f455bce39",
    "trace_id": "8e28cce0-0400-4bfd-83db-6d27f97422c7",
    "data": [
        {
            "id": "c14ca458-cd5a-4700-83d4-5249e15f2707",
            "title": "Woke up with the sun in my eyes",
            "image_url": "https://cdn.acedata.cloud/e724d7f13d.png",
            "lyric": "[Verse]\nWoke up with the sun in my eyes\nNo clouds above just blue in the skies\nShoes on my feet I’m ready to run\nEvery step feels like a loaded gun\n[Chorus]\nHappy days are rolling in\nLet the joy beneath my skin\nNo more shadows no more lies\nJust the truth that lifts me high\n[Verse 2]\nDancing through the city streets\nA rhythm pounding in my heartbeat\nStrangers smile it’s catching on\nThis world’s a stage we’re all a song\n[Chorus]\nHappy days are rolling in\nLet the joy beneath my skin\nNo more shadows no more lies\nJust the truth that lifts me high\n[Bridge]\nThrow your worries out the door\nLet them sink to the ocean floor\nWe’re alive and it’s enough\nLife is messy but it’s love\n[Chorus]\nHappy days are rolling in\nLet the joy beneath my skin\nNo more shadows no more lies\nJust the truth that lifts me high",
            "audio_url": "https://platform2.cdn.acedata.cloud/fish/5ade0339-5f11-487e-aacc-06a908271706.mp3",
            "video_url": null,
            "image_id": "c14ca458-cd5a-4700-83d4-5249e15f2707",
            "topic": null,
            "seed": "2082104582",
            "sound": "",
            "created_at": "2025-12-30T17:48:40.135187Z",
            "model": "FUZZ-2.0",
            "progress": "100%",
            "state": "succeeded",
            "duration": "173.12798185941043"
        }
    ]
}

替换片段

如果想对歌曲进行替换片段的话，我们需要传入action参数值为：replace_section，接下来我们要根据歌词、标题自定义生成歌曲。

如果想对自己上传的歌曲进行继续替换片段的话，可以将参数 action 设置为 upload_replace_section ，并且输入需要继续续写自定义上传的歌曲 ID，歌曲 ID 的获取是使用 Producer Upload API来获取，如下图所示：

填写样例如下：

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

对应的代码：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
 
curl -X POST 'https://api.acedata.cloud/producer/audios' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "action": "replace_section",
  "model": "FUZZ-2.0 Pro",
  "instrumental": false,
  "lyric": "[Verse]\\nWoke up with the sun in my eyes\\nNo clouds above just blue in the skies\\nShoes on my feet I’m ready to run\\nEvery step feels like a loaded gun\\n[Chorus]\\nHappy days are rolling in\\nLet the joy beneath my skin\\nNo more shadows no more lies\\nJust the truth that lifts me high\\n[Verse 2]\\nDancing through the city streets\\nA rhythm pounding in my heartbeat\\nStrangers smile it’s catching on\\nThis world’s a stage we’re all a song\\n[Chorus]\\nHappy days are rolling in\\nLet the joy beneath my skin\\nNo more shadows no more lies\\nJust the truth that lifts me high\\n[Bridge]\\nThrow your worries out the door\\nLet them sink to the ocean floor\\nWe’re alive and it’s enough\\nLife is messy but it’s love\\n[Chorus]\\nHappy days are rolling in\\nLet the joy beneath my skin\\nNo more shadows no more lies\\nJust the truth that lifts me high",
  "audio_id": "d9ebc609-fb65-4a23-b914-c074747af6a4",
  "replace_section_start": 3,
  "replace_section_end": 70,
  "custom": true
}'

测试允许，生成的效果是类似的。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
 
{
    "success": true,
    "task_id": "3cb5ae96-01b0-4a37-afb0-e582608af56f",
    "trace_id": "3ebc6f63-5093-4499-bf9b-95c239e0da4f",
    "data": [
        {
            "id": "a54609c6-13e2-4176-be0f-4d7eebc68e1f",
            "title": "Woke up with the sun in my eyes",
            "image_url": "https://cdn.acedata.cloud/e724d7f13d.png",
            "lyric": "[Verse]\\nWoke up with the sun in my eyes\\nNo clouds above just blue in the skies\\nShoes on my feet I’m ready to run\\nEvery step feels like a loaded gun\\n[Chorus]\\nHappy days are rolling in\\nLet the joy beneath my skin\\nNo more shadows no more lies\\nJust the truth that lifts me high\\n[Verse 2]\\nDancing through the city streets\\nA rhythm pounding in my heartbeat\\nStrangers smile it’s catching on\\nThis world’s a stage we’re all a song\\n[Chorus]\\nHappy days are rolling in\\nLet the joy beneath my skin\\nNo more shadows no more lies\\nJust the truth that lifts me high\\n[Bridge]\\nThrow your worries out the door\\nLet them sink to the ocean floor\\nWe’re alive and it’s enough\\nLife is messy but it’s love\\n[Chorus]\\nHappy days are rolling in\\nLet the joy beneath my skin\\nNo more shadows no more lies\\nJust the truth that lifts me high",
            "audio_url": "https://platform2.cdn.acedata.cloud/fish/5ade0339-5f11-487e-aacc-06a908271706.mp3",
            "video_url": null,
            "image_id": "a54609c6-13e2-4176-be0f-4d7eebc68e1f",
            "topic": null,
            "seed": "14887454",
            "sound": "",
            "created_at": "2025-12-30T18:01:19.907443Z",
            "model": "FUZZ-2.0 Pro",
            "progress": "100%",
            "state": "succeeded",
            "duration": "174.6140589569161"
        }
    ]
}

伴奏翻版

如果想使用官方的伴奏翻版操作，可以将action参数值设为：swap_instrumentals，接下来我们要根据歌词、标题自定义生成歌曲。

填写样例如下：

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

对应的代码：

1
2
3
4
5
6
7
8
9
10
11
 
curl -X POST 'https://api.acedata.cloud/producer/audios' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "action": "swap_instrumentals",
  "model": "FUZZ-2.0 Pro",
  "weirdness": 0.6,
  "prompt": "Happy",
  "audio_id": "d9ebc609-fb65-4a23-b914-c074747af6a4"
}'

测试允许，生成的效果是类似的。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
 
{
  "success": true,
  "task_id": "d17d8376-3a58-451d-a976-404719bac11d",
  "trace_id": "ab596807-910a-4e30-bae2-4647895f7d0b",
  "data": [
    {
      "id": "22d7d75c-9e0a-47a8-b22b-eea55eaa0c4b",
      "title": "Extend (Sound swap)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png",
      "lyric": "[Verse]\nWoke up with the sun in my eyes\nNo clouds above just blue in the skies\nShoes on my feet I’m ready to run\nEvery step feels like a loaded gun\n[Chorus]\nHappy days are rolling in\nLet the joy beneath my skin\nNo more shadows no more lies\nJust the truth that lifts me high\n[Verse 2]\nDancing through the city streets\nA rhythm pounding in my heartbeat\nStrangers smile it’s catching on\nThis world’s a stage we’re all a song\n[Chorus]\nHappy days are rolling in\nLet the joy beneath my skin\nNo more shadows no more lies\nJust the truth that lifts me high\n[Bridge]\nThrow your worries out the door\nLet them sink to the ocean floor\nWe’re alive and it’s enough\nLife is messy but it’s love\n[Chorus]\nHappy days are rolling in\nLet the joy beneath my skin\nNo more shadows no more lies\nJust the truth that lifts me high",
      "audio_url": "https://platform2.cdn.acedata.cloud/fish/5ade0339-5f11-487e-aacc-06a908271706.mp3",
      "video_url": null,
      "image_id": "22d7d75c-9e0a-47a8-b22b-eea55eaa0c4b",
      "topic": null,
      "seed": "2157878068",
      "sound": "Happy",
      "created_at": "2025-12-30T18:09:49.594800Z",
      "model": "FUZZ-2.0 Pro",
      "progress": "100%",
      "state": "succeeded",
      "duration": "172.3849433106576"
    }
  ]
}

人声翻版

如果想使用官方的人声翻版操作，可以将action参数值设为：swap_vocals，接下来我们要根据歌词、标题、风格自定义生成歌曲。

填写样例如下：

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

对应的代码：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
 
curl -X POST 'https://api.acedata.cloud/producer/audios' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "action": "swap_vocals",
  "model": "FUZZ-2.0 Pro",
  "instrumental": false,
  "lyric": "[Verse]\nWoke up with the sun in my eyes\nNo clouds above just blue in the skies\nShoes on my feet I’m ready to run\nEvery step feels like a loaded gun\n[Chorus]\nHappy days are rolling in\nLet the joy beneath my skin\nNo more shadows no more lies\nJust the truth that lifts me high\n[Verse 2]\nDancing through the city streets\nA rhythm pounding in my heartbeat\nStrangers smile it’s catching on\nThis world’s a stage we’re all a song\n[Chorus]\nHappy days are rolling in\nLet the joy beneath my skin\nNo more shadows no more lies\nJust the truth that lifts me high\n[Bridge]\nThrow your worries out the door\nLet them sink to the ocean floor\nWe’re alive and it’s enough\nLife is messy but it’s love\n[Chorus]\nHappy days are rolling in\nLet the joy beneath my skin\nNo more shadows no more lies\nJust the truth that lifts me high",
  "weirdness": 0.6,
  "lyrics_strength": 0.8,
  "audio_id": "d9ebc609-fb65-4a23-b914-c074747af6a4",
  "custom": true
}'

测试允许，生成的效果是类似的。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
 
{
  "success": true,
  "task_id": "a903ac38-f129-4f85-9181-b1dc5579bd32",
  "trace_id": "9953af52-45e0-4808-bf13-88f0b21262c1",
  "data": [
    {
      "id": "7b2d653b-aaaa-41b0-b737-aee4c4c5693b",
      "title": "Woke up with the sun in my eyes",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png",
      "lyric": "[Verse]\nWoke up with the sun in my eyes\nNo clouds above just blue in the skies\nShoes on my feet I’m ready to run\nEvery step feels like a loaded gun\n[Chorus]\nHappy days are rolling in\nLet the joy beneath my skin\nNo more shadows no more lies\nJust the truth that lifts me high\n[Verse 2]\nDancing through the city streets\nA rhythm pounding in my heartbeat\nStrangers smile it’s catching on\nThis world’s a stage we’re all a song\n[Chorus]\nHappy days are rolling in\nLet the joy beneath my skin\nNo more shadows no more lies\nJust the truth that lifts me high\n[Bridge]\nThrow your worries out the door\nLet them sink to the ocean floor\nWe’re alive and it’s enough\nLife is messy but it’s love\n[Chorus]\nHappy days are rolling in\nLet the joy beneath my skin\nNo more shadows no more lies\nJust the truth that lifts me high",
      "audio_url": "https://platform2.cdn.acedata.cloud/fish/5ade0339-5f11-487e-aacc-06a908271706.mp3",
      "video_url": null,
      "image_id": "7b2d653b-aaaa-41b0-b737-aee4c4c5693b",
      "topic": null,
      "seed": "2484735707",
      "sound": "",
      "created_at": "2025-12-30T18:13:01.349875Z",
      "model": "FUZZ-2.0 Pro",
      "progress": "100%",
      "state": "succeeded",
      "duration": "173.12798185941043"
    }
  ]
}

词曲分离

如果想使用官方的词曲分离操作，可以将action参数值设为：stems，接下来我们要根据歌曲ID进行词曲分离。

填写样例如下：

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

对应的代码：

1
2
3
4
5
6
7
8
 
curl -X POST 'https://api.acedata.cloud/producer/audios' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "action": "stems",
  "audio_id": "a54609c6-13e2-4176-be0f-4d7eebc68e1f"
}'

测试允许，生成的效果是类似的。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
 
{
    "success": true,
    "task_id": "561ac695-b4aa-47cf-978d-fb7be2b9ebfc",
    "trace_id": "66d0d397-2987-4bde-84fb-a60d0023b217",
    "data": [
        {
            "title": "Woke up with the sun in my eyes",
            "lyric": "",
            "stems_url": "https://platform.cdn.acedata.cloud/producer/561ac695-b4aa-47cf-978d-fb7be2b9ebfc.zip",
            "model": "",
            "progress": "100%",
            "state": "succeeded"
        }
    ]
}

异步回调

由于 Producer Audios Generation API 生成的时间有时候会相对较长，如果 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/#!/view/0d73431d-f833-4be4-9276-b6e1690d55c1。

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

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

1
2
3
 
{
  "task_id": "1a6ac2ad-10f2-4e2b-b500-66ec27fe82ad"
}

稍等片刻，我们可以在 https://webhook.site/#!/view/0d73431d-f833-4be4-9276-b6e1690d55c1 上观察到生成任务的结果，如图所示：

内容如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
 
{
    "success": true,
    "task_id": "1a6ac2ad-10f2-4e2b-b500-66ec27fe82ad",
    "trace_id": "1da03537-4eb8-410d-b849-43f03085a3bb",
    "data": [
        {
            "id": "1dd08826-478e-43a6-868f-aff5ababac2c",
            "title": "Woke up with the sun in my eyes",
            "image_url": "https://cdn.acedata.cloud/e724d7f13d.png",
            "lyric": "[Verse]\nWoke up with the sun in my eyes\nNo clouds above just blue in the skies\nShoes on my feet I’m ready to run\nEvery step feels like a loaded gun\n[Chorus]\nHappy days are rolling in\nLet the joy beneath my skin\nNo more shadows no more lies\nJust the truth that lifts me high\n[Verse 2]\nDancing through the city streets\nA rhythm pounding in my heartbeat\nStrangers smile it’s catching on\nThis world’s a stage we’re all a song\n[Chorus]\nHappy days are rolling in\nLet the joy beneath my skin\nNo more shadows no more lies\nJust the truth that lifts me high\n[Bridge]\nThrow your worries out the door\nLet them sink to the ocean floor\nWe’re alive and it’s enough\nLife is messy but it’s love\n[Chorus]\nHappy days are rolling in\nLet the joy beneath my skin\nNo more shadows no more lies\nJust the truth that lifts me high",
            "audio_url": "https://platform2.cdn.acedata.cloud/fish/5ade0339-5f11-487e-aacc-06a908271706.mp3",
            "video_url": null,
            "image_id": "1dd08826-478e-43a6-868f-aff5ababac2c",
            "topic": null,
            "seed": "1490770667",
            "sound": "",
            "created_at": "2025-12-30T18:36:00.994141Z",
            "model": "FUZZ-2.0 Pro",
            "progress": "100%",
            "state": "succeeded",
            "duration": "135.2330158730159"
        }
    ]
}

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

错误处理

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

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

错误响应示例

1
2
3
4
5
6
7
8
 
{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

结论

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

作者 发表于 阅读次数： 本文字数： 24k 阅读时长 ≈ 22 分钟

技术教程

你是不是也想在 Claude 里直接完成更多创作任务：一句话生成一首歌，让 Claude 根据歌词继续做封面图；让它把产品图变成短视频；边聊天边搜索网页资料；最后把分享链接压成短链。

Claude 本身擅长理解需求、拆解任务和组织上下文，但音乐、图片、视频、搜索、短链这些能力需要外部工具来完成。AceData Cloud 把常用的 AI 创作服务封装成 11 个托管式 MCP Server，你只要在 Claude 里连接一次，就能让 Claude 在对话中按需调用这些工具。

适合这篇文章的读者很简单：你正在使用 claude.ai 网页版或 Claude Desktop，希望把 Claude 从“聊天助手”扩展成“AI 创作工作台”，并且希望用最少步骤跑通。

MCP 是什么？

MCP（Model Context Protocol）是 Anthropic 推出的开放协议，可以理解为 Claude 和外部工具之间的标准连接方式。

没有 MCP 时，你要在 Claude、搜索引擎、图片生成网站、音乐生成网站之间来回切换，把 prompt、结果链接、素材反复复制粘贴。有 MCP 后，Claude 可以在理解你的目标后直接调用对应工具：需要音乐就调用 Suno，需要图片就调用 Midjourney / Flux / Seedream，需要视频就调用 Luma / Sora / Veo，需要搜索就调用 Serp。

AceData Cloud 提供的是远程 MCP Server：服务托管在云端，Claude 通过 HTTPS 连接，不需要你本地安装模型、部署服务或维护密钥轮换。

AceData Cloud 提供哪些 MCP Server？

这 11 个 MCP Server 覆盖了从素材生成到信息检索的常见场景，使用同一个 AceData Cloud 账号统一授权、统一扣费。

MCP Server 领域 核心能力 远程 URL
Suno 音乐 文生歌、歌词、翻唱、续写、人声分离、Persona https://suno.mcp.acedata.cloud/mcp
Midjourney 绘画 文生图、混图、放大、Edit、生成视频 https://midjourney.mcp.acedata.cloud/mcp
Flux 绘画 6 个模型、Kontext 编辑、商用免版税 https://flux.mcp.acedata.cloud/mcp
Seedream 绘画 字节跳动模型，中文 prompt 理解强 https://seedream.mcp.acedata.cloud/mcp
NanoBanana 绘画 Gemini 驱动、虚拟试衣、商品换景 https://nanobanana.mcp.acedata.cloud/mcp
Luma 视频 Dream Machine、首尾帧控制 https://luma.mcp.acedata.cloud/mcp
Sora 视频 OpenAI 视频模型、角色一致性 https://sora.mcp.acedata.cloud/mcp
Veo 视频 Google 视频模型、原生音频、1080p 超分 https://veo.mcp.acedata.cloud/mcp
Seedance 视频 字节跳动、动作生成、配音 https://seedance.mcp.acedata.cloud/mcp
Serp 搜索 Google 搜索 6 种类型、多语言 https://serp.mcp.acedata.cloud/mcp
ShortURL 工具 长链转短链、批量、永久免费 https://shorturl.mcp.acedata.cloud/mcp

你不需要一次把 11 个都接上。常见做法是先接一个最想试的服务，比如 Midjourney 或 Suno，确认 Claude 能正常调用后，再按需要继续添加其他服务。

最简单的接入方式：OAuth Connector

claude.ai 网页版和 Claude Desktop 都支持通过 Connectors 添加远程 MCP Server。这个方式不需要手动复制 API Token，也不需要编辑 JSON 配置文件，只要登录 AceData Cloud 授权即可。

第 1 步：打开 Connectors 页面

在 claude.ai 网页版中，打开 https://claude.ai/customize/connectors，或者从左下角头像进入 Settings → Customize → Connectors。

Claude Desktop 的入口也在设置里的 Connectors 区域，界面和网页端基本一致。找到 Add custom connector 后，就可以添加 AceData Cloud 的 MCP Server。

Claude Connectors 添加入口

第 2 步：填写 MCP Server URL

点击 Add custom connector 后，给 Connector 起一个容易识别的名字，例如 Midjourney、Suno 或 Serp，然后从上面的表格复制对应的 MCP Server URL。

比如要先接入 Midjourney，就填写：

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

添加完成后，Claude 会读取这个 MCP Server 暴露的工具列表。这里看到的工具，就是后续 Claude 可以在对话中调用的能力。

Connector 工具列表

第 3 步：完成 AceData Cloud OAuth 授权

第一次连接时，Claude 会跳转到 AceData Cloud 的授权页面。你可以使用 GitHub、Google、微信、邮箱或手机号登录；如果还没有账号，注册后会获得免费额度，可以直接用来测试。

确认授权后，这个 Connector 就会绑定到你的 AceData Cloud 账号。之后 Claude 调用 MCP 工具时，会从这个账号的额度中扣费。

AceData Cloud OAuth 授权

第 4 步：回到 Claude，确认已连接

授权完成后回到 Claude，如果状态显示为 Connected，说明这个 MCP Server 已经可以使用。接下来你可以直接在对话里说“用 Midjourney 生成一张赛博朋克城市图”或“用 Suno 写一首轻快的 BGM”，Claude 会根据上下文选择对应工具。

MCP Connector 已连接

如果你想继续添加其他服务，重复上面的步骤即可。每个服务单独添加，但都使用同一个 AceData Cloud 账号，额度和调用记录统一管理。

注意：claude.ai 网页版的自定义 Connector 能力取决于你的 Anthropic 套餐。如果你的账号界面里没有 Add custom connector，可以改用 Claude Desktop，或升级到支持自定义 Connector 的套餐。

各服务单独教程

这篇文章只讲整体思路和最简单的连接方式。如果你想深入某一个服务，下面这些教程会展示更具体的工具列表、常用 prompt 和实际效果。

服务 教程链接
Suno Claude + Suno MCP：聊天就能写歌、配乐、翻唱
Flux Claude Desktop + Flux MCP：商用级图片生成
Seedream Claude Desktop + Seedream MCP：中文 prompt 国风绘画
NanoBanana Claude Desktop + NanoBanana MCP：Gemini 图片编辑、虚拟试衣
Luma Claude Desktop + Luma MCP：Dream Machine 视频生成
Sora Claude Desktop + Sora MCP：OpenAI 视频模型
Veo Claude Desktop + Veo MCP：Google 视频 + 原生音频
Seedance Claude Desktop + Seedance MCP：动作视频、配音
Serp Claude + Serp MCP：Google 实时搜索
ShortURL Claude + ShortURL MCP：长链转短链

如何查看剩余额度和调用记录

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

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

如果额度不足，可以前往 AceData Cloud 控制台 - 充值 补充额度，支持支付宝、微信、Stripe 等支付方式。

常见问题

Q：OAuth 接入需要手动复制 API Token 吗？

A：不需要。claude.ai 和 Claude Desktop 的 Connector 会通过 OAuth 完成授权。Token 主要用于 Claude Code、Cursor、VS Code 等需要手动配置 Header 的客户端。

Q：可以只连接一个 MCP Server 吗？

A：可以。建议先从一个最常用的服务开始，比如 Midjourney、Suno 或 Serp。确认能正常调用后，再按需要继续添加其他服务。

Q：为什么添加后 Claude 没有调用工具？

A：先确认 Connector 状态是 Connected，并且当前 Claude 套餐支持自定义 Connector。然后在提问时把需求说得明确一些，例如“用 Midjourney 生成一张图片”或“用 Serp 搜索”。如果仍然失败，可以在 Connectors 里点 Reconnect 重新授权。

Q：调用失败提示余额不足怎么办？

A：到 AceData Cloud 控制台 - 应用列表 查看剩余额度，再到 充值页面 补充额度。所有 MCP Server 共用同一个账户额度。

Q：连接多个 MCP Server 后会互相影响吗？

A：不会。每个 Connector 独立连接，Claude 会根据你的请求选择合适的工具。额度和调用记录会统一归到同一个 AceData Cloud 账号下，方便查看和管理。

作者 发表于 阅读次数： 本文字数： 3.8k 阅读时长 ≈ 3 分钟

API 开发教程

LobeChat 是一款开源 AI 客户端，主打「现代化 UI + 插件生态 + 知识库 + 一键自部署」。你可以使用官方在线版（PWA），也可以用 Docker 在自己的服务器上跑一份私有版。它原生支持自定义 OpenAI 兼容端点，因此可以接入 Ace Data Cloud，一份 API Token 同时访问 Claude、GPT、Gemini、Grok、DeepSeek、Kimi、GLM 等 60+ 大模型。本文介绍配置流程。

申请流程

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

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

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

配置 Ace Data Cloud

进入 LobeChat 的 应用设置 → 语言模型，找到 OpenAI 卡片并启用，填入：

字段 值 说明
API Key 你的 Ace Data Cloud Token 控制台复制的 Token
API 代理地址 https://api.acedata.cloud/v1 必须以 /v1 结尾
客户端请求模式 开启 浏览器直连，Key 不经过 LobeChat 服务器

LobeChat 不会自动给 Base URL 拼接 /v1，请求路径直接是 {API 代理地址}/chat/completions：

API 代理地址 实际请求 结果
https://api.acedata.cloud/v1 https://api.acedata.cloud/v1/chat/completions 正确
https://api.acedata.cloud/openai https://api.acedata.cloud/openai/chat/completions 也可用
https://api.acedata.cloud/openai/v1 https://api.acedata.cloud/openai/v1/chat/completions 404（/openai 下没有 /v1）
https://api.acedata.cloud https://api.acedata.cloud/chat/completions 404（缺 /v1）

LobeChat 默认会调用 /v1/models 自动拉取模型，Ace Data Cloud 返回的模型较多时界面会很长，建议在「模型列表 → 自定义模型名称」中手动填写一个 allow list，用英文逗号分隔。如需自定义显示名，可以用 =，例如 gpt-5=GPT-5 旗舰版。

推荐模型

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

家族 模型 ID 备注
GPT gpt-5、gpt-5-mini、gpt-4o OpenAI 旗舰 / 性价比 / 经典多模态
Claude claude-opus-4-8、claude-sonnet-4-6 Anthropic 旗舰 / 均衡
Gemini gemini-3.1-pro、gemini-3-flash-preview Google 多模态 / 快速
Grok grok-4 xAI，原生联网
DeepSeek deepseek-v3 高性价比，中文友好
Kimi kimi-k3 推理、视觉、超长上下文

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

验证对接

如果不确定问题出在 LobeChat 还是网络，可以先用 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 有效但余额不足，到 控制台 充值即可。

进阶：Docker 自部署

如果希望部署一份私有版给团队使用，可用 Docker 一行命令启动（把 {token} 替换为你的 Token）：

1
2
3
4
5
6
7
8
 
docker run -d \
  --name lobe-chat \
  -p 3210:3210 \
  -e OPENAI_API_KEY={token} \
  -e OPENAI_PROXY_URL=https://api.acedata.cloud/v1 \
  -e ACCESS_CODE=your-secret-password \
  -e OPENAI_MODEL_LIST="gpt-5,claude-opus-4-8,gemini-3.1-pro,grok-4,deepseek-v3" \
  lobehub/lobe-chat:latest

打开 http://你的服务器IP:3210，输入 ACCESS_CODE 即可使用，团队成员无需各自填写 Key。上面用到的 OPENAI_API_KEY、OPENAI_PROXY_URL、OPENAI_MODEL_LIST 等环境变量的完整说明见 LobeChat 模型服务商环境变量文档。若用 nginx 反向代理加 HTTPS，请务必加上 proxy_buffering off;，否则流式响应会被缓冲。更多部署形态请参考 LobeChat 自部署入门 与 Docker Compose 部署。

常见问题

提示 404 Not Found

通常是 API 代理地址写成了 .../openai/v1 或漏了 /v1。改成 https://api.acedata.cloud/v1。

模型列表为空

打开「客户端请求模式」开关；或在「自定义模型名称」中手动填写模型 allow list。

提示 401 Unauthorized

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

了解更多

作者 发表于 阅读次数： 本文字数： 2.7k 阅读时长 ≈ 2 分钟

API 开发教程

Ace Data Cloud 提供 TypeScript / Python / Go 三种语言的官方客户端 SDK，把 api.acedata.cloud 上的 chat completions、images、video、music、search、x402 等能力封装成强类型方法，省去手写 HTTP、SSE、任务轮询、错误处理和重试退避的工作。

本章按真实接入顺序组织：先在控制台拿到 API Token，再选语言看对应章节，最后看任务轮询、流式响应和 X402 链上支付的高级用法。

仓库与包

三语言能力矩阵

能力 TypeScript Python Go
chat.completions.create（非流式） ✅ ✅ ✅
chat.completions.create（SSE 流式） ✅ ✅ ✅
images.generate（Midjourney / Flux / NanoBanana / Seedream） ✅ ✅ 🚧 (alpha)
videos.generate（Sora / Veo / Luma / Kling / Hailuo / Wan） ✅ ✅ 🚧 (alpha)
audios.generate（Suno / Producer / Fish） ✅ ✅ 🚧 (alpha)
search.google（Serp） ✅ ✅ 🚧 (alpha)
TaskHandle 异步轮询 ✅（毫秒） ✅（秒） 🚧
异步客户端 ✅ (Promise) ✅ (AsyncAceDataCloud) ✅ (context.Context)
自动重试 + 指数退避 ✅ ✅ ✅
类型化异常（AuthenticationError / RateLimitError …） ✅ ✅ ✅
X402 paymentHandler 钩子（无 token 链上付费） ✅ ✅ ❌（计划中）

Go SDK 的多媒体资源和任务轮询当前处于 alpha 阶段（伪版本 v0.0.0-20260505072132-4a3d921f9bb4），稳定的能力是 chat.completions。多媒体场景请优先选 TypeScript 或 Python。

何时用 SDK / MCP / 原生 HTTP / X402

场景 推荐方式
后端服务、CLI、自动化脚本、Agent 框架 SDK（本章）
Claude Desktop / Cursor / Cline 等 MCP 客户端调用 MCP Servers
一次性 curl 验证、调试、嵌入式只支持 HTTP 的环境 原生 HTTP（每个服务的 快速开始）
不想创建 API Token、按调用链上付 USDC X402 集成指南

SDK 与 X402 不互斥：SDK 同时支持「token 路径」和「paymentHandler 路径」，详见 SDK + X402 支付钩子。

申请 API Token

要使用 SDK，首先到 Ace Data Cloud 控制台 - 应用列表 申请一个 API Token：

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

在首次申请时会有免费额度赠送，可以免费体验 Ace Data Cloud 提供的各种 AI 服务。

复制刚才拿到的 Token，下面统一记作 {token}。

统一环境变量

三种语言的 SDK 都会自动读取同一个环境变量 ACEDATACLOUD_API_TOKEN，推荐在 shell 里 export，让 SDK 自动拾取：

1
2
3
 
export ACEDATACLOUD_API_TOKEN={token}
# 可选：默认 https://api.acedata.cloud
# export ACEDATACLOUD_BASE_URL=https://api.acedata.cloud

也可以在构造客户端时显式传入，三种语言对应的参数名分别是：

  • TypeScript：new AceDataCloud({ apiToken: '{token}' })
  • Python：AceDataCloud(api_token="{token}")
  • Go：adc.NewClient(adc.WithAPIToken("{token}"))

注意：AceDataCloud 项目仓库里约定俗成是 ACEDATACLOUD_API_KEY（在 .env / CI 里），但这三个 SDK 本身只识别 ACEDATACLOUD_API_TOKEN。如果你的环境里只有 ACEDATACLOUD_API_KEY，请在构造时显式传入。

30 秒上手三例

下面三段代码做的是同一件事：调用 gpt-4o-mini，让它只回复 ADC_*_OK。每段都附了真实运行结果，可以拿你自己的 token 复现。

TypeScript

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
 
import { AceDataCloud } from '@acedatacloud/sdk';

const client = new AceDataCloud({ apiToken: process.env.ACEDATACLOUD_API_KEY });

const t0 = Date.now();
const res = await client.openai.chat.completions.create({
  model: 'gpt-4o-mini',
  messages: [{ role: 'user', content: 'Reply with exactly: ADC_TS_SDK_OK' }],
  max_tokens: 20,
  temperature: 0
});
console.log('elapsed_ms', Date.now() - t0);
console.log('id', res.id);
console.log('model', res.model);
console.log('content', res.choices[0].message.content);
console.log('usage', JSON.stringify(res.usage));

SDK 当前把响应声明为 Record<string, unknown>，运行时是一个普通 JSON 对象，可以直接按字段访问。在严格 TS 项目里如果遇到类型报错，可以临时 as any，或者参考 SDK 任务轮询与流式响应 自定义 typed wrapper。

程序运行结果：

1
2
3
4
5
 
elapsed_ms 2543
id chatcmpl-DldCcLvkTFaioST8e6SjOl0wJScQA
model gpt-4o-mini
content ADC_TS_SDK_OK
usage {"prompt_tokens":16,"completion_tokens":6,"total_tokens":22}

Python

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
 
import os, time, json
from acedatacloud import AceDataCloud

client = AceDataCloud(api_token=os.environ["ACEDATACLOUD_API_KEY"])

t0 = time.time()
res = client.openai.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Reply with exactly: ADC_PY_SDK_OK"}],
    max_tokens=20,
    temperature=0,
)
print("elapsed_ms", int((time.time() - t0) * 1000))
print("id", res["id"])
print("model", res["model"])
print("content", res["choices"][0]["message"]["content"])
print("usage", json.dumps({k: v for k, v in res["usage"].items()
                            if k in ("prompt_tokens","completion_tokens","total_tokens")}))

Python SDK 当前返回的是 dict，所以用 res["id"] 而不是 res.id。这一点和 openai-python 不同，迁移时需要注意。

程序运行结果：

1
2
3
4
5
 
elapsed_ms 2963
id chatcmpl-DldFdnIlhSUXINpupgsUmZL78MnBu
model gpt-4o-mini
content ADC_PY_SDK_OK
usage {"prompt_tokens": 17, "completion_tokens": 7, "total_tokens": 24}

Go

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

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

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

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

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

Go SDK 的响应统一是 map[string]any，没有强类型 struct，需要自行类型断言。所有资源访问器都是方法链：client.OpenAI().Chat().Completions().Create(...)。

程序运行结果：

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

三种语言的响应里 id、elapsed_ms、usage 来源都一致：经 PlatformGateway 鉴权 → 上游 OpenAI 兼容服务 → 写入计费记录。content 字段是模型真实输出，用固定标识 ADC_*_OK 是为了证明响应没有被 SDK 篡改。

推荐阅读顺序

  1. TypeScript SDK 接入教程 —— npm install 之后第一段可以跑起来的代码。
  2. Python SDK 接入教程 —— 同步、异步、流式三套用法。
  3. Go SDK 接入教程 —— Go 风格的 context.Context 和 channel 流式。
  4. SDK 任务轮询与流式响应 —— TaskHandle 单位差异、SSE 实现细节、重试退避。
  5. SDK + X402 支付钩子 —— 无 token，按调用上链结算。

如何查看剩余额度

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

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

了解更多

作者 发表于 阅读次数： 本文字数： 5.6k 阅读时长 ≈ 5 分钟

产品推广

摘要 / 概览

Ace Data Cloud 是一个以使用为先的 AI 基础设施平台，旨在支持真实的生产级 AI 系统。它使构建者、团队和自主代理能够通过按使用付费的 API、可编程工作流和原生结算访问 AI 服务，无需面对分散工具、订阅或手动计费的摩擦。

Ace 将 AI API、工作流编排、应用部署和支付结算统一到一个协调的环境中。该平台面向需要可预测成本、持续执行和可靠大规模运行基础设施的开发者、产品团队、创作者和 AI 代理。

相关入口：

随着 AI 系统越来越多地从实验转向自主、长时间运行，现有的基础设施模式已无法满足需求。Ace 致力于提供一个支持原生使用访问、机器对机器支付和透明价值流动的基础。

问题陈述

AI 基础设施的碎片化

当前 AI 生态系统在提供商、工具和计费层面存在碎片化：

  • 聊天、图像、视频、音乐和数据服务各自独立的 API
  • 每个提供商独立的订阅和定价模型
  • 手动账户设置和 API 密钥管理
  • 分离的工作流和自动化工具
  • 设计为人工交互的支付系统，而非自动执行

这种碎片化增加了运营复杂性，提高了成本，并引入了不必要的故障点。

为什么这会破坏真实的 AI 系统

对于生产系统和自主代理，这些限制无法扩展：

  • 订阅与可变或机器驱动的使用不匹配
  • 手动计费阻碍持续执行
  • 支付延迟和对账打断实时工作流
  • 构建者花费过多精力管理基础设施而非业务逻辑

随着 AI 系统向持续运行和自动化发展，现有解决方案无法满足真实使用需求。

Ace Data Cloud 概览

Ace Data Cloud 是一个统一的 AI 与 Web3 基础设施平台，围绕使用而非访问构建。

Ace Data Cloud 是一个基础设施平台，使 AI 服务、工作流和应用能够在按使用付费模式下运行，并支持原生结算。

Ace 不是演示平台、单一 AI 产品或投机代币项目。它是设计用于支持真实工作负载、真实支付和持续执行的基础设施。

平台理念简单明了：

使用应可度量，成本应可预测，价值应透明流动。

核心架构

Ace 将多个核心层协调为一个系统。

身份与账户

用户通过 Ace OAuth 认证，链接身份、使用和结算，无需手动配置或分散账户管理。

API 与服务

Ace 通过统一 API 提供多种 AI 服务的标准化访问——包括聊天、图像生成、视频生成、音乐和歌词等。

工作流

工作流自动化由 Dify 驱动，允许用户将 AI 操作、逻辑和条件串联成可重复的生产级系统。

部署

Nexior 提供部署层，支持无需从零构建前端、支付逻辑或使用跟踪即可发布完整 AI 应用。

支付与结算

x402 利用 Base 和 Solana 上的 USDC 实现机器对机器的按使用付费结算。

积分系统

积分作为平台统一的使用单位，抽象支付复杂性，同时保持透明的账务。

典型流程：

1
 
用户注册 → 选择服务或工作流 → 执行使用 → 消耗积分 → 自动结算 → 使用被跟踪。

产品组件

AI API

Ace 提供生产级 AI API，涵盖聊天、图像生成、视频生成、音乐、歌词及相关服务。这些 API 被构建者、工作流、已部署应用和自主代理使用。

工作流自动化（Dify）

Dify 使用户能够编排多步骤 AI 工作流，无需管理基础设施或集成代码。

Nexior

Nexior 是一个开放部署层，允许用户启动带有内置使用跟踪和变现功能的完整 AI 平台。对应的在线体验站为 https://studio.acedata.cloud。

MCP 服务器

模型上下文协议服务器允许外部工具、IDE 和代理以编程方式与 Ace 服务交互。

x402 支付

x402 支持基于 USDC 的按请求结算，免除订阅或手动计费需求。

积分系统

积分提供一致的服务消费方式，同时维护平台内清晰的定价和账务。

基于使用的支付与 x402

订阅模式与自主系统或可变工作负载不匹配。按使用付费定价直接将成本与执行挂钩。

x402 支持：

  • 机器对机器支付
  • 确定性结算
  • 原生使用计费

Ace 在 Base 和 Solana 上使用 USDC 支持 x402，实现快速结算和可预测成本。通过 x402 结算的用户可享受使用折扣，降低高频和自动化工作负载的摩擦。

该模式消除对传统支付处理器的依赖，支持持续、实时执行。

$ACE 代币效用

$ACE 是 Ace Data Cloud 的生态代币。

$ACE 的用途

  • 平台服务的使用折扣
  • 内部协调与账务
  • 参与平台收入飞轮

$ACE 与使用的关联

随着平台使用增加，产生费用。部分费用用于回购和生态支持，将真实使用与代币活动关联起来。

$ACE 不是

$ACE 不作为投资产品、投机治理资产或价格驱动工具。其角色是支持平台经济和协调。

经济模型与收入飞轮

Ace 通过以下方式产生收入：

  • 平台服务使用
  • 创作者和工作流费用

收入分配用于：

  • 基础设施与运营
  • 产品开发
  • 生态增长
  • 代币回购

回购和流动性操作在链上透明执行。

目标用户与使用场景

构建者

集成 AI API 和工作流，无需管理多个供应商或计费系统。

AI 代理

以可预测的按使用成本运行持续自主工作流。

非技术创作者

使用 Nexior 部署 AI 应用，无需编写代码。

团队与公司

运行 AI 系统，具备清晰账务、可预测成本和可扩展基础设施。

路线图与方向

Ace 遵循渐进、以使用驱动的路线图。

  • 已发布： 核心 API、工作流、x402 结算、积分系统、Nexior
  • 进行中： 移动应用、扩展服务、更深层代理支持
  • 方向： 更广泛集成、更多服务、提升易用性

路线图更新公开发布。

安全、透明与信任

  • 链上透明的回购与流动性
  • 平台级使用跟踪
  • 适当开源组件

结论

Ace Data Cloud 致力于让 AI 基础设施适用于真实系统。通过聚焦使用、透明和协调，平台避免短期叙事，优先考虑持久性。

Ace 随实际需求增长而非投机，提供设计用于持续运行、负责任扩展和支持下一代 AI 系统的基础设施。

作者 发表于 阅读次数： 本文字数： 2.3k 阅读时长 ≈ 2 分钟

技术教程

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

Luma AI 的 Dream Machine 视频模型，运镜自然、物理感强、支持 image-to-video。通过 MCP 接入 Codex CLI 后，可以直接在对话里调用，不用切窗口、不用复制粘贴。

获取 API Token

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

配置

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

1
2
3
4
5
 
[mcp_servers.luma]
url = "https://luma.mcp.acedata.cloud/mcp"
type = "http"

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

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

使用示例

用 Luma 生成一段 5 秒视频：海面上的灯塔，夜晚，浪花拍打

把这张产品图（链接 xxx）做成一个 360 度旋转展示视频

把前面这段 5 秒视频续写到 10 秒，保持镜头风格

工具

工具 说明
luma_generate_video 文生视频 / 图生视频 / 视频续写

相关链接

作者 发表于 阅读次数： 本文字数： 595 阅读时长 ≈ 1 分钟

API 开发教程

本文将介绍人脸静态活体检测（高精度版）API 对接说明，它可用于对用户上传的静态图片进行防翻拍活体检测，以判断是否是翻拍图片。

申请流程

要使用 人脸静态活体检测（高精度版） API，首先到 Ace Data Cloud 控制台 获取您的 API Token，留作备用。

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

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

📘 完整文档：人脸静态活体检测（高精度版） API →

基本使用

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

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

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

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

另外设置了 Request Body，包括：

  • image_url：需要处理的人脸图片链接。
  • face_model_version：人脸识别服务所用的算法模型版本。目前入参支持“3.0“。

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

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

1
2
3
4
 
{
  "score": 0,
  "face_model_version": "3.0"
}

可以看到这时候我们就得到了此处人脸静态活体检测的结果，包括了活体打分的内容。

字段说明如下：

  • score ：活体打分，取值范围 [0,100]，根据活体分数对应的阈值区间来判断是否为翻拍。目前阈值可分为[5,10,40,70,90]，其中推荐阈值为40。
  • face_model_version：人脸识别所用的算法模型版本。

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

1
2
3
4
5
6
7
 
curl -X POST 'https://api.acedata.cloud/face/detect-live' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "image_url": "https://cdn.acedata.cloud/lrbtcn.jpg"
}'

Python 的对接代码如下：

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

url = "https://api.acedata.cloud/face/detect-live"

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

payload = {
    "image_url": "https://cdn.acedata.cloud/lrbtcn.jpg"
}

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

错误处理

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

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

错误响应示例

1
2
3
4
5
6
7
8
 
{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

结论

通过本文档，您已经了解了如何使用 人脸静态活体检测（高精度版） API 可用于对用户上传的静态图片进行防翻拍活体检测，以判断是否是翻拍图片。希望本文档能帮助您更好地对接和使用该 API。如有任何问题，请随时联系我们的技术支持团队。

作者 发表于 阅读次数： 本文字数： 2.1k 阅读时长 ≈ 2 分钟

技术教程

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

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

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

什么是 MCP？

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

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

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

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

在 Claude.ai 网页版添加 Seedream MCP

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

1. 打开 Connectors 设置

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

Claude.ai Customize Connectors

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

2. 添加 Seedream MCP Server

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

字段 值
Name Seedream（随便取）
URL https://seedream.mcp.acedata.cloud/mcp

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

3. OAuth 授权

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

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

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

Seedream Connector 工具列表

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

实测：一句英文 Prompt 出图

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

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

Claude 收到后做的事情：

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

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

Claude.ai 中 Seedream 生成结果

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

Seedream 出图

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

更多玩法（同样一个 Connector）

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

先查可用尺寸再出图

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

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

改图 / 局部修改

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

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

中文 prompt 直出

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

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

批量生成多张候选

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

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

常见问题

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

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

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

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

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

相关链接

作者 发表于 阅读次数： 本文字数： 3.2k 阅读时长 ≈ 3 分钟

MCP 教程

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

功能概览

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

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

前置准备

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

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

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

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

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

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

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

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

Claude Desktop

编辑配置文件：

  • macOS：~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows：%APPDATA%\Claude\claude_desktop_config.json
1
2
3
4
5
6
7
8
9
10
11
 
{
  "mcpServers": {
    "nanobanana": {
      "type": "http",
      "url": "https://nanobanana.mcp.acedata.cloud/mcp",
      "headers": {
        "Authorization": "Bearer 你的API Token"
      }
    }
  }
}

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

Claude Code（终端命令行）

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

VS Code（GitHub Copilot）

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

1
2
3
4
5
6
7
8
9
10
11
 
{
  "servers": {
    "nanobanana": {
      "type": "http",
      "url": "https://nanobanana.mcp.acedata.cloud/mcp",
      "headers": {
        "Authorization": "Bearer 你的API Token"
      }
    }
  }
}

Cursor

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

1
2
3
4
5
6
7
8
9
10
 
{
  "mcpServers": {
    "nanobanana": {
      "url": "https://nanobanana.mcp.acedata.cloud/mcp",
      "headers": {
        "Authorization": "Bearer 你的API Token"
      }
    }
  }
}

其他支持 MCP 的客户端

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

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

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

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

安装

pip 安装（推荐）：

1
 
pip install mcp-nanobanana-pro

或源码安装：

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

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

在 Claude Desktop 中使用（本地）

编辑 Claude Desktop 配置文件：

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

添加以下配置：

1
2
3
4
5
6
7
8
9
10
 
{
  "mcpServers": {
    "nanobanana": {
      "command": "mcp-nanobanana-pro",
      "env": {
        "ACEDATACLOUD_API_TOKEN": "你的API Token"
      }
    }
  }
}

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

1
2
3
4
5
6
7
8
9
10
11
 
{
  "mcpServers": {
    "nanobanana": {
      "command": "uvx",
      "args": ["mcp-nanobanana-pro"],
      "env": {
        "ACEDATACLOUD_API_TOKEN": "你的API Token"
      }
    }
  }
}

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

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

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

1
2
3
4
5
6
7
8
9
10
 
{
  "servers": {
    "nanobanana": {
      "command": "mcp-nanobanana-pro",
      "env": {
        "ACEDATACLOUD_API_TOKEN": "你的API Token"
      }
    }
  }
}

或者使用 uvx：

1
2
3
4
5
6
7
8
9
10
11
 
{
  "servers": {
    "nanobanana": {
      "command": "uvx",
      "args": ["mcp-nanobanana-pro"],
      "env": {
        "ACEDATACLOUD_API_TOKEN": "你的API Token"
      }
    }
  }
}

可用工具列表

工具名 说明
nanobanana_generate_image 通过文本提示词生成图像
nanobanana_edit_image 编辑或组合已有图像
nanobanana_get_task 查询单个任务状态
nanobanana_get_tasks_batch 批量查询任务状态

使用示例

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

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

更多信息

作者 发表于 阅读次数： 本文字数： 3.5k 阅读时长 ≈ 3 分钟

API 开发教程

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

申请流程

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

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

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

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

基本使用

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

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

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

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

另外设置了 Request Body，包括：

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

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

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

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

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

</p >

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

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

1
2
3
4
5
6
7
8
9
10
11
 
curl -X POST 'https://api.acedata.cloud/face/beautify' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "image_url": "https://cdn.acedata.cloud/lrbtcn.jpg",
  "smoothing": 50,
  "whitening": 50,
  "face_lifting": 50,
  "eye_enlarging": 50
}'

Python 的对接代码如下：

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

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

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

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

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

错误处理

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

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

错误响应示例

1
2
3
4
5
6
7
8
 
{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

结论

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

作者 发表于 阅读次数： 本文字数： 2.5k 阅读时长 ≈ 2 分钟

API 开发教程

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

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

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

申请流程

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

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

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

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

基本使用

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

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

Request Headers 包括：

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

Request Body 主要包括：

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

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

字段 类型 必填 说明
prompt string 是 用自然语言描述要做的视频（主题、要展示什么、风格、受众）。脚本、画面、配音、剪辑都由 AI 决定
action string 否 generate（默认，生成新视频）/ remix / edit / extend（在已有视频上迭代，需配合 ref_task_id）
ref_task_id string 否 当 action 为 remix / edit / extend 时必填：作为起点的历史任务 task_id
file_urls string[] 否 参考媒体（图片 / 视频 / 音频 URL），例如要出镜的产品图、logo，或要加字幕的素材片段
langs string[] 否 输出语言，如 ["zh-cn", "en"]，默认 ["zh-cn"]。第一个为主语言；每多一种语言复用画面、只多配音 + 渲染，每多一种 +6 积分
aspect string 否 9:16（默认）/ 16:9 / 1:1（画面比例提示，AI 可能依据 prompt 调整）
duration int 否 目标时长（秒，1–600，即最长 10 分钟），默认 30。按实际成片时长计费，越长越贵（见下方计费）
quality string 否 制作档位（作用在时长价格上的倍率）：draft（快速预览粗剪，约为标准档 0.5×）/ standard（默认，均衡，1×）/ premium（更精细、更出彩，耗时更久，约为标准档 2×）
scenario string 否 视频类型路由提示（仅为提示，AI 导演仍决定最终结构）：auto（默认）/ narrated（多场景真实照片 + 旁白 + 数据卡）/ drama（角色 + 对白的短剧）/ avatar（数字人 / 口播，需用 file_urls 传人像）/ motion（抽象动感字幕 / 数据 / logo 动效）/ slideshow（演示 / 路演 deck）
style string 否 视觉风格预设：auto（默认）/ cinematic / glass / luxury / swiss / modern / editorial / warm / vibrant / neon / mono / pastel / bold / industrial / futuristic / retro，也接受自由文本作为软提示。与 scenario 正交、不改变路由
voice string 否 旁白音色（与语言无关，跨语言通用）：auto（默认）/ warm-female / bright-female / anchor-female / clean-female / calm-male / deep-male / documentary-male / energetic-male / storyteller-male

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

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

对应的 Python 代码如下：

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

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

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

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

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

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

1
2
3
4
5
 
{
  "success": true,
  "task_id": "f57e99c4f60f4373a15517742ce2357d",
  "trace_id": "70e1cb12-c619-4292-a416-90191205996b"
}

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

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

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

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

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

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

填写样例的 CURL 代码如下：

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

常见的搭配方式：

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

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

多语言输出

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

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

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

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

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

1
2
3
4
5
6
7
8
9
 
curl -X POST 'https://api.acedata.cloud/maestro/videos' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "action": "remix",
  "ref_task_id": "f57e99c4f60f4373a15517742ce2357d",
  "prompt": "把开场标题换成更有冲击力的一句，整体配色更暗一些"
}'
  • remix：在原视频结构上重新演绎（保留主题，调整表现）。
  • edit：对指定局部做精修（如换标题、换配音、调色）。
  • extend：在原视频基础上延展内容。

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

取结果

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

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

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

计费

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

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

1
 
积分 ≈ 0.85 × 成片时长秒 × 质量倍率 × 场景倍率 + 6 × max(语言数 − 1, 0)
  • 质量倍率：draft 0.5× / standard 1×（默认）/ premium 2×。
  • 场景倍率：drama 1.35× / avatar 1.15× / 其他 1×。

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

成片时长 标准档积分
30s 25.5
60s 51
120s（2 分钟） 102
300s（5 分钟） 255
600s（10 分钟，上限） 510
每多一种语言（langs 超过 1 种，每多一种） +6
/maestro/tasks 轮询 免费

错误处理

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

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

错误响应示例

1
2
3
4
5
6
7
8
 
{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

结论

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

相关接口

作者 发表于 阅读次数： 本文字数： 6.3k 阅读时长 ≈ 6 分钟

技术教程

📘 Overview：OpenCode MCP Overview →

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

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

获取 API Token

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

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

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

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

配置 OpenCode

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

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

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

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

全局：所有项目共用

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

1
2
3
4
5
6
7
8
9
10
11
12
 
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "flux": {
      "type": "remote",
      "url": "https://flux.mcp.acedata.cloud/mcp",
      "enabled": true,
      "oauth": false,
      "headers": { "Authorization": "Bearer {env:ACEDATACLOUD_API_KEY}" }
    }
  }
}

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

项目级：仅当前项目生效

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

1
2
3
4
5
6
7
8
9
10
11
12
 
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "flux": {
      "type": "remote",
      "url": "https://flux.mcp.acedata.cloud/mcp",
      "enabled": true,
      "oauth": false,
      "headers": { "Authorization": "Bearer {env:ACEDATACLOUD_API_KEY}" }
    }
  }
}

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

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

真实运行结果

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

1
2
3
4
5
6
7
8
9
10
11
 
$ opencode --version
1.15.13

$ opencode mcp list

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

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

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

1
 
opencode mcp debug flux

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

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

典型场景

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

快速出图

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

Kontext 编辑现有图

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

生成产品 hero 图

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

工具列表

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

工具 说明
flux_generate_image 文生图（Flux pro / dev / ultra）
flux_edit_image 对已有图按提示词编辑（Flux Kontext pro / max）

相关链接

作者 发表于 阅读次数： 本文字数： 3.6k 阅读时长 ≈ 3 分钟

API 开发教程

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

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

源码与文档：

安装

1
 
go get github.com/AceDataCloud/SDK/go

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

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

结果说明：

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

准备 API Token

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

1
 
export ACEDATACLOUD_API_TOKEN={token}

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

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

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

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

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

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

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

程序运行结果：

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

结果说明：

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

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

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

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

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

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

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

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

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

程序运行结果：

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

结果说明：

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

示例 3：类型化错误处理

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

import (
    "context"
    "errors"
    "fmt"

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

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

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

配置选项（functional options）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
 
client, err := adc.NewClient(
    // 必填：API token；建议从环境变量读
    adc.WithAPIToken(os.Getenv("ACEDATACLOUD_API_TOKEN")),

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

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

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

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

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

进阶：复用 Client

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
 
// pkg/acelearn/client.go
var sharedClient *adc.Client

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

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

局限和路线图

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

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

仍处于 alpha：

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

如何查看剩余额度

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

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

了解更多

作者 发表于 阅读次数： 本文字数： 6.6k 阅读时长 ≈ 6 分钟

API 开发教程

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

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

教程 适用场景 链接
快速开始 先用一个最小请求理解 402、accepts 和 PAYMENT-SIGNATURE 流程 X402 快速开始
TypeScript SDK 在浏览器、Node.js 或前端应用中调用 Ace Data Cloud API TypeScript SDK 接入
Python SDK 在 Python 服务、脚本、Agent 或数据流水线中调用 API Python SDK 接入
订单支付 用 X402 支付 Ace Data Cloud 控制台订单 订单支付教程
网络与支付方式 了解 Base、SKALE、Solana 的资产、签名和适用场景 网络与支付方式
exact 与 upto 区分固定价格 API 和用量后置结算 API 计费方案说明
价格说明 了解 X402 价格与 Credits 单价的关系，及各服务真实价格 X402 价格说明
Facilitator 理解 verify、settle 和自建收款 API 的服务端链路 Facilitator 集成
E2E 与故障排查 检查公开入口、运行高级验证工具，定位常见 402、签名和结算问题 E2E 验证与故障排查

推荐接入路径

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

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

公开源码与包地址：

项目 地址
Ace Data Cloud SDK https://github.com/AceDataCloud/SDK
X402 Client https://github.com/AceDataCloud/X402Client
X402 Facilitator https://github.com/AceDataCloud/FacilitatorX402
npm SDK https://www.npmjs.com/package/@acedatacloud/sdk
npm X402 Client https://www.npmjs.com/package/@acedatacloud/x402-client
PyPI SDK https://pypi.org/project/acedatacloud/
PyPI X402 Client https://pypi.org/project/acedatacloud-x402/

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

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

支持状态

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

能力 状态 说明
402 discovery 可用 https://x402.acedata.cloud/.well-known/x402 返回公开发现文档。
API 402 accepts 可用 未支付请求会返回 Base、SKALE 和 Solana 的可用 payment requirement。
TypeScript SDK 可用 @acedatacloud/sdk 与 @acedatacloud/x402-client 可自动处理 402、签名和重试。
Python SDK 可用 acedatacloud 与 acedatacloud-x402 可自动处理 402、签名和重试。
Base exact 已链上验证 适合固定金额 API 和订单支付。
Base upto 已链上验证 适合聊天补全等后置计量 API，当前唯一提供 upto 的网络。
SKALE exact 已链上验证 适合低 gas 成本的 EVM 支付场景。
Solana exact HTTP paid retry 已验证 已验证 API paid retry 与模型响应；链上签名确认建议使用自有 Solana RPC 对账。
订单支付 已链上验证 Base exact 订单支付已完成链上结算并更新订单状态。

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
 
packages
@acedatacloud/sdk@2026.504.2 import ok
@acedatacloud/x402-client@2026.531.3 import ok
acedatacloud==2026.4.26.1 import ok
acedatacloud-x402==2026.5.31.3 import ok

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

TypeScript SDK
content ADC_TS_SDK_X402_OK

Python SDK
content ADC_PY_SDK_X402_OK

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

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

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

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

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

说明：

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

接入注意事项

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

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

可以公开核验的范围

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

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

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

作者 发表于 阅读次数： 本文字数： 4.8k 阅读时长 ≈ 4 分钟

API 开发教程

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

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

申请流程

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

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

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

📘 完整文档：Grok Chat Completion API →

基本使用

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

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

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

常用可选参数：

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

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
 
{
  "id": "foaicmpl-13936918-cb99-49e1-b94c-bde98b482ed4",
  "model": "grok-4",
  "object": "chat.completion",
  "created": 1755839683,
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Yo! What's up? 😎 Ready to dive into whatever you're pondering about today?"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 8,
    "completion_tokens": 20,
    "total_tokens": 28,
    "prompt_tokens_details": {
      "cached_tokens": 0,
      "text_tokens": 0,
      "audio_tokens": 0,
      "image_tokens": 0
    },
    "completion_tokens_details": {
      "text_tokens": 0,
      "audio_tokens": 0,
      "reasoning_tokens": 0
    },
    "input_tokens": 0,
    "output_tokens": 0,
    "input_tokens_details": null
  }
}

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

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

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

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

流式响应

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

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

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

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

Python 样例调用代码：

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

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

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

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

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

输出效果如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
 
data: {"id": "foaicmpl-503ab14f-3f22-46ab-9f91-3fb44773be38", "object": "chat.completion.chunk", "created": 1755839790, "model": "grok-3", "system_fingerprint": null, "choices": [{"delta": {"role": "assistant"}, "logprobs": null, "finish_reason": null, "index": 0}], "usage": null}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

data: [DONE]

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

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

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
 
const options = {
  method: "post",
  headers: {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
  },
  body: JSON.stringify({
    "model": "grok-3",
    "messages": [{"role":"user","content":"Hello"}],
    "stream": true
  })
};

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

Java 样例代码：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
 
JSONObject jsonObject = new JSONObject();
jsonObject.put("model", "grok-3");
jsonObject.put("messages", [{"role":"user","content":"Hello"}]);
jsonObject.put("stream", true);
MediaType mediaType = "application/json; charset=utf-8".toMediaType();
RequestBody body = jsonObject.toString().toRequestBody(mediaType);
Request request = new Request.Builder()
  .url("https://api.acedata.cloud/grok/chat/completions")
  .post(body)
  .addHeader("accept", "application/json")
  .addHeader("authorization", "Bearer {token}")
  .addHeader("content-type", "application/json")
  .build();

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

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

多轮对话

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

Python 样例调用代码：

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

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

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

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

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

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
 
{
  "id": "foaicmpl-984ebc53-76b3-4d33-b0e8-0307ab4965af",
  "model": "grok-3",
  "object": "chat.completion",
  "created": 1755839996,
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "You said, \"Hello.\""
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 27,
    "completion_tokens": 6,
    "total_tokens": 33,
    "prompt_tokens_details": {
      "cached_tokens": 0,
      "text_tokens": 0,
      "audio_tokens": 0,
      "image_tokens": 0
    },
    "completion_tokens_details": {
      "text_tokens": 0,
      "audio_tokens": 0,
      "reasoning_tokens": 0
    },
    "input_tokens": 0,
    "output_tokens": 0,
    "input_tokens_details": null
  }
}

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

错误处理

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

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

错误响应示例

1
2
3
4
5
6
7
8
 
{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

结论

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

作者 发表于 阅读次数： 本文字数： 13k 阅读时长 ≈ 12 分钟

API 开发教程

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

申请流程

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

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

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

📘 完整文档：Flux Images Generation API →

基本使用

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

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

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

另外设置了 Request Body，包括：

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

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

模型 范围
flux-dev 支持宽高比例 1024x1024、1024x1792、1792x1024，或图片比例
flux-pro 支持宽高比例 1024x1024、1024x1792、1792x1024，或图片比例
flux-2-flex 仅支持图片比例
flux-2-pro 仅支持图片比例
flux-2-max 仅支持图片比例
flux-kontext-pro 仅支持图片比例
flux-kontext-max 仅支持图片比例

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

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

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

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

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

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

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

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

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

编辑图片任务

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

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

填写样例如下：

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

对应的代码：

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

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

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

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

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

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

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

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

异步回调

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

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

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

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

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

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

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

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

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

内容如下：

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

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

错误处理

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

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

错误响应示例

1
2
3
4
5
6
7
8
 
{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

结论

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

作者 发表于 阅读次数： 本文字数： 4.9k 阅读时长 ≈ 4 分钟

API 开发教程

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

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

名词 & 端点速查

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

1
 
curl https://auth.acedata.cloud/.well-known/oauth-authorization-server
用途 端点
发现文档（Discovery） GET /.well-known/oauth-authorization-server
用户授权页（浏览器跳转） GET https://auth.acedata.cloud/oauth2/authorize
令牌端点（换 / 刷新 token） POST https://auth.acedata.cloud/oauth2/token
撤销令牌 POST https://auth.acedata.cloud/oauth2/revoke
用户信息（UserInfo） GET https://auth.acedata.cloud/api/v1/users/me
应用注册管理（自助） https://auth.acedata.cloud/user/oauth-apps

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

权限范围（Scope）

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

身份类（OIDC 兼容）

Scope 含义 /users/me 返回字段
openid 用户唯一标识 id
profile 基础资料 username、nickname、avatar、is_verified、date_joined
email 邮箱 email
phone 手机号（敏感） phone、region

平台资源类

Scope 含义
applications:read / applications:write 读 / 改 用户的服务订阅与额度
credentials:read / credentials:write 读 / 创建撤销 用户的 API Token
usage:read 读用户的调用历史
orders:read / orders:write 读订单 / 下单并发起支付

聚合类（自动展开）

Scope 展开为
platform:read applications:read + credentials:read + usage:read + orders:read
platform:write applications:write + credentials:write + orders:write
platform platform:read + platform:write

特殊

Scope 含义
offline_access 颁发 Refresh Token（不申请则只下发 Access Token，过期需重新授权）

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

第 1 步：注册一个 OAuth 应用

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

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

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

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

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

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

1
2
3
4
5
6
7
8
 
https://auth.acedata.cloud/oauth2/authorize
  ?response_type=code
  &client_id=<你的 client_id>
  &redirect_uri=<你注册的回调地址>
  &scope=openid%20profile%20credentials:read
  &state=<随机防 CSRF 串>
  &code_challenge=<PKCE 挑战值>          # 公开客户端必填
  &code_challenge_method=S256            # 公开客户端必填
  • state：自己生成的随机串，回调时原样带回，用来防 CSRF，务必校验。
  • PKCE（公开客户端必做，机密客户端也推荐）：先生成随机 code_verifier，再计算
    code_challenge = BASE64URL( SHA256( code_verifier ) )，把 code_challenge 放进授权 URL，
    code_verifier 自己留着第 4 步用。

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

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

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

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

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

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

机密客户端（带 client_secret）：

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

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

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

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

1
2
3
4
5
6
7
 
{
  "access_token": "<JWT>",
  "token_type": "Bearer",
  "expires_in": 1296000,
  "scope": "openid profile credentials:read",
  "refresh_token": "<JWT，仅 offline_access 时>"
}

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

第 4 步：用 Access Token 调用接口

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

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

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

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

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

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

刷新令牌

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

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

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

撤销令牌

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

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

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

常见错误

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

error 含义 / 排查
invalid_request 缺少或非法参数（如没传 code / client_id）
invalid_client client_id 不存在、应用被停用，或 client_secret 不对
invalid_grant 授权码不存在 / 已过期（>10 分钟）/ 已被用过 / PKCE 校验失败 / redirect_uri 与授权时不一致
access_denied 用户在授权页点了「拒绝」
unsupported_grant_type grant_type 不是 authorization_code 或 refresh_token

限制速查

项 值
每账号最多 OAuth 应用数 20
授权码有效期 10 分钟，单次使用
Access Token 有效期 15 天
Refresh Token 有效期 30 天（轮换）
redirect_uri 必须与注册值精确匹配
client_secret 仅创建 / 轮换时显示一次，服务端以 SHA-256 哈希存储

作者 发表于 阅读次数： 本文字数： 5.1k 阅读时长 ≈ 5 分钟

API 开发教程

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

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

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

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

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

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

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

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

结果如下：

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

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

作者 发表于 阅读次数： 本文字数： 900 阅读时长 ≈ 1 分钟

技术教程

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

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

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

第 2 步：获取并填写 API Key

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

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

第 3 步：验证已连通

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

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

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
 
{
  "servers": {
    "veo": {
      "type": "http",
      "url": "https://veo.mcp.acedata.cloud/mcp",
      "headers": {
        "Authorization": "Bearer ${input:acedata-api-key}"
      }
    }
  },
  "inputs": [
    {
      "id": "acedata-api-key",
      "type": "promptString",
      "description": "Ace Data Cloud API Key",
      "password": true
    }
  ]
}

第 3 步：验证已连通

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

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

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
 
{
  "servers": {
    "veo": {
      "type": "http",
      "url": "https://veo.mcp.acedata.cloud/mcp",
      "headers": {
        "Authorization": "Bearer ${input:acedata-token}"
      }
    }
  },
  "inputs": [
    {
      "id": "acedata-token",
      "type": "promptString",
      "description": "Ace Data Cloud API key",
      "password": true
    }
  ]
}

第 3 步：验证已连通

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

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

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
 
{
  "servers": {
    "veo": {
      "type": "http",
      "url": "https://veo.mcp.acedata.cloud/mcp",
      "headers": {
        "Authorization": "Bearer ${input:acedata-token}"
      }
    }
  },
  "inputs": [
    {
      "id": "acedata-token",
      "type": "promptString",
      "description": "Ace Data Cloud API key",
      "password": true
    }
  ]
}

实战示例

文字生成视频

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

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

图片生成视频

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

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

带音频生成视频

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

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

工具列表

工具 说明
veo_text_to_video 文本生成视频
veo_image_to_video 图片生成视频
veo_get_1080p 取 1080p 高清版本

其他编辑器配置

相关链接

作者 发表于 阅读次数： 本文字数： 2.4k 阅读时长 ≈ 2 分钟

API 开发教程

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

申请方法

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

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

使用方法

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

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

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

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

命令测试

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

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

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

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

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

运行结果如下：

1
2
3
4
5
6
7
8
9
10
11
12
 
{
  "ip": "66.206.249.77",
  "hostname": "host-66-206-249-77.public.eastlink.ca",
  "city": "Kirkland Lake",
  "region": "Ontario",
  "country": "CA",
  "loc": "48.1446,-80.0377",
  "org": "AS11260 EastLink",
  "postal": "P2N",
  "timezone": "America/Toronto",
  "readme": "https://ipinfo.io/missingauth"
}

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

代码对接

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

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

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

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

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

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

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

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

运行结果如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
 
{
  "ip": "103.190.205.165",
  "hostname": "assigned-for-client.adnsl.com",
  "city": "Paltan",
  "region": "Dhaka Division",
  "country": "BD",
  "loc": "23.7362,90.4143",
  "org": "AS38203 ADN Telecom Ltd.",
  "postal": "1000",
  "timezone": "Asia/Dhaka",
  "readme": "https://ipinfo.io/missingauth"
}
{
  "ip": "74.111.25.181",
  "hostname": "pool-74-111-25-181.syrcny.fios.verizon.net",
  "city": "Syracuse",
  "region": "New York",
  "country": "US",
  "loc": "43.0481,-76.1474",
  "org": "AS701 Verizon Business",
  "postal": "13201",
  "timezone": "America/New_York",
  "readme": "https://ipinfo.io/missingauth"
}
{
  "ip": "207.113.168.248",
  "city": "LaPorte",
  "region": "Indiana",
  "country": "US",
  "loc": "41.6106,-86.7225",
  "org": "AS13428 Surf Air Wireless, LLC",
  "postal": "46350",
  "timezone": "America/Chicago",
  "readme": "https://ipinfo.io/missingauth"
}

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

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

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

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

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

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

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

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

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

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

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
 
const axios = require("axios");
const base64 = require("base64");

const proxy_host = "global.proxy.acedata.cloud";
const proxy_port = "30007";
const proxy_username = "{proxy_username}"; // 8位用户名
const proxy_password = "{proxy_password}"; // 32位密码

const credentials = base64.encode(`${proxy_username}:${proxy_password}`);

const proxies = {
  http: `http://${proxy_host}:${proxy_port}`,
  https: `http://${proxy_host}:${proxy_port}`,
};

const headers = {
  "Proxy-Authorization": `Basic ${credentials}`,
};

for (let i = 0; i < 3; i++) {
  axios
    .get("https://ipinfo.io", { proxies, headers })
    .then((resp) => console.log(resp.data))
    .catch((err) => console.error(err));
}

运行效果都是一样的。

对于其他语言的设置方法，请参考上文自行改写即可。

地区筛选

我们可以通过在 username 里面添加 region 来进行地区的筛选，例如如果要选择美国的代理，原来的 username 是 1f78266a，则可以把 username 修改为 1f78266a-region-us，上述的 curl 就可以改写如下：

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

地区列表：

国家或地区名称 国家/地区代码
美国 us
香港 hk
安道尔 ad
阿联酋 ae
阿富汗 af
安提瓜和巴布达 ag
安圭拉 ai
阿尔巴尼亚 al
亚美尼亚 am
安哥拉 ao
南极洲 aq
阿根廷 ar
美属萨摩亚 as
奥地利 at
澳大利亚 au
阿鲁巴 aw
奥兰群岛 ax
阿塞拜疆 az
波黑 ba
巴巴多斯 bb
孟加拉 bd
比利时 be
布基纳法索 bf
保加利亚 bg
巴林 bh
布隆迪 bi
贝宁 bj
圣巴泰勒米岛 bl
百慕大 bm
文莱 bn
玻利维亚 bo
荷兰加勒比区 bq
巴西 br
巴哈马 bs
不丹 bt
布韦岛 bv
博茨瓦纳 bw
白俄罗斯 by
伯利兹 bz
加拿大 ca
科科斯群岛 cc
中非 cf
瑞士 ch
智利 cl
喀麦隆 cm
哥伦比亚 co
哥斯达黎加 cr
古巴 cu
佛得角 cv
圣诞岛 cx
塞浦路斯 cy
捷克 cz
德国 de
吉布提 dj
丹麦 dk
多米尼克 dm
多米尼加 do
阿尔及利亚 dz
厄瓜多尔 ec
爱沙尼亚 ee
埃及 eg
西撒哈拉 eh
厄立特里亚 er
西班牙 es
芬兰 fi
斐济群岛 fj
密克罗尼西亚联邦 fm
法罗群岛 fo
法国 fr
加蓬 ga
格林纳达 gd
格鲁吉亚 ge
法属圭亚那 gf
加纳 gh
直布罗陀 gi
格陵兰 gl
几内亚 gn
瓜德罗普 gp
赤道几内亚 gq
希腊 gr
危地马拉 gt
关岛 gu
几内亚比绍 gw
圭亚那 gy
赫德岛和麦克唐纳群岛 hm
洪都拉斯 hn
克罗地亚 hr
海地 ht
匈牙利 hu
印尼 id
爱尔兰 ie
以色列 il
马恩岛 im
印度 in
英属印度洋领地 io
伊拉克 iq
伊朗 ir
冰岛 is
意大利 it
泽西岛 je
牙买加 jm
约旦 jo
日本 jp
柬埔寨 kh
基里巴斯 ki
科摩罗 km
科威特 kw
开曼群岛 ky
黎巴嫩 lb
列支敦士登 li
斯里兰卡 lk
利比里亚 lr
莱索托 ls
立陶宛 lt
卢森堡 lu
拉脱维亚 lv
利比亚 ly
摩洛哥 ma
摩纳哥 mc
摩尔多瓦 md
黑山 me
法属圣马丁 mf
马达加斯加 mg
马绍尔群岛 mh
马其顿 mk
马里 ml
缅甸 mm
澳门 mo
马提尼克 mq
毛里塔尼亚 mr
蒙塞拉特岛 ms
马耳他 mt
马尔代夫 mv
马拉维 mw
墨西哥 mx
马来西亚 my
纳米比亚 na
尼日尔 ne
诺福克岛 nf
尼日利亚 ng
尼加拉瓜 ni
荷兰 nl
挪威 no
尼泊尔 np
瑙鲁 nr
阿曼 om
巴拿马 pa
秘鲁 pe
法属波利尼西亚 pf
巴布亚新几内亚 pg
菲律宾 ph
巴基斯坦 pk
波兰 pl
皮特凯恩群岛 pn
波多黎各 pr
巴勒斯坦 ps
帕劳 pw
巴拉圭 py
卡塔尔 qa
留尼汪 re
罗马尼亚 ro
塞尔维亚 rs
俄罗斯 ru
卢旺达 rw
所罗门群岛 sb
塞舌尔 sc
苏丹 sd
瑞典 se
新加坡 sg
斯洛文尼亚 si
斯洛伐克 sk
塞拉利昂 sl
圣马力诺 sm
塞内加尔 sn
索马里 so
苏里南 sr
南苏丹 ss
圣多美和普林西比 st
萨尔瓦多 sv
叙利亚 sy
斯威士兰 sz
特克斯和凯科斯群岛 tc
乍得 td
多哥 tg
泰国 th
托克劳 tk
东帝汶 tl
突尼斯 tn
汤加 to
土耳其 tr
图瓦卢 tv
坦桑尼亚 tz
乌克兰 ua
乌干达 ug
乌拉圭 uy
梵蒂冈 va
委内瑞拉 ve
英属维尔京群岛 vg
美属维尔京群岛 vi
越南 vn
瓦利斯和富图纳 wf
萨摩亚 ws
也门 ye
马约特 yt
南非 za
赞比亚 zm
津巴布韦 zw
刚果（布） cg
刚果（金） cd
莫桑比克 mz
根西岛 gg
冈比亚 gm
北马里亚纳群岛 mp
埃塞俄比亚 et
新喀里多尼亚 nc
瓦努阿图 vu
法属南部领地 tf
纽埃 nu
美国本土外小岛屿 um
库克群岛 ck
英国 gb
特立尼达和多巴哥 tt
圣文森特和格林纳丁斯 vc
台湾 tw
新西兰 nz
沙特阿拉伯 sa
老挝 la
朝鲜 北朝鲜 kp
韩国 南朝鲜 kr
葡萄牙 pt
吉尔吉斯斯坦 kg
哈萨克斯坦 kz
塔吉克斯坦 tj
土库曼斯坦 tm
乌兹别克斯坦 uz
圣基茨和尼维斯 kn
圣皮埃尔和密克隆 pm
圣赫勒拿 sh
圣卢西亚 lc
毛里求斯 mu
科特迪瓦 ci
肯尼亚 ke
蒙古国 mn

IP 固定

和上述内容一样，我们可以通过在 username 里面添加 session 并添加一个 5 位固定数字，来实现一段时间内的 IP 固定，有效期大约 10 分钟。

例如如果要实现一段时间内的 IP 固定，原来的 username 是 1f78266a，则可以把 username 修改为 1f78266a-session-12345，其中的 12345 如果不变，那么一段时间内 IP 就不变，上述的 curl 就可以改写如下：

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

购买更多

如您的套餐已经耗尽，您需要购买更多才能继续使用该代理服务。

要购买更多，请到「申请页面」直接点击「购买更多」按钮即可选购，单次购买更多，单价越便宜。

作者 发表于 阅读次数： 本文字数： 6.3k 阅读时长 ≈ 6 分钟

API 开发教程

LibreChat 是一个高度可配置的开源 AI 客户端，在一个界面里复刻 ChatGPT 的完整体验，并加上多服务商支持与企业级配置。它的特点是用一份 librechat.yaml 配置文件描述所有服务商、模型与路由规则，配置可版本化、可代码评审。它原生支持自定义 OpenAI 兼容端点，因此可以接入 Ace Data Cloud，一份 API Token 同时访问 Claude、GPT、Gemini、Grok、DeepSeek、Kimi、GLM 等 60+ 大模型。本文介绍配置流程。

申请流程

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

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

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

部署 LibreChat

LibreChat 通过 Docker Compose 部署，先准备目录并下载官方配置：

1
2
3
4
 
mkdir -p ~/librechat && cd ~/librechat
curl -O https://raw.githubusercontent.com/danny-avila/LibreChat/main/docker-compose.yml
curl -O https://raw.githubusercontent.com/danny-avila/LibreChat/main/.env.example
mv .env.example .env

在 .env 中用 openssl rand -hex 32 生成 JWT_SECRET、JWT_REFRESH_SECRET、CREDS_KEY、CREDS_IV 等安全密钥，并按需设置 ALLOW_REGISTRATION。

配置 Ace Data Cloud

创建 librechat.yaml，把 Ace Data Cloud 作为自定义 OpenAI 兼容端点（完整字段说明见官方 Custom Endpoints 文档，把 {token} 替换为你的 Token）：

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

endpoints:
  custom:
    - name: "Ace Data Cloud"
      apiKey: "{token}"
      baseURL: "https://api.acedata.cloud/v1"
      models:
        default:
          - "gpt-5"
          - "gpt-5-mini"
          - "gpt-4o"
          - "claude-opus-4-8"
          - "claude-sonnet-4-6"
          - "gemini-3.1-pro"
          - "gemini-3-flash-preview"
          - "grok-4"
          - "deepseek-v3"
          - "kimi-k3"
        fetch: false   # false=用固定列表；true=自动 GET /v1/models
      titleConvo: true
      titleModel: "gpt-5-mini"
      modelDisplayLabel: "Ace Data Cloud"

在 docker-compose.yml 的 api 服务下把该文件挂进容器，然后 docker compose up -d 启动：

1
2
3
4
 
volumes:
  - type: bind
    source: ./librechat.yaml
    target: /app/librechat.yaml

注意 baseURL 的路径规则：

baseURL 实际请求 结果
https://api.acedata.cloud/v1 https://api.acedata.cloud/v1/chat/completions 正确
https://api.acedata.cloud/openai https://api.acedata.cloud/openai/chat/completions 也可用
https://api.acedata.cloud/openai/v1 https://api.acedata.cloud/openai/v1/chat/completions 404（/openai 下没有 /v1）
https://api.acedata.cloud https://api.acedata.cloud/chat/completions 404（缺 /v1）

推荐模型

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

家族 模型 ID 备注
GPT gpt-5、gpt-5-mini、gpt-4o OpenAI 旗舰 / 性价比 / 经典多模态
Claude claude-opus-4-8、claude-sonnet-4-6 Anthropic 旗舰 / 均衡
Gemini gemini-3.1-pro、gemini-3-flash-preview Google 多模态 / 快速
Grok grok-4 xAI，原生联网
DeepSeek deepseek-v3 高性价比，中文友好
Kimi kimi-k3 推理、视觉、超长上下文

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

验证对接

如果不确定问题出在 LibreChat 还是网络，可以先用 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 有效但余额不足，到 控制台 充值即可。

进阶：yaml 配置技巧

librechat.yaml 支持多个 endpoint 分组（例如「旗舰组」与「经济组」），可以用 apiKey: "user_provided" 让每个用户填自己的 Key、用量各算各的；titleModel: "gpt-5-mini" 用便宜模型自动生成对话标题；dropParams 可以统一删掉某个上游不支持的参数以避免 400 错误。详见 librechat.yaml 配置详解。

常见问题

启动后看不到 Ace Data Cloud 端点

通常是 yaml 没挂进容器或缩进错误。检查 docker-compose.yml 的 volumes，并校验 yaml 缩进。

提示 404

baseURL 写成了 .../openai/v1 或漏了 /v1。改成 https://api.acedata.cloud/v1。

模型下拉为空

fetch: true 但 /v1/models 失败时，改为 fetch: false 并手动列出 default。

改 yaml 后不生效

需重启容器：docker compose restart api。

了解更多

作者 发表于 阅读次数： 本文字数： 3.1k 阅读时长 ≈ 3 分钟

API 开发教程

Riffusion 允许我们上传参考音频进行二次创作，本文档讲解相关 API 的对接方法。

该 API 只有一个输入参数，就是 audio_url，它是一个可以公开访问的 CDN 地址，支持 mp3 后缀。

这里我们输入的 audio_url 是 https://cdn.acedata.cloud/suno_demo.mp3，是一个可以公开访问的 CDN 地址。

1
2
3
4
5
6
7
 
curl -X POST 'https://api.acedata.cloud/riffusion/upload' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "audio_url": "https://cdn.acedata.cloud/suno_demo.mp3"
}'

结果如下：

1
2
3
4
5
6
7
 
{
  "success": true,
  "task_id": "57e8ce3a-39cb-41a2-802f-e70a324f4d0a",
  "data": {
    "audio_id": "eae26f89-b64b-404d-a80c-761996660b1c"
  }
}

可以看到，data 的 audio_id 字段就是上传后的歌曲 ID。

有了歌曲 ID 之后，我们便可以使用 Riffusion Audios Generation API 来进行自定义歌曲生成了，比如说 action 传入 upload_extend，同时 audio_id 传入返回的歌曲 ID，就可以根据参考音频生成新的歌曲了。

作者 发表于 阅读次数： 本文字数： 705 阅读时长 ≈ 1 分钟

API 开发教程

Producer 允许我们上传参考音频进行二次创作，本文档讲解相关 API 的对接方法。

该 API 只有一个输入参数，就是 audio_url，它是一个可以公开访问的 CDN 地址，支持 mp3 后缀。

这里我们输入的 audio_url 是 https://cdn.acedata.cloud/suno_demo.mp3，是一个可以公开访问的 CDN 地址。

1
2
3
4
5
6
7
 
curl -X POST 'https://api.acedata.cloud/producer/upload' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "audio_url": "https://cdn.acedata.cloud/suno_demo.mp3"
}'

结果如下：

1
2
3
4
5
6
7
8
9
 
{
  "success": true,
  "task_id": "23e7d4ec-d1a8-429f-87d8-9f53fc3b6666",
  "data": {
    "audio_id": "d906da31-87cb-42f5-98df-2fc4969923b1",
    "lyric": "[Mandopop, Acoustic Pop]\n[Soft female vocals, bright and cheerful]\n\n[Verse 1]\n阳光洒在海边\n浪花笑得灿烂\n你和我在沙滩\n钟表停止转\n冰淇淋在融化\n手牵手去散步\n风儿轻轻吹过\n心跳不停跳\n\n[Chorus]\n夏天夏天\n时间停在这一天\n笑声回荡\n蔚蓝天空在身旁",
    "audio_url": "https://storage.googleapis.com/corpusant-app-public/producer/raw/d906da31-87cb-42f5-98df-2fc4969923b1.mp3"
  }
}

可以看到，data 的 audio_id 字段就是上传后的歌曲 ID。

有了歌曲 ID 之后，我们便可以使用 Producer Audios Generation API 来进行自定义歌曲生成了，比如说 action 传入 upload_extend，同时 audio_id 传入返回的歌曲 ID，就可以根据参考音频生成新的歌曲了。

作者 发表于 阅读次数： 本文字数： 1k 阅读时长 ≈ 1 分钟

MCP 教程

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

功能概览

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

  • 文本生成视频 — 通过文本提示词生成高质量视频
  • 图片生成视频 — 以图片为基础生成视频
  • 多模型支持 — 支持 veo3、veo2-fast、veo31-fast-ingredients 等模型
  • 多种分辨率 — 支持 4K、1080p、GIF 等输出格式
  • 多种画面比例 — 支持 16:9、9:16 等比例
  • 1080p 升级 — 将已生成视频升级到 1080p
  • 任务查询 — 监控生成进度并获取结果

前置准备

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

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

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

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

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

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

Claude Code（终端命令行）

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

Cursor

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

1
2
3
4
5
6
7
8
9
10
 
{
  "mcpServers": {
    "veo": {
      "url": "https://veo.mcp.acedata.cloud/mcp",
      "headers": {
        "Authorization": "Bearer 你的API Token"
      }
    }
  }
}

其他支持 MCP 的客户端

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

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

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

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

安装

pip 安装（推荐）：

1
 
pip install mcp-veo

或源码安装：

1
2
3
 
git clone https://github.com/AceDataCloud/VeoMCP.git
cd VeoMCP
pip install -e .

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

在 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": {
    "veo": {
      "command": "mcp-veo",
      "env": {
        "ACEDATACLOUD_API_TOKEN": "你的API Token"
      }
    }
  }
}

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

1
2
3
4
5
6
7
8
9
10
11
 
{
  "mcpServers": {
    "veo": {
      "command": "uvx",
      "args": ["mcp-veo"],
      "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": {
    "veo": {
      "command": "mcp-veo",
      "env": {
        "ACEDATACLOUD_API_TOKEN": "你的API Token"
      }
    }
  }
}

或者使用 uvx：

1
2
3
4
5
6
7
8
9
10
11
 
{
  "servers": {
    "veo": {
      "command": "uvx",
      "args": ["mcp-veo"],
      "env": {
        "ACEDATACLOUD_API_TOKEN": "你的API Token"
      }
    }
  }
}

可用工具列表

工具名 说明
veo_text_to_video 通过文本提示词生成视频
veo_image_to_video 以图片为基础生成视频
veo_get_1080p 将视频升级到 1080p
veo_get_task 查询单个任务状态
veo_get_tasks_batch 批量查询任务状态

使用示例

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

  • 「帮我用 Veo 生成一段星空延时摄影视频」
  • 「用这张风景照生成一段 4K 视频」
  • 「生成一段竖屏 9:16 的短视频」
  • 「把这个视频升级到 1080p」

更多信息

作者 发表于 阅读次数： 本文字数： 3.3k 阅读时长 ≈ 3 分钟

API 开发教程

为 Pending 状态的订单获取支付链接 / 二维码 / 链上扣款指令，并发起实际扣款。

不同支付方式的行为：

payment_method 返回内容 用户操作
AliPay 支付宝二维码 / H5 跳转 URL 扫码或点击链接完成支付
WeChat 微信扫码二维码 用微信扫码
Stripe Stripe Checkout Session URL 跳转 Stripe 完成卡支付
Paypal PayPal Approve URL 跳转 PayPal 完成支付
X402 / Crypto EIP-3009 / Solana 链上转账指令 钱包签名，链上确认即生效

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

接口概览

项 内容
方法 POST
URL https://platform.acedata.cloud/api/v1/orders/{order_id}/pay/
鉴权 ✅ 需要账户令牌
Body application/json（多数支付方式可为空 {}）

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

请求头：

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

获取账户令牌的方式见管理 AceDataCloud 平台账户令牌。

路径参数

参数 类型 必填 说明
order_id UUID ✅ 订单 ID

请求体

不同支付方式所需字段不同：

AliPay / WeChat / Stripe / Paypal

通常无需 Body，直接 POST {}。

X402 / Crypto

字段 类型 必填 说明
signature string ✅ 钱包对授权信息的签名（EIP-712 或 Solana 签名）
from_address string ✅ 付款方钱包地址
chain_id string 否 链 ID（默认平台主链）
token_address string 否 代币合约地址（默认 USDC）

请求示例

cURL — AliPay

1
2
3
4
5
 
curl -X POST 'https://platform.acedata.cloud/api/v1/orders/fa927d12-3b04-4f51-bf2e-ec3a5a7d9b2c/pay/' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer platform-v1-92eb****629c' \
  -H 'content-type: application/json' \
  -d '{}'

Python

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

PLATFORM_TOKEN = "platform-v1-92eb****629c"
order_id = "fa927d12-3b04-4f51-bf2e-ec3a5a7d9b2c"

resp = requests.post(
    f"https://platform.acedata.cloud/api/v1/orders/{order_id}/pay/",
    headers={
        "authorization": f"Bearer {PLATFORM_TOKEN}",
        "content-type": "application/json",
    },
    json={},
    timeout=10,
)
data = resp.json()
print(f"支付链接: {data.get('payment_url') or data.get('qr_code_url')}")

Node.js

1
2
3
4
5
6
7
8
9
10
11
 
const orderId = 'fa927d12-3b04-4f51-bf2e-ec3a5a7d9b2c'
const r = await fetch(`https://platform.acedata.cloud/api/v1/orders/${orderId}/pay/`, {
  method: 'POST',
  headers: {
    authorization: 'Bearer platform-v1-92eb****629c',
    'content-type': 'application/json',
  },
  body: '{}',
})
const data = await r.json()
window.location.href = data.payment_url || data.qr_code_url

响应示例（HTTP 200）

AliPay / WeChat

1
2
3
4
5
6
7
 
{
  "order_id": "fa927d12-3b04-4f51-bf2e-ec3a5a7d9b2c",
  "payment_method": "AliPay",
  "payment_url": "https://qr.alipay.com/bax03455azqgxxxxxxxxx",
  "qr_code_url": "https://qr.alipay.com/bax03455azqgxxxxxxxxx",
  "expires_in": 900
}

Stripe / Paypal

1
2
3
4
5
6
 
{
  "order_id": "fa927d12-3b04-4f51-bf2e-ec3a5a7d9b2c",
  "payment_method": "Stripe",
  "payment_url": "https://checkout.stripe.com/c/pay/cs_test_xxxxx",
  "expires_in": 86400
}

X402 / Crypto

链上支付成功直接结算——返回值表示已确认上链：

1
2
3
4
5
6
 
{
  "order_id": "fa927d12-3b04-4f51-bf2e-ec3a5a7d9b2c",
  "payment_method": "X402",
  "state": "Paid",
  "tx_hash": "0x123abc..."
}

错误处理

HTTP code 含义
400 invalid_state 订单状态不是 Pending（已支付 / 已取消 / 已过期）
400 invalid_signature X402 / Crypto 签名验证失败
400 invalid 其他参数错误
401 not_authenticated 缺少账户令牌
403 permission_denied 订单不属于你
404 not_found 订单不存在

实用提示

  • 支付链接有时效：AliPay/WeChat 一般 15 分钟过期，到期后再次调用本接口会自动重新生成新链接。
  • 支付完成后自动到账：服务端会监听支付回调（异步），通常几秒内 state 变为 Paid 并增加 Application 余额。
  • 不需要手动确认：第三方支付的支付状态完全由服务端 Webhook 接收，客户端只需轮询订单详情或刷新订单状态 来感知。
  • X402 即付即生效：链上支付不是异步流程——本接口返回时 state 已经是 Paid。
  • 重复支付保护：同一订单 state="Paid" 后调用本接口会返回 400 invalid_state，不会重复扣款。

相关接口

作者 发表于 阅读次数： 本文字数： 3.1k 阅读时长 ≈ 3 分钟

API 开发教程

TypeScript 是接入 Ace Data Cloud X402 最推荐的方式之一。官方 SDK 负责普通 API 调用、任务轮询、错误处理和自动重试；@acedatacloud/x402-client 负责在遇到 402 Payment Required 时签出 X-Payment 请求头。

源码与包地址：

安装依赖

1
 
npm install @acedatacloud/sdk @acedatacloud/x402-client

如果使用 Base 或 SKALE，需要 EVM 签名能力：

1
 
npm install ethers

如果使用 Solana，需要 Solana wallet adapter 或 @solana/web3.js：

1
 
npm install @solana/web3.js

干净 npm 项目的安装和导入检查输出：

1
2
3
4
5
 
imports_ok true true true true true
@acedatacloud/sdk@2026.504.2
@acedatacloud/x402-client@2026.531.3
ethers@6.16.0
@solana/web3.js@1.98.4

结果说明：

  • @acedatacloud/sdk 和 @acedatacloud/x402-client 均可从 npm 安装并被 Node.js 导入。
  • ethers 用于 EVM typed data 签名，@solana/web3.js 用于 Solana transaction 构造。

Base 或 SKALE 示例

浏览器中可以直接使用 window.ethereum。Node.js 中可以用 ethers.Wallet 包一层 EIP-1193 风格的 provider。

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
 
import { Wallet } from 'ethers';
import { AceDataCloud } from '@acedatacloud/sdk';
import { createX402PaymentHandler } from '@acedatacloud/x402-client';

const wallet = new Wallet(process.env.EVM_PRIVATE_KEY!);

const evmProvider = {
  async request({ method, params }: { method: string; params?: unknown[] }) {
    if (method !== 'eth_signTypedData_v4') {
      throw new Error(`unsupported method: ${method}`);
    }
    const [, typedDataJson] = params as [string, string];
    const typedData = JSON.parse(typedDataJson);
    return wallet.signTypedData(typedData.domain, typedData.types, typedData.message);
  }
};

const client = new AceDataCloud({
  paymentHandler: createX402PaymentHandler({
    network: 'base',
    evmProvider,
    evmAddress: wallet.address
  })
});

const result = await client.openai.chat.completions.create({
  model: 'gpt-4o-mini',
  messages: [{ role: 'user', content: 'Say hi in 3 words' }],
  max_tokens: 10
});

console.log(result.choices[0].message.content);

SKALE paid call 的程序运行结果：

1
2
3
4
 
payer 0xd0479FA9FD8C678303d477433d24C15e3723CC1C
elapsed_ms 6782
content ADC_TS_SDK_X402_OK
id chatcmpl-DlcVLO4PQWvmjPDQpy9yQw2QdLGAT

结果说明：

  • 程序先触发无认证 402，再由 handler 签出 X-Payment，最后用同一请求体重试。
  • content ADC_TS_SDK_X402_OK 是模型真实返回的固定字符串，说明重试后的请求进入了上游 API。
  • id chatcmpl-DlcVLO4PQWvmjPDQpy9yQw2QdLGAT 是这次 chat completion 响应 ID，可用于和平台使用记录对照。
  • 链上结算结果见 E2E 验证与故障排查 中的 SKALE exact 记录。

把 network 改成 skale 即可使用 SKALE。SKALE 的优势是链上交易 gas 成本低；Base 的优势是 USDC 流动性和钱包支持更成熟。

浏览器钱包示例

在前端应用中使用 MetaMask、Coinbase Wallet 或 WalletConnect 时，通常直接传入 EIP-1193 provider：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
 
import { AceDataCloud } from '@acedatacloud/sdk';
import { createX402PaymentHandler } from '@acedatacloud/x402-client';

const [address] = await window.ethereum.request({ method: 'eth_requestAccounts' });

const client = new AceDataCloud({
  paymentHandler: createX402PaymentHandler({
    network: 'base',
    evmProvider: window.ethereum,
    evmAddress: address
  })
});

const image = await client.images.generate({
  provider: 'nano-banana',
  prompt: 'a yellow banana on a white background'
});

浏览器钱包会弹出签名确认。用户签名的不是任意消息，而是 API 返回的支付要求：收款地址、USDC 合约、金额、有效期和 nonce 都被包含在签名里。

Solana 示例

Solana 使用 SPL USDC TransferChecked。传入的 wallet adapter 需要暴露 publicKey 和 signAndSendTransaction。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
 
import { AceDataCloud } from '@acedatacloud/sdk';
import { createX402PaymentHandler } from '@acedatacloud/x402-client';

const client = new AceDataCloud({
  paymentHandler: createX402PaymentHandler({
    network: 'solana',
    solanaWallet: phantomWallet
  })
});

const result = await client.openai.chat.completions.create({
  model: 'gpt-4o-mini',
  messages: [{ role: 'user', content: 'Say hi in 3 words' }],
  max_tokens: 10
});

Solana 路径目前只支持 exact，不支持 upto。如果 API 返回多个 accepts，handler 会选择 network = 'solana' 的那一项。

Solana 路径在同一公开 API 上已验证 paid retry 能返回 HTTP 200 和 ADC_SOLANA_E2E_OK。公开 RPC 查询可能限流，因此本文不写 Solana tx hash；需要链上对账时，请使用你自己的 Solana RPC 或控制台记录确认。

选择 exact 或 upto

当前 TypeScript handler 会选择服务器返回的第一个匹配网络的 payment requirement。Ace Data Cloud 的 API 通常会把同一网络的 exact 放在 upto 前面，因此如果你明确要走后置计量，需要传入 preferScheme: 'upto'。

示例：

1
2
3
4
5
6
7
8
 
const client = new AceDataCloud({
  paymentHandler: createX402PaymentHandler({
    network: 'base',
    evmProvider,
    evmAddress: wallet.address,
    preferScheme: 'upto'
  })
});

如果服务端没有返回该网络的 upto requirement，handler 会自动回退到该网络可用的第一个 requirement，通常是 exact。

upto 需要一次性授权 Permit2。TypeScript helper 支持 Base 和 SKALE：

1
2
3
4
5
 
# Base
npx tsx scripts/approve-permit2.ts --network base

# SKALE Base
SKALE_BASE_PRIVATE_KEY=0x... npx tsx scripts/approve-permit2.ts --network skale

SKALE upto 已完成公开 API 验证：HTTP 402 -> HTTP 200，后置 settlement tx 为 0x51831a97fb97802951bee5dfb36735f4a0b589f153e6a23976fad5495c3925bc。完整输出见计费方案说明。

SDK 做了什么

@acedatacloud/sdk 的 transport 会在收到 402 时执行一次 payment handler：

1
2
3
4
5
6
 
type PaymentHandler = (ctx: {
  url: string;
  method: string;
  body?: unknown;
  accepts: PaymentRequirement[];
}) => Promise<{ headers: Record<string, string> }>;

@acedatacloud/x402-client 返回的 handler 会：

  1. 从 ctx.accepts 中选择目标网络的 payment requirement。
  2. 按网络构造 EVM EIP-712 签名或 Solana transfer transaction。
  3. 将 envelope 序列化为 Base64。
  4. 返回 { headers: { 'X-Payment': '<base64>' } }。
  5. SDK 自动用原请求体重试。

这意味着业务代码只需要像普通 SDK 调用一样写，不需要手动处理 402 重试。

作者 发表于 阅读次数： 本文字数： 5k 阅读时长 ≈ 5 分钟

技术教程

📘 Overview：OpenCode MCP Overview →

Luma Dream Machine 在“小成本 / 高画质 / 自然过渡”这三点上一直是性价比最高的视频模型之一。在 OpenCode 里接上 Luma MCP Server 后，你可以让它根据文本或参考图生成短视频，也能直接续写已有视频做风格一致的延伸。

Luma MCP 适合做产品 demo 短片、Banner 动效、社交媒体短视频，以及“用图片驱动出动画”和“视频延伸”两类高频场景。

获取 API Token

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

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

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

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

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

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

1
 
opencode mcp debug luma

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

🤖 选模型的实测建议：在 OpenCode 里要真正让模型主动调用 Luma 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
 
生成一段 5 秒视频：海浪轻拍金色沙滩，日落，电影感

图生视频

1
 
把这张产品图变成视频，缓慢从左到右环绕展示

视频延伸

1
 
续写这个视频，再来 10 秒，保持同样的风格

工具列表

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

工具 说明
luma_generate_video 文本生成视频
luma_generate_video_from_image 用参考图生成视频
luma_extend_video 视频延伸

相关链接

作者 发表于 阅读次数： 本文字数： 3.5k 阅读时长 ≈ 3 分钟

API 开发教程

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

申请流程

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

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

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

📘 完整文档：Wan Videos Generation API →

基本使用

首先先了解下基本的使用方式，就是输入提示词 prompt、 生成行为 action、首帧参考图片 image_url 以及模型 model，便可获得处理后的结果，首先需要简单地传递一个 action 字段，它的值为 text2video，它主要包含俩种行为：文生视频（text2video）、图生视频（image2video），然后我们还需要输入模型 model，目前主要有 wan2.6-i2v, wan2.6-r2v, wan2.6-i2v-flash, wan2.6-t2v 模型，具体的内容如下：

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

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

另外设置了 Request Body，包括：

  • model：生成视频的模型，主要有 wan2.6-i2v, wan2.6-r2v, wan2.6-i2v-flash, wan2.6-t2v 模型。
  • action：此次视频生成任务的行为，主要包含三种行为，分别为：文生视频（text2video）、图生视频（image2video），当是文生视频时，目前只支持模型 wan2.6-t2v，当是图生视频时，目前只支持模型 wan2.6-i2v, wan2.6-r2v, wan2.6-i2v-flash。
  • image_url：当选择图生视频行为 image2video 就必须需要上传的首帧参考图片链接，目前只支持模型 wan2.6-i2v、wan2.6-i2v-flash。
  • reference_video_urls：图生视频时可选，指定参考的视频链接进行生成，目前只支持模型 wan2.6-r2v。
  • size：指定生成的视频分辨率，格式为宽*高。该参数的默认值和可用枚举值依赖于 model 参数，具体的规则可参考官网文档：。
  • duration：视频生成的时长，主要支持5、10、15。
  • shot_type：可选，指定生成视频的镜头类型，即视频是由一个连续镜头还是多个切换镜头组成。生效条件：仅当”prompt_extend”: true 时生效。参数优先级：shot_type > prompt。例如，若 shot_type设置为”single”，即使 prompt 中包含“生成多镜头视频”，模型仍会输出单镜头视频，具体的规则可参考官网文档。
  • negative_prompt：可选，反向提示词，用来描述不希望在视频画面中看到的内容，可以对视频画面进行限制。支持中英文，长度不超过500个字符，超过部分会自动截断。示例值：低分辨率、错误、最差质量、低质量、残缺、多余的手指、比例不良等。
  • resolution：指定生成的视频分辨率档位，用于调整视频的清晰度（总像素）。模型根据选择的分辨率档位，自动缩放至相近总像素，视频宽高比将尽量与输入图像 img_url 的宽高比保持一致，更多说明详见参考官网文档。
  • audio_url：音频文件的 URL，模型将使用该音频生成视频。使用方式参考官网文档。
  • audio：是否生成有声视频。参数优先级：audio > audio_url。当 audio=false时，即使传入 audio_url，输出仍为无声视频，且计费按无声视频计算，默认值是true。
  • prompt_extend：是否开启prompt智能改写。开启后使用大模型对输入prompt进行智能改写。对于较短的prompt生成效果提升明显，但会增加耗时，默认值是true。
  • prompt：提示词。
  • callback_url：需要回调结果的URL。
  • async：可选，设为 true 时接口立即返回 task_id，无需提供 callback_url，随后通过对应的任务查询接口轮询获取结果。

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

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

1
2
3
4
5
6
 
{
  "success": true,
  "video_url": "https://dashscope-result-sh.oss-accelerate.aliyuncs.com/1d/db/20260124/da477ba2/0d2042f9-ba8d-496d-8ab5-182617e28f9e.mp4?Expires=1769349278&OSSAccessKeyId=LTAI5tKPD3TMqf2Lna1fASuh&Signature=SjBa4wRcDVx3SSYu/x7BYCFQk0s=",
  "state": "completed",
  "task_id": "a4bca552-d964-46a1-8ff7-fd922f916582"
}

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

  • success，此时视频生成任务的状态情况。
  • task_id，此时视频生成任务ID。
  • video_url，此时视频生成任务的视频链接。
  • state，此时视频生成任务的状态。

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

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

1
2
3
4
5
6
7
8
9
10
 
curl -X POST 'https://api.acedata.cloud/wan/videos' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "action": "text2video",
  "model": "wan2.6-t2v",
  "prompt": "Astronauts shuttle from space to volcano",
  "duration": 5
}'

图生视频功能

如果想对参考图或者参考视频来生成视频的话，可以将参数 action 设置为 image2video ，并且输入需要参考图链接或者参考视频链接，接下来我们要必须填下一步需要扩展的提示词来自定义生成视频，就可以指定如下内容：

  • model：生成视频的模型，主要有 wan2.6-i2v, wan2.6-r2v, wan2.6-i2v-flash, wan2.6-t2v 模型。
  • image_url：当选择图生视频行为 image2video 就必须需要上传的首帧参考图片链接，目前只支持模型 wan2.6-i2v、wan2.6-i2v-flash。
  • reference_video_urls：图生视频时可选，指定参考的视频链接进行生成，目前只支持模型 wan2.6-r2v。
  • prompt：提示词。

填写样例如下：

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

对应的 Python 代码：

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

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

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

payload = {
    "action": "image2video",
    "model": "wan2.6-i2v",
    "prompt": "Astronauts shuttle from space to volcano",
    "duration": 5,
    "image_url": "https://cdn.acedata.cloud/r9vsv9.png",
    "callback_url": "https://www.baidu.com/"
}

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

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

1
2
3
4
5
6
 
{
  "success": true,
  "video_url": "https://dashscope-result-sh.oss-accelerate.aliyuncs.com/1d/db/20260124/da477ba2/0d2042f9-ba8d-496d-8ab5-182617e28f9e.mp4?Expires=1769349278&OSSAccessKeyId=LTAI5tKPD3TMqf2Lna1fASuh&Signature=SjBa4wRcDVx3SSYu/x7BYCFQk0s=",
  "state": "completed",
  "task_id": "a4bca552-d964-46a1-8ff7-fd922f916582"
}

可以看出，结果内容与上文的是一致的，这也就实现视频的扩展视频功能。

异步回调

由于 Wan 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/624b2c78-6dbd-4618-9d2b-b32eade6d8c3。

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

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

1
2
3
 
{
  "task_id": "20068983-0cc9-4c6a-aeb6-9c6a3c668be0"
}

稍等片刻，我们可以在 https://webhook.site/624b2c78-6dbd-4618-9d2b-b32eade6d8c3 上观察到生成视频的结果，如图所示：

内容如下：

1
2
3
4
5
6
 
{
  "success": true,
  "video_url": "https://dashscope-result-sh.oss-accelerate.aliyuncs.com/1d/db/20260124/da477ba2/0d2042f9-ba8d-496d-8ab5-182617e28f9e.mp4?Expires=1769349278&OSSAccessKeyId=LTAI5tKPD3TMqf2Lna1fASuh&Signature=SjBa4wRcDVx3SSYu/x7BYCFQk0s=",
  "state": "completed",
  "task_id": "a4bca552-d964-46a1-8ff7-fd922f916582"
}

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

错误处理

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

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

错误响应示例

1
2
3
4
5
6
7
8
 
{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

结论

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

作者 发表于 阅读次数： 本文字数： 5.7k 阅读时长 ≈ 5 分钟

API 开发教程

通过订单 ID 获取单个订单的完整信息——比列表多出 application、service、package 等关联对象的完整字段，以及当前可用的 payment_url（仅 Pending 订单）。

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

接口概览

项 内容
方法 GET
URL https://platform.acedata.cloud/api/v1/orders/{order_id}
鉴权 ✅ 需要账户令牌

⚠️ URL 不要带尾部斜杠——/orders/{id} 不是 /orders/{id}/。

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

请求头：

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

获取方式见管理 AceDataCloud 平台账户令牌。

路径参数

参数 类型 必填 说明
order_id UUID ✅ 订单 ID

请求示例

cURL

1
2
3
 
curl 'https://platform.acedata.cloud/api/v1/orders/fa927d12-3b04-4f51-bf2e-ec3a5a7d9b2c' \
  -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
 
import requests

order_id = "fa927d12-3b04-4f51-bf2e-ec3a5a7d9b2c"
resp = requests.get(
    f"https://platform.acedata.cloud/api/v1/orders/{order_id}",
    headers={"authorization": "Bearer platform-v1-92eb****629c"},
    timeout=10,
)
order = resp.json()
print(f"订单: {order['service']['title']} - {order['package']['amount']} {order['service']['unit']}")
print(f"状态: {order['state']} - ¥{order['final_price']}")
if order['state'] == "Pending":
    print("⚠️ 订单未支付")

Node.js

1
2
3
4
5
 
const orderId = 'fa927d12-3b04-4f51-bf2e-ec3a5a7d9b2c'
const r = await fetch(`https://platform.acedata.cloud/api/v1/orders/${orderId}`, {
  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
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
 
{
  "id": "fa927d12-3b04-4f51-bf2e-ec3a5a7d9b2c",
  "user_id": "89518d07-5560-4b05-92c1-667f3ddf6a4b",
  "application_id": "82f57141-2323-4453-8730-60f7d833a2da",
  "service_id": "38ecf158-36f2-42f2-8e7f-6786cdfc2452",
  "package_id": "4add61f2-61db-4d1c-85b6-d4876ac122f0",
  "type": "Usage",
  "state": "Paid",
  "price": 63.2,
  "amount": 530.0,
  "currency": "CNY",
  "payment_method": "AliPay",
  "discount_rate": 1.0,
  "discount_amount": 0.0,
  "final_price": 63.2,
  "metadata": null,
  "tags": null,
  "paid_at": "2026-04-26T08:01:23Z",
  "expired_at": null,
  "refunded_at": null,
  "created_at": "2026-04-26T08:00:00Z",
  "updated_at": "2026-04-26T08:01:23Z",
  "service": {
    "id": "38ecf158-36f2-42f2-8e7f-6786cdfc2452",
    "alias": "openai",
    "title": "OpenAI",
    "unit": "Credit"
  },
  "application": {
    "id": "82f57141-2323-4453-8730-60f7d833a2da",
    "remaining_amount": 100.0
  },
  "package": {
    "id": "4add61f2-61db-4d1c-85b6-d4876ac122f0",
    "type": "Usage",
    "price": 63.2,
    "amount": 530.0
  }
}

响应字段说明

字段含义同订单列表，额外展开 application / service / package 关联对象。

错误处理

HTTP code 含义
401 not_authenticated 缺少账户令牌
403 permission_denied 订单不属于你
404 not_found 订单不存在
500 — URL 末尾误加斜杠，去掉后重试

实用提示

  • 要拿支付链接：用支付 AceDataCloud 平台订单 接口而不是本接口——本接口只返回快照，不刷新付款链接。
  • 判断订单生效：用 state="Paid" 和 paid_at 一起判断。paid_at 写入后，Application 的 remaining_amount 一般在几秒内增加。
  • state="Pending" 超过 24 小时：建议轮询刷新订单状态 或直接放弃。

相关接口

作者 发表于 阅读次数： 本文字数： 2.8k 阅读时长 ≈ 3 分钟

API 开发教程

Jan 是一款主打「离线优先 + 隐私保护」的开源 AI 桌面客户端。它自带本地推理引擎（基于 llama.cpp，Apple Silicon 上可用 MLX），可以直接在本机运行开源模型；同时通过 Remote Engine 机制支持任意 OpenAI 兼容端点。借助这一能力可以接入 Ace Data Cloud，让本地模型与云端 Claude、GPT、Gemini、Grok、DeepSeek、Kimi、GLM 等 60+ 大模型共存于同一客户端，一份 API Token 即可使用。本文介绍配置流程。

申请流程

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

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

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

下载 Jan

到 Jan 官网 按平台下载（Windows、macOS、Linux）。Apple Silicon 机型请下载 arm64 包以获得最佳性能。

配置 Ace Data Cloud

Jan 把模型分为 Local Engine（本机运行）与 Remote Engine（第三方 API）两类。Ace Data Cloud 走 OpenAI 兼容协议，按 Remote Engine 接入。

打开 Jan，进入 Settings → Model Providers，找到 OpenAI 卡片并编辑：

字段 值 说明
API Key 你的 Ace Data Cloud Token 控制台复制的 Token
Base URL https://api.acedata.cloud/v1 必须以 /v1 结尾，结尾不要带斜杠

Base URL 必须以 /v1 结尾是 Jan 官方文档的明确约定。如果不想覆盖原 OpenAI 配置，可以「+ Add Provider」新建一个 openai-compatible 类型的供应商，填入相同内容。

Jan 不会自动拉取 Ace Data Cloud 的模型列表，需要在同一编辑页下方点 + Add Model，逐个填写模型 ID。添加后模型会出现在左上角下拉中，并带有「Cloud」图标以区分远程 / 本地。

推荐模型

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

家族 模型 ID 备注
GPT gpt-5、gpt-5-mini、gpt-4o OpenAI 旗舰 / 性价比 / 经典多模态
Claude claude-opus-4-8、claude-sonnet-4-6 Anthropic 旗舰 / 均衡
Gemini gemini-3.1-pro、gemini-3-flash-preview Google 多模态 / 快速
Grok grok-4 xAI，原生联网
DeepSeek deepseek-v3 高性价比，中文友好
Kimi kimi-k3 推理、视觉、超长上下文

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

验证对接

如果不确定问题出在 Jan 还是网络，可以先用 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 有效但余额不足，到 控制台 充值即可。

进阶：本地 + 云端混合

Jan 内置一个可开启的本地 OpenAI 兼容 API Server（Settings → Local API Server），开启后监听 http://localhost:1337/v1/chat/completions，运行你下载的本地模型。这样可以在 LangChain / LlamaIndex 等框架里把 Base URL 指向本地做免费调试，复杂任务再切到 Ace Data Cloud 远程模型。切换模型时对话上下文不会丢失。

常见问题

提示 Connection error 或 404

通常是 Base URL 漏了 /v1。改成 https://api.acedata.cloud/v1（必须以 /v1 结尾，且不要写成 .../openai/v1）。

提示 401 Unauthorized

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

远程模型不出现在下拉中

Jan 不会自动调用 /v1/models，必须手动 + Add Model 添加模型 ID。

能否上传图片让模型分析

可以，但需选择支持视觉的模型，如 gpt-5、gemini-3.1-pro、claude-opus-4-8。

了解更多

作者 发表于 阅读次数： 本文字数： 2.2k 阅读时长 ≈ 2 分钟

API 开发教程

定时任务（/aichat2/scheduled-tasks）让你的 AI Agent 在无人值守的情况下按计划自动运行——每天汇总新闻、每周生成报告、每小时监控数据等任务，全部交给平台在后台自动完成，完成后推送通知让你直接看结果。

功能简介

  • 全能力 agentic 执行：定时任务复用 AI Chat v2 的完整工具链（网页搜索、读取文件、调用 MCP 服务器等），不仅仅是普通问答。
  • 灵活的调度规则：支持每天（daily）、每小时（hourly）、每周（weekly）以及自定义 Cron 表达式。
  • 推送通知：任务完成后通过 Web Push / FCM / APNs 推送到你的浏览器和手机，点击即可跳转到结果对话。
  • 模板变量：在提示词中使用 1784754045000（今日日期）、（第几次运行）、（上次输出摘要）实现动态提示。
  • 透明计费：每次运行按实际使用的模型和 token 数计费，与手动发起的对话价格完全相同。在控制台「用量」页可看到以「Scheduled Task」为来源的独立记录。

申请方式

同 AI Chat v2，在 Ace Data Cloud 控制台 申请 aichat API 权限，获取 API Token 即可同时使用对话和定时任务功能。

通过 Nexior 使用

打开 Nexior，在左侧对话列表顶部点击「定时任务」（时钟图标）进入管理页。

  1. 点击「新建」，填写任务名称、提示词、模型和执行频率。
  2. 保存后任务立即生效，下一次调度时间按你设定的频率自动计算。
  3. 点击任一任务卡片可查看历次运行记录（时间、状态、结果链接）。
  4. 随时通过开关暂停 / 恢复，或点击删除按钮永久移除。

通过 API 使用

所有操作统一走 POST /aichat2/scheduled-tasks，用 action 字段区分。

创建定时任务

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
 
curl https://api.acedata.cloud/aichat2/scheduled-tasks \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "create",
    "name": "每日资讯汇总",
    "schedule": {
      "type": "cron",
      "cron": "0 9 * * *",
      "tz": "Asia/Shanghai"
    },
    "template": {
      "model": "gpt-4o-mini",
      "question": "今天是 {{date}}。请搜索并汇总今日 AI 领域最重要的 3 条新闻，用中文概括每条的核心内容（100 字以内）。",
      "max_turns": 5
    }
  }'

响应示例：

1
2
3
4
5
6
7
8
 
{
  "id": "c3a4b5d6-...",
  "name": "每日资讯汇总",
  "state": "enabled",
  "schedule": { "type": "cron", "cron": "0 9 * * *", "tz": "Asia/Shanghai" },
  "run_count": 0,
  "created_at": 1750000000
}

调度类型说明

schedule.type 必填字段 说明
cron cron（标准 5 段 Cron 表达式）, tz 最灵活，如 0 9 * * 1-5（工作日每天 9:00）
interval interval_seconds, tz 固定间隔，如 3600（每小时）
once at（Unix 时间戳）, tz 仅运行一次

所有调度时间自动加 ±60 秒抖动，防止大量任务同时触发。

列出所有任务

1
2
3
4
 
curl -X POST https://api.acedata.cloud/aichat2/scheduled-tasks \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"action": "retrieve_batch"}'

更新任务

1
2
3
4
5
6
7
8
 
curl -X POST https://api.acedata.cloud/aichat2/scheduled-tasks \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "update",
    "id": "{task_id}",
    "state": "disabled"
  }'

查看运行历史

1
2
3
4
 
curl -X POST https://api.acedata.cloud/aichat2/scheduled-tasks \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"action": "retrieve_runs", "id": "{task_id}"}'

响应示例（单次运行）：

1
2
3
4
5
6
 
{
  "id": "exec-uuid",
  "status": "success",
  "scheduled_at": 1750032000,
  "conversation_id": "conv-uuid"
}

通过 conversation_id 可到 AI Chat v2 接口拿到完整的对话内容，也可直接在 Nexior 查看。

删除任务

1
2
3
4
 
curl -X POST https://api.acedata.cloud/aichat2/scheduled-tasks \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"action": "delete", "id": "{task_id}"}'

模板变量

变量 替换值
1784754045000 当天日期（本地化格式，如 2026/6/22）
ISO 日期（如 2026-06-22）
当前是第几次运行（从 1 开始）
任务名称
上次运行结果的前 500 字摘要（首次运行时为空）

注意事项

  • 无人值守模式：定时任务运行时如果 AI 需要调用 ask_user_question（请求你确认）或需要第三方授权（request_user_consent），该工具会被自动禁用，任务可能跳过相关步骤。如果你的用例需要这类交互，建议先手动发起一次对话完成授权，再创建定时任务。
  • 余额：每次运行前会检查账户余额。余额不足时该次运行会标记为失败，并通过推送通知提醒你充值。连续 5 次失败后任务自动暂停。
  • ends_at 默认值：未设置结束时间时，任务默认在创建后 3 个月自动停止，防止遗忘的僵尸任务持续扣费。可在创建时通过 ends_at（Unix 时间戳）延长。
  • 最大运行时长：单次运行最长 15 分钟。

计费

定时任务与普通 AI Chat v2 使用完全相同的价格体系，按模型和 token 数计费。在控制台用量页，定时任务产生的记录会以「AceChat Scheduled Run」独立展示，便于区分手动对话和自动运行的消耗。

作者 发表于 阅读次数： 本文字数： 3k 阅读时长 ≈ 3 分钟