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

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

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

源码与文档：

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

安装

1

go get github.com/AceDataCloud/SDK/go

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

1
2

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

结果说明：

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

准备 API Token

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

1

export ACEDATACLOUD_API_TOKEN={token}

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

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

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

package main

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

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

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

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

程序运行结果：

1
2
3
4
5

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

结果说明：

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

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

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

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

package main

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

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

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

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

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

程序运行结果：

1
2
3
4

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

结果说明：

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

示例 3：类型化错误处理

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

package main

import (
    "context"
    "errors"
    "fmt"

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

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

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

配置选项（functional options）

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

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

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

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

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

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

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

进阶：复用 Client

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

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

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

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

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

局限和路线图

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

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

仍处于 alpha：

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

如何查看剩余额度

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

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

了解更多

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

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

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

推荐接入路径

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

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

公开源码与包地址：

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

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

支持状态

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

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

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

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

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

TypeScript SDK
content ADC_TS_SDK_X402_OK

Python SDK
content ADC_PY_SDK_X402_OK

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

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

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

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

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

说明：

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

接入注意事项

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

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

可以公开核验的范围

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

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

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

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

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

申请流程

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

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

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

📘 完整文档：Grok Chat Completion API →

基本使用

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

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

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

常用可选参数：

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

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

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

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

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

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

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

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

流式响应

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

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

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

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

Python 样例调用代码：

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

import requests

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

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

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

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

输出效果如下：

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

data: [DONE]

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

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

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

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

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

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

Java 样例代码：

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

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

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

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

多轮对话

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

Python 样例调用代码：

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

import requests

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

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

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

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

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

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

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

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

错误处理

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

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

错误响应示例

1
2
3
4
5
6
7
8

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

结论

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

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

申请流程

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

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

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

📘 完整文档：Flux Images Generation API →

基本使用

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

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

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

另外设置了 Request Body，包括：

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

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

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

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

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

1
2
3
4
5
6
7
8
9
10

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

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

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

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

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

1
2
3
4
5
6
7
8
9
10

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

编辑图片任务

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

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

填写样例如下：

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

对应的代码：

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

import requests

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

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

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

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

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

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

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

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

异步回调

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

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

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

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

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

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

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

1
2
3

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

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

内容如下：

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

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

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

错误处理

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

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

错误响应示例

1
2
3
4
5
6
7
8

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

结论

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

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

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

名词 & 端点速查

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

1

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

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

权限范围（Scope）

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

身份类（OIDC 兼容）

平台资源类

聚合类（自动展开）

特殊

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

第 1 步：注册一个 OAuth 应用

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

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

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

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

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

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

1
2
3
4
5
6
7
8

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

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

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

1

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

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

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

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

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

机密客户端（带 client_secret）：

1
2
3
4
5
6

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

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

1
2
3
4
5
6

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

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

1
2
3
4
5
6
7

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

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

第 4 步：用 Access Token 调用接口

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

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

1
2

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

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

1
2

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

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

刷新令牌

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

1
2
3

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

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

撤销令牌

1
2

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

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

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

常见错误

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

限制速查

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

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

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

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

import requests

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

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

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

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

结果如下：

1
2
3
4
5
6
7
8

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

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

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

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

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

第 2 步：获取并填写 API Key

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

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

第 3 步：验证已连通

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

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

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

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

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

第 3 步：验证已连通

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

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

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

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

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

第 3 步：验证已连通

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

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

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

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

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

实战示例

文字生成视频

1

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

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

图片生成视频

1

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

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

带音频生成视频

1

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

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

工具列表

其他编辑器配置

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

相关链接

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

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

申请方法

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

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

使用方法

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

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

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

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

命令测试

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

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

1

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

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

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

运行结果如下：

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

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

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

代码对接

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

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

import requests

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

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

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

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

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

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

运行结果如下：

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

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

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

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

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

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

import requests
import base64

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

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

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

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

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

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

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

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

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

地区列表：

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

购买更多

如您的套餐已经耗尽，您需要购买更多才能继续使用该代理服务。

要购买更多，请到「申请页面」直接点击「购买更多」按钮即可选购，单次购买更多，单价越便宜。

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 的路径规则：

推荐模型

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

完整模型清单请以 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。

了解更多

• LibreChat 官网 ｜ LibreChat GitHub ｜ librechat.yaml 配置详解
• LibreChat 自定义端点（Custom Endpoints）官方文档
• Ace Data Cloud OpenAI Chat Completions API 文档
• Ace Data Cloud 服务列表
• Ace Data Cloud 控制台

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，就可以根据参考音频生成新的歌曲了。

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，就可以根据参考音频生成新的歌曲了。

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"
      }
    }
  }
}

可用工具列表

使用示例

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

• 「帮我用 Veo 生成一段星空延时摄影视频」
• 「用这张风景照生成一段 4K 视频」
• 「生成一段竖屏 9:16 的短视频」
• 「把这个视频升级到 1080p」

更多信息

• GitHub 仓库：AceDataCloud/VeoMCP
• PyPI 包：mcp-veo
• API 文档：Veo 视频生成 API

为 Pending 状态的订单获取支付链接 / 二维码 / 链上扣款指令，并发起实际扣款。

不同支付方式的行为：

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

接口概览

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

请求头：

1

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

获取账户令牌的方式见管理 AceDataCloud 平台账户令牌。

路径参数

请求体

不同支付方式所需字段不同：

AliPay / WeChat / Stripe / Paypal

通常无需 Body，直接 POST {}。

X402 / Crypto

请求示例

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