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

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

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

仓库与包

• SDK 源码（monorepo）：https://github.com/AceDataCloud/SDK
• TypeScript：@acedatacloud/sdk
• Python：acedatacloud
• Go：github.com/AceDataCloud/SDK/go
• X402 客户端（TypeScript）：@acedatacloud/x402-client
• X402 客户端（Python）：acedatacloud-x402

三语言能力矩阵

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

何时用 SDK / MCP / 原生 HTTP / 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 控制台 - 使用历史 即可查看所有使用历史和扣费详情。

了解更多

• 📦 SDK monorepo 源码
• 🔌 X402 集成指南
• 🛠 MCP Servers 教程
• 📊 服务列表与定价

摘要 / 概览

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

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

相关入口：

• 开发者平台：https://platform.acedata.cloud
• 在线体验：https://studio.acedata.cloud
• Nexior 开源部署：https://github.com/AceDataCloud/Nexior

随着 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 系统的基础设施。

📘 完整指南：在 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 Dream Machine MCP Server (GitHub)
• Luma Dream Machine MCP on PyPI
• AceData Cloud 平台
• MCP 协议官网

本文将介绍人脸静态活体检测（高精度版）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。如有任何问题，请随时联系我们的技术支持团队。

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

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

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

什么是 MCP？

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

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

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

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

在 Claude.ai 网页版添加 Seedream MCP

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

1. 打开 Connectors 设置

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

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

2. 添加 Seedream MCP Server

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

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

3. OAuth 授权

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

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

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

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

实测：一句英文 Prompt 出图

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

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

Claude 收到后做的事情：

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

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

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

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

更多玩法（同样一个 Connector）

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

先查可用尺寸再出图

1

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

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

改图 / 局部修改

1

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

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

中文 prompt 直出

1

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

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

批量生成多张候选

1

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

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

常见问题

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

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

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

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

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

相关链接

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

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

功能概览

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

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

前置准备

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

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

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

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

1

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

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

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

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

Claude Desktop

编辑配置文件：

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

1
2
3
4
5
6
7
8
9
10
11

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

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

Claude Code（终端命令行）

1
2

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

VS Code（GitHub Copilot）

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

1
2
3
4
5
6
7
8
9
10
11

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

Cursor

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

1
2
3
4
5
6
7
8
9
10

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

其他支持 MCP 的客户端

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

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

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

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

安装

pip 安装（推荐）：

1

pip install mcp-nanobanana-pro

或源码安装：

1
2
3

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

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

在 Claude Desktop 中使用（本地）

编辑 Claude Desktop 配置文件：

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

添加以下配置：

1
2
3
4
5
6
7
8
9
10

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

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

1
2
3
4
5
6
7
8
9
10
11

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

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

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

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

1
2
3
4
5
6
7
8
9
10

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

或者使用 uvx：

1
2
3
4
5
6
7
8
9
10
11

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

可用工具列表

使用示例

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

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

更多信息

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

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

申请流程

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

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

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

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

基本使用

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

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

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

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

另外设置了 Request Body，包括：

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

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

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

1
2
3

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

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

</p >

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

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

1
2
3
4
5
6
7
8
9
10
11

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

Python 的对接代码如下：

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

import requests

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

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

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

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

错误处理

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

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

错误响应示例

1
2
3
4
5
6
7
8

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

结论

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

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

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

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

申请流程

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

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

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

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

基本使用

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

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

Request Headers 包括：

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

Request Body 主要包括：

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

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

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

1
2
3
4
5
6
7
8
9
10

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

对应的 Python 代码如下：

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

import requests

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

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

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

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

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

1
2
3
4
5

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

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

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

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

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

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

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

填写样例的 CURL 代码如下：

1
2
3
4
5
6
7
8
9
10
11

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

常见的搭配方式：

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

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

多语言输出

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

1
2
3
4
5
6
7
8
9
10

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

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

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

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

1
2
3
4
5
6
7
8
9

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

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

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

取结果

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

1
2
3
4
5
6
7

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

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

计费

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

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

1

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

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

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

错误处理

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

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

错误响应示例

1
2
3
4
5
6
7
8

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

结论

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

相关接口

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

📘 Overview：OpenCode MCP Overview →

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

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

获取 API Token

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

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

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

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

配置 OpenCode

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

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

1

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

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

全局：所有项目共用

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

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

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

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

项目级：仅当前项目生效

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

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

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

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

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

真实运行结果

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

1
2
3
4
5
6
7
8
9
10
11

$ opencode --version
1.15.13

$ opencode mcp list

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

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

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

1

opencode mcp debug flux

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

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

典型场景

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

快速出图

1

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

Kontext 编辑现有图

1

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

生成产品 hero 图

1

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

工具列表

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

相关链接

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

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

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

源码与文档：

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

安装

1

go get github.com/AceDataCloud/SDK/go

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

1
2

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

结果说明：

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

准备 API Token

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

1

export ACEDATACLOUD_API_TOKEN={token}

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

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

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

package main

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

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

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

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

程序运行结果：

1
2
3
4
5

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

结果说明：

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

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

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

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

package main

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

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

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

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

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

程序运行结果：

1
2
3
4

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

结果说明：

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

示例 3：类型化错误处理

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

package main

import (
    "context"
    "errors"
    "fmt"

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

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

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

配置选项（functional options）

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

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

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

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

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

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

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

进阶：复用 Client

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

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

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

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

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

局限和路线图

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

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

仍处于 alpha：

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

如何查看剩余额度

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

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

了解更多

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

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

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

推荐接入路径

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

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

公开源码与包地址：

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

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

支持状态

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

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

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

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

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

TypeScript SDK
content ADC_TS_SDK_X402_OK

Python SDK
content ADC_PY_SDK_X402_OK

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

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

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

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

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

说明：

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

接入注意事项

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

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

可以公开核验的范围

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

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

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

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

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

申请流程

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

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

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

📘 完整文档：Grok Chat Completion API →

基本使用

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

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

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

常用可选参数：

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

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

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

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

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

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

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

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

流式响应

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

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

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

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

Python 样例调用代码：

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

import requests

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

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

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

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

输出效果如下：

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

data: [DONE]

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

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

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

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

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

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

Java 样例代码：

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

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

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

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

多轮对话

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

Python 样例调用代码：

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

import requests

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

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

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

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

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

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

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

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

错误处理

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

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

错误响应示例

1
2
3
4
5
6
7
8

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

结论

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

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

申请流程

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

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

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

📘 完整文档：Flux Images Generation API →

基本使用

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

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

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

另外设置了 Request Body，包括：

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

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

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

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

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

1
2
3
4
5
6
7
8
9
10

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

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

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

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

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

1
2
3
4
5
6
7
8
9
10

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

编辑图片任务

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

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

填写样例如下：

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

对应的代码：

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

import requests

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

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

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

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

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

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

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

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

异步回调

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

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

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

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

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

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

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

1
2
3

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

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

内容如下：

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

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

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

错误处理

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

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

错误响应示例

1
2
3
4
5
6
7
8

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

结论

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

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

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

名词 & 端点速查

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

1

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

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

权限范围（Scope）

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

身份类（OIDC 兼容）

平台资源类

聚合类（自动展开）

特殊

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

第 1 步：注册一个 OAuth 应用

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

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

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

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

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

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

1
2
3
4
5
6
7
8

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

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

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

1

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

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

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

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

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

机密客户端（带 client_secret）：

1
2
3
4
5
6

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

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

1
2
3
4
5
6

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

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

1
2
3
4
5
6
7

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

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

第 4 步：用 Access Token 调用接口

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

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

1
2

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

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

1
2