静觅丨崔庆才的个人站点

API 开发教程 Subsite（白标子站）使用教程

Subsite 让你在 不另外部署一份前端代码 的前提下，基于 Nexior / Studio 主站建出一个有自己品牌、域名和功能子集的独立站点。每个 Subsite 共享主站的服务容量（模型池、积分账本、对话历史），但拥有独立的：

子域名（例如 mybrand.studio.acedata.cloud）
Logo / Favicon / 站点标题
功能开关（隐藏 Connector、关闭注册、强制 BYOK 等）
默认欢迎语 / 引导提示

谁会用到：希望以 SaaS 形式售卖 AI 助手的代理 / 经销商；想给客户一个「专属入口」的乙方公司；做行业解决方案的 ISV。

工作原理

                  ┌────────────────────────┐
mybrand.studio. ─►│ Nexior / Studio 主站   │
acedata.cloud    │ + 你的 Subsite 配置     │──► 共用平台服务
                  └────────────────────────┘

不是另一份独立部署，而是主站根据请求 Host 动态加载 Subsite 配置。这意味着主站升级 = Subsite 自动升级，无需打包构建。

5 分钟实操

第 1 步：进入 Subsite 管理

登录 studio.acedata.cloud → 右上角头像 → Settings → My Subsite。

如果没看到这个入口，说明你所在站点还没开通 Subsite 功能（多租户场景需站点管理员预先在后台开启）。

第 2 步：创建一个 Subsite

点 Create Subsite：

字段	示例	说明
Subdomain Prefix	`acmecorp`	3-32 位小写字母 / 数字 / 短横线，不能首尾或连续短横线
Subsite Title	`AcmeCorp AI Console`	显示在浏览器标签和 Logo 旁边

提交后平台立即创建 DNS 记录 + TLS 证书，约 30 秒后 acmecorp.studio.acedata.cloud 即可访问。

第 3 步：上传品牌资产

进入 Subsite 详情：

Logo：建议 PNG 透明底，72×72 起；同步显示在登录页和导航栏；
Favicon：自动从 Logo 生成，也可单独覆盖；
Description：SEO meta description 文案。

第 4 步：调整功能开关

开关	默认	推荐值（B2B 转售）
显示 Connector 入口	开	关（避免用户被外部工具分心）
显示「联系客服」气泡	开	关（换成你自己的支持邮箱）
强制 BYOK	关	关（继续吃平台积分），开（要求每个用户绑自己的 Key）
允许新用户自助注册	开	关（仅邀请制时）

第 5 步：把入口给客户

直接把 https://acmecorp.studio.acedata.cloud 发给客户。或者用 CNAME 把 ai.acmecorp.com 指过来 —— 详见自定义域名章节。

自定义域名

如果你不希望子域名带 studio.acedata.cloud，可以在 Subsite 详情 → Domains → Add Custom Domain：

填入 ai.acmecorp.com；
平台返回一条 CNAME（指向 proxy.acedata.cloud）；
你在自己的 DNS 服务商处加这条 CNAME；
等 DNS 生效（≤ 5 分钟），Subsite 自动签发 TLS 证书。

支持多域名同时绑定，例如同时保留 acmecorp.studio.acedata.cloud 和 ai.acmecorp.com。

常见问题

Q：Subsite 用户的对话历史和我自己的混在一起吗？
A：不会。每个 Subsite 有独立的用户体系；登录态、积分账本、对话历史均按 (subsite_id, user_id) 隔离。

Q：Subsite 用谁的积分？
A：默认用 Subsite 站长的积分（站长充值，子站用户消费）。也可以切换为「子站用户自付」模式 —— 子站用户必须自己充值或绑定 BYOK 才能用。

Q：Subsite 能换语言 / 改文案吗？
A：UI 文案跟随主站 i18n 自动翻译；如要改特定文案（例如把「Studio」换成「AcmeCorp Console」），用 Settings → Branding → Custom Strings 覆盖即可。

Q：能买断 / 私有部署吗？
A：能。如需自己跑 Nexior 实例，请参考 Nexior 部署系列教程；Subsite 多租户调度逻辑（app/utils/subsite.py）也已开源。

API 开发教程 Google SERP API 对接说明

Google SERP（Search Engine Results Page）是用户在 Google 搜索引擎中输入查询后看到的结果页面。它显示自然搜索结果、广告、特色摘要、知识图谱以及图片、视频等多种内容，旨在为用户提供最相关的信息。

本文将详细介绍 Google SERP API，它可以提供在 Google 搜索引擎中输入查询获取结果，结果的内容也是包含了许多类型，比如特色摘要、知识图谱以及图片等多种结果。

本文档会介绍下 Google SERP API 的对接说明。

申请流程

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

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

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

📘 完整文档：Google SERP API →

基本使用

首先先了解下基本的使用方式，就是输入搜索资源类型和关键词，就能获得搜索结果，只需要简单地传递 query 字段，并指定相应模型即可。

比如说查找：关于“apple inc”的信息，我们接下来就可以在界面上填写对应的内容，如图所示：

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

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

另外设置了 Request Body，包括：

type：搜索资源的类型，目前只支持六种类型，默认是 search。
query：搜索的关键词。
country：自定义搜索结果的所在国家，默认是美国（US）。
language：自定义搜索结果的语言，默认是英语（en）。
range：自定义搜索结果的时间范围，默认是没有限制的。
number：自定义搜索结果的分页页面大小，默认是 10。
page：自定义搜索结果的分页页数，默认是 1。

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

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

{
  "knowledge_graph": {
    "title": "Apple",
    "type": "Technology company",
    "website": "http://www.apple.com/",
    "image_url": "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcT5ITHsQzdzkkFWKinRe1Y4FUbC_Vy3R_M&s=0",
    "description": "Apple Inc. is an American multinational corporation and technology company headquartered in Cupertino, California, in Silicon Valley. It is best known for its consumer electronics, software, and services.",
    "description_source": "Wikipedia",
    "description_link": "https://en.wikipedia.org/wiki/Apple_Inc.",
    "attributes": {
      "Customer service": "1 (800) 275-2273",
      "Founders": "Steve Jobs, Steve Wozniak, and Ronald Wayne",
      "Founded": "April 1, 1976, Los Altos, CA",
      "Headquarters": "Cupertino, CA",
      "CEO": "Tim Cook (Aug 24, 2011–)"
    }
  },
  "organic": [
    {
      "title": "Apple",
      "link": "https://www.apple.com/",
      "snippet": "Discover the innovative world of Apple and shop everything iPhone, iPad, Apple Watch, Mac, and Apple TV, plus explore accessories, entertainment, ...",
      "sitelinks": [
        {
          "title": "Support",
          "link": "https://support.apple.com/"
        },
        {
          "title": "Career Opportunities",
          "link": "https://www.apple.com/careers/us/"
        },
        {
          "title": "Business",
          "link": "https://www.apple.com/business/"
        },
        {
          "title": "Store",
          "link": "https://www.apple.com/store"
        },
        {
          "title": "Investor Relations",
          "link": "https://investor.apple.com/investor-relations/default.aspx"
        }
      ],
      "position": 1
    },
    {
      "title": "Apple Inc. - Wikipedia",
      "link": "https://en.wikipedia.org/wiki/Apple_Inc.",
      "snippet": "Apple Inc. is an American multinational corporation and technology company headquartered in Cupertino, California, in Silicon Valley.",
      "position": 2
    },
    {
      "title": "Apple Inc. | History, Products, Headquarters, & Facts - Britannica",
      "link": "https://www.britannica.com/money/Apple-Inc",
      "snippet": "American manufacturer of personal computers, smartphones, and tablet computers. Apple was the first successful personal computer company and ...",
      "date": "7 days ago",
      "position": 3
    },
    {
      "title": "Apple Inc. (AAPL) Company Profile & Facts - Yahoo Finance",
      "link": "https://finance.yahoo.com/quote/AAPL/profile/",
      "snippet": "Apple Inc. designs, manufactures, and markets smartphones, personal computers, tablets, wearables, and accessories worldwide. The company offers iPhone, a line ...",
      "position": 4
    },
    {
      "title": "AAPL: Apple Inc Stock Price Quote - NASDAQ GS - Bloomberg",
      "link": "https://www.bloomberg.com/quote/AAPL:US",
      "snippet": "Apple Inc. designs, manufactures, and markets smartphones, personal computers, tablets, wearables and accessories, and sells a variety of related accessories.",
      "position": 5
    },
    {
      "title": "Apple Inc. (AAPL) Stock Price Today - WSJ",
      "link": "https://www.wsj.com/market-data/quotes/AAPL?gaa_at=eafs&gaa_n=ASWzDAiLDLUKmLSxoaZi5n84id-eGDp9gI99K5VU1R7pK3SzSi_PbdpD61P1&gaa_ts=685148c8&gaa_sig=mGk3lG_2W7ZqrXfXSXv7GAP78KUi_uJEadAXuv2bgYJ8Ah42GhIZxrsN4ynbNg_oKD_7NZS1lRPSglUNacIheQ%3D%3D",
      "snippet": "Apple Inc. engages in the design, manufacture, and sale of smartphones, personal computers, tablets, wearables and accessories, and other varieties of related ...",
      "position": 6
    }
  ],
  "people_also_ask": [
    {
      "question": "What is the Apple Inc?",
      "snippet": "Apple Inc., originally Apple Computer, Inc., is a multinational corporation that creates and markets consumer electronics and attendant computer software, and is a digital distributor of media content. Apple's core product lines are the iPhone smartphone, iPad tablet computer, and the Mac personal computer.",
      "title": "History of Apple Inc. - Wikipedia",
      "link": "https://en.wikipedia.org/wiki/History_of_Apple_Inc."
    },
    {
      "question": "Who owns Apple Inc?",
      "snippet": "Apple (AAPL) Ownership Overview The ownership structure of Apple (AAPL) stock is a mix of institutional, retail, and individual investors. Approximately 50.57% of the company's stock is owned by Institutional Investors, 0.06% is owned by Insiders, and 49.38% is owned by Public Companies and Individual Investors.",
      "title": "Who owns Apple? AAPL Stock Ownership - TipRanks.com",
      "link": "https://www.tipranks.com/stocks/aapl/ownership"
    },
    {
      "question": "What is Apple Inc. best known for?",
      "snippet": "It is best known for its consumer electronics, software, and services. Founded in 1976 as Apple Computer Company by Steve Jobs, Steve Wozniak and Ronald Wayne, the company was incorporated by Jobs and Wozniak as Apple Computer, Inc. the following year.",
      "title": "Apple Inc. - Wikipedia",
      "link": "https://en.wikipedia.org/wiki/Apple_Inc."
    },
    {
      "question": "What is the meaning of Inc in Apple Inc?",
      "snippet": "abbreviation for incorporated: used in the names of US companies that are legally established: Bishop Computer Services, Inc.",
      "title": "Inc. | English meaning - Cambridge Dictionary",
      "link": "https://dictionary.cambridge.org/dictionary/english/inc"
    }
  ],
  "related_searches": [
    {
      "query": "Apple iPhone 13"
    },
    {
      "query": "apple inc คืออะไร"
    },
    {
      "query": "Apple Inc full form"
    },
    {
      "query": "Apple Inc address"
    },
    {
      "query": "Apple Inc industry"
    },
    {
      "query": "Apple Inc investor relations"
    },
    {
      "query": "Apple Inc Annual Report"
    },
    {
      "query": "Apple Store"
    }
  ]
}

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

knowledge_graph，搜索结果的知识图谱。
organic，搜索结果的详细信息。
people_also_ask，跟搜索关键词相关的问题。
related_searches，对于搜素关键词的相关搜索。

可以看到，这里返回的结果中有一个 organic 字段，它主要包含了搜索关键词的结果。

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

curl -X POST 'https://api.acedata.cloud/serp/google' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "query": "apple inc"
}'

Python 的对接代码如下：

import requests

url = "https://api.acedata.cloud/serp/google"

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

payload = {
    "query": "apple inc"
}

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

自定义搜索类型

如果您自定义搜索资源的类型，我们可以修改参数 type，它分别包含了普通资源 search、图片资源 images、新闻资源 news、地图资源 maps、地区资源 places、视频资源 videos，本文将以视频资源 videos 做一个示范。

下面我们来演示下具体的操作。

首先，将 type 参数设置为 videos，并正常传递 query 参数，如图所示：

对应代码如下：

curl -X POST 'https://api.acedata.cloud/serp/google' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "type": "videos",
  "query": "apple inc"
}'

可以得到如下回答：

{
  "videos": [
    {
      "title": "Healthcare",
      "link": "https://www.apple.com/healthcare/",
      "snippet": "More ways to shop: Find an Apple Store or other retailer near you. Or call 1-800-MY-APPLE (1-800-692-7753). United States. Copyright © 2025 Apple Inc. All ...",
      "image_url": "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcRQzUYLXB37srVLPW8JbVzhIlP9-SxMe3A8M98Eb7362as4&s",
      "source": "Apple",
      "date": "Apr 16, 2025",
      "position": 1
    },
    {
      "title": "Apple",
      "link": "https://www.youtube.com/apple",
      "snippet": "Our first ever spatial computer. · A Gift for Mom | Shot on iPhone in Spatial Video | Experienced on Apple Vision Pro · Metallica — Official Trailer | Apple ...",
      "position": 2
    },
    {
      "title": "Is Apple FINALLY taking risks again?",
      "link": "https://www.youtube.com/watch?v=JNZV9i5BwH0",
      "snippet": "Taking into account how Microsoft did , and continue to struggle I will said moving the Mac to ARM was a \"killed the company if we fail\" kind of ...",
      "image_url": "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcR0zvbxg3ozbeHNUJojmyRBhi3J-TviJQRinIS4DZiF-EM8&s",
      "video_url": "https://encrypted-vtbn0.gstatic.com/video?q=tbn:ANd9GcTfNZRuifDZb4zgj0d6wDxoHLI8yUr-8SIPNw",
      "duration": "13:04",
      "source": "YouTube",
      "channel": "Luke Miani",
      "date": "2 days ago",
      "position": 3
    },
    {
      "title": "What Apple Didn't Talk About At WWDC 25 & Why It Matters!",
      "link": "https://www.youtube.com/watch?v=2LTc3mzNh08",
      "snippet": "I'm slowly unfollowing YouTubers that create rage bait videos to follow the hate trend. Apple is far from perfect but these subjects have ...",
      "image_url": "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcTgGUJwgxdH-WHBmGOk6XgvijwnYX2H_D2Cl23aNab8CKyT&s",
      "video_url": "https://encrypted-vtbn0.gstatic.com/video?q=tbn:ANd9GcRTtYLkgIrCxERepA5KmCJDbZ7lTUa0OBHqzw",
      "duration": "13:05",
      "source": "YouTube",
      "channel": "Brian Tong",
      "date": "7 hours ago",
      "position": 4
    },
    {
      "title": "Apple",
      "link": "https://www.youtube.com/user/Apple",
      "snippet": "Our first ever spatial computer. · A Gift for Mom | Shot on iPhone in Spatial Video | Experienced on Apple Vision Pro · Metallica — Official Trailer | Apple ...",
      "position": 5
    },
    {
      "title": "Apple Watch Ultra 2",
      "link": "https://www.apple.com/apple-watch-ultra-2/",
      "snippet": "Designed in partnership with Huish Outdoors, the Oceanic+ app turns Ultra 2 into a fully capable dive computer running a Bühlmann decompression algorithm.",
      "image_url": "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcSvZ58COtZS4zIIJDd1-Tl0GIKbFqoffFlhLa20OtLcILDR&s",
      "source": "Apple",
      "date": "Sep 12, 2023",
      "position": 6
    },
    {
      "title": "Apple at Work - Success Stories - BDC",
      "link": "https://www.apple.com/business/enterprise/success-stories/financial-services/bdc/",
      "snippet": "Apple Business Manager and AirWatch Mobile Device Management allow BDC to effortlessly deploy and manage devices and apps across the company entirely zero-touch ...",
      "image_url": "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcRDQuxFNiitOIuPizPvTHwzQqyuLuypH_UNPqcZ-bGUAFy2&s",
      "source": "Apple",
      "date": "Nov 2, 2021",
      "position": 7
    },
    {
      "title": "Higher Education - Institutions",
      "link": "https://www.apple.com/education/higher-education/",
      "snippet": "More ways to shop: Find an Apple Store or other retailer near you. Or call 1-800-MY-APPLE (1-800-692-7753). United States. Copyright © 2025 Apple Inc. All ...",
      "image_url": "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcSIZRPg0iWQmiRPY-Ro1XmdUQYbwGmIxUgMjjL8TqdyutHF&s",
      "source": "Apple",
      "date": "Jun 8, 2018",
      "position": 8
    },
    {
      "title": "Apple: The Trillion Dollar Betrayal | The Truth About Your ...",
      "link": "https://www.youtube.com/watch?v=wmfuE-RM7Rg",
      "snippet": "Apple is the most valuable company in the world and has a role in our lives like no other. From smartphones to smart watches, ...",
      "image_url": "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcSvqw0lj-kWlq1HnowgEqzFxk5npWRpod2w1gogX-Dt4-jk&s",
      "video_url": "https://encrypted-vtbn0.gstatic.com/video?q=tbn:ANd9GcSG7N1JPdVZhrbuDckiwnYuWIQsXg_tdcmlvA",
      "duration": "52:40",
      "source": "YouTube",
      "channel": "Moconomy",
      "date": "Dec 4, 2024",
      "position": 9
    },
    {
      "title": "Apple at Work - Success Stories - SAP",
      "link": "https://www.apple.com/business/enterprise/success-stories/tech/sap/",
      "snippet": "SAP has found that offering its employees this choice goes far beyond letting people pick their computer. Mac unleashes their full potential. At a glance. 105K+ ...",
      "image_url": "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcSaplpBsRWWCJNlPtXsFX-jr3yw0mexpI6RtFKN6-TJAqrW&s",
      "source": "Apple",
      "date": "Apr 13, 2022",
      "position": 10
    }
  ]
}

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

news，搜索结果中视频信息列表。

可以看到，这里返回的结果中有一个 videos 字段，它主要包含了搜索关键词的结果。

自定义搜索资源所在国家

该接口也支持限定搜索结果的所在国家，我们可以添加 country 参数来限定国家，输入的参数为国家的简写，比如 cn（China）、us（United States），本文将以 China 做如下示例，下面为具体的信息：

输出效果如下：

{
  "news": [
    {
      "title": "Apple announces iOS 26 beta public roll out set for July",
      "link": "https://www.tv47.digital/apple-announces-ios-26-beta-public-roll-out-set-for-july-105190/",
      "snippet": "Tech giant Apple Inc. has unveiled the latest iterations of its operating systems for iPhone, Mac, and iPad, introducing a significant...",
      "date": "2 hours ago",
      "source": "TV47 Digital",
      "image_url": "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcTBNrktH4AWMt8KS3hErOkI1oAeUvRm4Aaq10qnINCa3TmyabOCwiEMvxVWsA&s",
      "position": 1
    },
    {
      "title": "Bragar Eagel & Squire, P.C. Is Investigating Apple, Sable and Abacus and Encourages Investors to Contact the Firm",
      "link": "https://www.tradingview.com/news/reuters.com,2025-06-17:newsml_GNX87dzHl:0-bragar-eagel-squire-p-c-is-investigating-apple-sable-and-abacus-and-encourages-investors-to-contact-the-firm/",
      "snippet": "NEW YORK, June 16, 2025 (GLOBE NEWSWIRE) — Bragar Eagel & Squire, P.C., a nationally recognized shareholder rights law firm,...",
      "date": "10 hours ago",
      "source": "TradingView",
      "image_url": "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcRdcHGK9sZ4M1wtCX6U74yV2ac9ClDX2hTSX4l4Brr1DWTvXfI4dKAn8sDU9g&s",
      "position": 2
    },
    {
      "title": "Apple Inc. (AAPL) Opinions on WWDC Software and AI Announcements",
      "link": "https://www.nasdaq.com/articles/apple-inc-aapl-opinions-wwdc-software-and-ai-announcements",
      "snippet": "Recent discussions on X about Apple Inc. (AAPL) have centered around the company's latest software updates and AI initiatives unveiled at...",
      "date": "17 hours ago",
      "source": "Nasdaq",
      "image_url": "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcSm5mhn6LRgzafnn34CrjlR3LS1_fHPmKNJckasyNgN4eYgBiCqGtulLQIViA&s",
      "position": 3
    },
    {
      "title": "Goldman Sachs Recommends Buying Apple, Expects Stock to Climb",
      "link": "https://finance.yahoo.com/news/goldman-sachs-recommends-buying-apple-042754922.html",
      "snippet": "Apple Inc. (NASDAQ:AAPL) is one of the best next generation dividend aristocrat stocks. Goldman Sachs recently highlighted a group of stocks...",
      "date": "6 hours ago",
      "source": "Yahoo Finance",
      "image_url": "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcS6QgEG6x6t12L8YqJebmoiPNM_RMjmiVUpwam1YXZgKwBUPGe6yn76hR-n0g&s",
      "position": 4
    },
    {
      "title": "Apple threatened with more noncompliance fines after losing Dutch App Store appeal",
      "link": "https://globalcompetitionreview.com/article/apple-threatened-more-noncompliance-fines-after-losing-dutch-app-store-appeal",
      "snippet": "The Netherlands Authority for Consumers and Markets has successfully fended off Apple's appeal against an order to amend its App Store rules...",
      "date": "17 hours ago",
      "source": "Global Competition Review",
      "image_url": "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcQ02b47E8UHdyFL6A4Da4Wla_nXXc427Y9aMgE7vVuJpN4CzLQp0ip_G77FwA&s",
      "position": 5
    },
    {
      "title": "Dutch court confirms Apple abused dominant position in dating apps",
      "link": "https://www.reuters.com/sustainability/boards-policy-regulation/dutch-court-confirms-apple-abused-dominant-position-dating-apps-2025-06-16/",
      "snippet": "A Dutch court on Monday confirmed a 2021 consumer watchdog 's ruling saying that Apple had abused its dominant position by imposing unfair...",
      "date": "19 hours ago",
      "source": "Reuters",
      "image_url": "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcQLRbz3ypqJL6zJo1LBfMen68-D4csUJbGNNO7w8JODW6fiKliGk0yRyRGfvQ&s",
      "position": 6
    },
    {
      "title": "Can Apple Salvage the AI iPhone in China?",
      "link": "https://www.bloomberg.com/opinion/articles/2025-06-10/can-apple-salvage-the-ai-iphone-in-china",
      "snippet": "If you thought Apple Inc.'s artificial intelligence woes in the US were bad, just know that they could actually be worse. Look at China.",
      "date": "6 days ago",
      "source": "Bloomberg.com",
      "image_url": "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcRzqIqxSek95GHKeeX9ekGIfzlZhz4jdEXqJPlk9Gyi5E8Yzk55iuhR5Soy_Q&s",
      "position": 7
    },
    {
      "title": "Apple requests S. Korea to allow transfer of high-precision map data overseas",
      "link": "https://en.yna.co.kr/view/AEN20250617006800320",
      "snippet": "SEOUL, June 17 (Yonhap) -- U.S. tech giant Apple Inc. has requested the South Korean gover...",
      "date": "5 hours ago",
      "source": "Yonhap News Agency",
      "image_url": "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcS20gcfgCXs4W5Hzu78JWocLIX_9jQPbN1rUUPctbiJ1UKd7R7eotC4CodJdQ&s",
      "position": 8
    },
    {
      "title": "Dutch Court Upholds Ruling Against Apple’s App Store Abuse",
      "link": "https://www.webpronews.com/dutch-court-upholds-ruling-against-apples-app-store-abuse/",
      "snippet": "In a significant blow to Apple Inc., a Dutch court has upheld a 2021 ruling by the Netherlands' Authority for Consumers and Markets,...",
      "date": "13 hours ago",
      "source": "WebProNews",
      "image_url": "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcSVZUsNtxTvIJYDjEGJN53uHWvK5NAGJrf-GS4wnzlSUtAbIYizew6HrYzr_w&s",
      "position": 9
    },
    {
      "title": "Dutch court confirms Apple abused dominant position for dating apps",
      "link": "https://seekingalpha.com/news/4458712-dutch-court-confirms-apple-abused-dominant-position-for-dating-apps",
      "snippet": "A Dutch court confirmed the country's competition agency's ruling that Apple (AAPL) abused its dominant position by imposing unreasonable...",
      "date": "2 hours ago",
      "source": "Seeking Alpha",
      "image_url": "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcSkf9LcqSBxw2DQZaDhfzZyJ0G2VRkkJ6dVHgBJFIGv_fgtPTDo2iAfQ_5fcQ&s",
      "position": 10
    }
  ]
}

可以看到，结果中是在 China 国家的搜索结果，具体的内容与上文是类似的。

自定义搜索结果语言

我们还可以自定义搜索结果的语言，这里我们额外添加 language 字段，内容为 zh-cn，其中它指的是简体中文的语言，同时还支持其他语言，但必须输入的语言的简写，比如 en（English）、fr（French）、zh-cn（Chinese（Simplified））等语言，如图所示：

对应代码如下：

curl -X POST 'https://api.acedata.cloud/serp/google' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "type": "news",
  "query": "apple inc",
  "language": "zh-cn"
}'

运行结果如下：

{
  "knowledge_graph": {
    "title": "苹果",
    "type": "公司",
    "website": "http://www.apple.com/",
    "image_url": "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcRgbY1KzXEpuPeTpcw0GwN6BpQTcg1m06TDUsfdG6P-zW3eWrmu78AXyg&s=0",
    "attributes": {
      "创始人": "史蒂夫·乔布斯、史蒂夫·沃兹尼亚克和罗纳德·韦恩",
      "创立于": "1976 年 4 月 1 日，加利福尼亚洛思阿图斯",
      "总部": "加利福尼亚库比蒂诺"
    }
  },
  "organic": [
    {
      "title": "Apple",
      "link": "https://www.apple.com/",
      "snippet": "Discover the innovative world of Apple and shop everything iPhone, iPad, Apple Watch, Mac, and Apple TV, plus explore accessories, entertainment, ...",
      "sitelinks": [
        {
          "title": "Support",
          "link": "https://support.apple.com/"
        },
        {
          "title": "Careers at Apple",
          "link": "https://www.apple.com/careers/us/"
        },
        {
          "title": "Store",
          "link": "https://www.apple.com/store"
        },
        {
          "title": "Business",
          "link": "https://www.apple.com/business/"
        },
        {
          "title": "Apple UK",
          "link": "https://www.apple.com/uk/"
        }
      ],
      "position": 1
    },
    {
      "title": "Apple Inc. - Wikipedia",
      "link": "https://en.wikipedia.org/wiki/Apple_Inc.",
      "snippet": "Apple Inc. is an American multinational corporation and technology company headquartered in Cupertino, California, in Silicon Valley.",
      "sitelinks": [
        {
          "title": "History",
          "link": "https://en.wikipedia.org/wiki/History_of_Apple_Inc."
        },
        {
          "title": "Litigation involving Apple Inc.",
          "link": "https://en.wikipedia.org/wiki/Litigation_involving_Apple_Inc."
        },
        {
          "title": "Apple Park",
          "link": "https://en.wikipedia.org/wiki/Apple_Park"
        },
        {
          "title": "Apple Watch",
          "link": "https://en.wikipedia.org/wiki/Apple_Watch"
        }
      ],
      "position": 2
    },
    {
      "title": "Apple Inc. | History, Products, Headquarters, & Facts - Britannica",
      "link": "https://www.britannica.com/money/Apple-Inc",
      "snippet": "Apple Inc. is an American multinational technology company that revolutionized the technology sector through its innovation of computer software, ...",
      "position": 3
    },
    {
      "title": "Apple Inc - Company Profile and News - Bloomberg Markets",
      "link": "https://www.bloomberg.com/profile/company/AAPL:US",
      "snippet": "Apple Inc. designs, manufactures, and markets smartphones, personal computers, tablets, wearables and accessories, and sells a variety of related ...",
      "position": 4
    },
    {
      "title": "Apple Inc. (AAPL) Stock Price, News, Quote & History - Yahoo Finance",
      "link": "https://finance.yahoo.com/quote/AAPL/",
      "snippet": "Apple Inc. designs, manufactures, and markets smartphones, personal computers, tablets, wearables, and accessories worldwide.",
      "date": "2024年8月27日",
      "position": 5
    },
    {
      "title": "AAPL: Apple Inc Stock Price Quote - NASDAQ GS - Bloomberg",
      "link": "https://www.bloomberg.com/quote/AAPL:US",
      "snippet": "Apple Inc. designs, manufactures, and markets smartphones, personal computers, tablets, wearables and accessories, and sells a variety of related accessories.",
      "position": 6
    },
    {
      "title": "Apple Inc. (AAPL) Company Profile & Facts - Yahoo Finance",
      "link": "https://finance.yahoo.com/quote/AAPL/profile/",
      "snippet": "See the company profile for Apple Inc. (AAPL) including business summary, industry/sector information, number of employees, business summary, ...",
      "position": 7
    }
  ],
  "people_also_ask": [
    {
      "question": "What is Apple Inc stand for?",
      "snippet": "It was incorporated as Apple Computer, Inc. in January 1977, and sales of its computers, including the Apple II , saw significant momentum and revenue growth for the company. \"Inc.\" is the abbreviation for incorporated. A corporation is a separate legal entity from the person or people forming it.",
      "title": "What does the 'Inc.' in Apple Inc. mean? - Quora",
      "link": "https://www.quora.com/What-does-the-Inc-in-Apple-Inc-mean"
    },
    {
      "question": "Who owns Apple Inc.?",
      "snippet": "Apple (AAPL) Ownership Overview The ownership structure of Apple (AAPL) stock is a mix of institutional, retail and individual investors. Approximately 48.76% of the company's stock is owned by Institutional Investors, 0.11% is owned by Insiders and 51.13% is owned by Public Companies and Individual Investors.",
      "title": "Who owns Apple? AAPL Stock Ownership - TipRanks.com",
      "link": "https://www.tipranks.com/stocks/aapl/ownership"
    },
    {
      "question": "Why did Apple change to Apple Inc?",
      "snippet": "During his keynote speech at the Macworld Expo on January 9, 2007, Jobs announced the renaming of Apple Computer, Inc. to Apple Inc., because the company had broadened its focus from computers to consumer electronics. This event also saw the announcement of the iPhone and the Apple TV.",
      "title": "Apple Inc. - Wikipedia",
      "link": "https://en.wikipedia.org/wiki/Apple_Inc."
    },
    {
      "question": "Why Apple Inc is called Apple?",
      "snippet": "With the name Apple, the new computer company would appear ahead of Atari, where Jobs used to work. Jobs confirmed this theory in an 1980 presentation, stating that the name was partly chosen because he liked apples and partly because Apple was ahead of Atari in the phone book.",
      "title": "Why Is Apple Called Apple? - Apple Scoop",
      "link": "https://applescoop.org/story/why-is-apple-called-apple"
    }
  ],
  "related_searches": [
    {
      "query": "apple inc是什么"
    },
    {
      "query": "apple澳门"
    },
    {
      "query": "Apple ID"
    },
    {
      "query": "apple美国"
    },
    {
      "query": "apple官网"
    },
    {
      "query": "apple美国官网"
    },
    {
      "query": "Apple company introduction"
    },
    {
      "query": "apple id官网"
    }
  ],
  "credits": 1
}

可以看到这里显示的结果都是简体中文的语言，结果的内容与上文类似。

自定义搜索结果时间范围

本文还可以自定义搜索结果的时间范围，包括了五种，分别是 qdr:h（过去一个小时）、qdr:d（过去一天）、qdr:w（过去一周）、qdr:m（过去一个月）、默认无限制，我们可以通过 range 传递对应的时间范围即可，比如这里设置为 qdr:d，这样表示搜索过去一天的结果，所以输入如下：

对应的代码如下：

curl -X POST 'https://api.acedata.cloud/serp/google' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "range": "qdr:d",
  "query": "apple inc"
}'

运行结果如下：

{
  "answer_box": {
    "title": "Tim Cook (Aug 24, 2011–)Apple / CEO",
    "answer": "Tim Cook (Aug 24, 2011–)"
  },
  "knowledge_graph": {
    "title": "Apple",
    "type": "Technology company",
    "website": "http://www.apple.com/",
    "image_url": "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcT5ITHsQzdzkkFWKinRe1Y4FUbC_Vy3R_M&s=0",
    "description": "Apple Inc. is an American multinational corporation and technology company headquartered in Cupertino, California, in Silicon Valley. It is best known for its consumer electronics, software, and services.",
    "description_source": "Wikipedia",
    "description_link": "https://en.wikipedia.org/wiki/Apple_Inc.",
    "attributes": {
      "Customer service": "1 (800) 275-2273",
      "Founders": "Steve Jobs, Steve Wozniak, and Ronald Wayne",
      "Founded": "April 1, 1976, Los Altos, CA",
      "Headquarters": "Cupertino, CA",
      "CEO": "Tim Cook (Aug 24, 2011–)"
    }
  },
  "organic": [
    {
      "title": "Apple",
      "link": "https://www.apple.com/",
      "snippet": "Discover the innovative world of Apple and shop everything iPhone, iPad, Apple Watch, Mac, and Apple TV, plus explore accessories, entertainment, ...",
      "sitelinks": [
        {
          "title": "Support",
          "link": "https://support.apple.com/"
        },
        {
          "title": "Career Opportunities",
          "link": "https://www.apple.com/careers/us/"
        },
        {
          "title": "Business",
          "link": "https://www.apple.com/business/"
        },
        {
          "title": "Apple Leadership",
          "link": "https://www.apple.com/leadership/"
        },
        {
          "title": "Store",
          "link": "https://www.apple.com/store"
        }
      ],
      "position": 1
    },
    {
      "title": "Apple Inc. - Wikipedia",
      "link": "https://en.wikipedia.org/wiki/Apple_Inc.",
      "snippet": "Apple Inc. is an American multinational corporation and technology company headquartered in Cupertino, California, in Silicon Valley.",
      "position": 2
    },
    {
      "title": "Apple Inc. | History, Products, Headquarters, & Facts - Britannica",
      "link": "https://www.britannica.com/money/Apple-Inc",
      "snippet": "American manufacturer of personal computers, smartphones, and tablet computers. Apple was the first successful personal computer company and ...",
      "date": "7 days ago",
      "position": 3
    },
    {
      "title": "Apple Inc. (AAPL) Company Profile & Facts - Yahoo Finance",
      "link": "https://finance.yahoo.com/quote/AAPL/profile/",
      "snippet": "Apple Inc. designs, manufactures, and markets smartphones, personal computers, tablets, wearables, and accessories worldwide. The company offers iPhone, a line ...",
      "position": 4
    },
    {
      "title": "AAPL: Apple Inc Stock Price Quote - NASDAQ GS - Bloomberg",
      "link": "https://www.bloomberg.com/quote/AAPL:US",
      "snippet": "Apple Inc. designs, manufactures, and markets smartphones, personal computers, tablets, wearables and accessories, and sells a variety of related accessories.",
      "position": 5
    },
    {
      "title": "Apple Inc. (AAPL) Stock Price Today - WSJ",
      "link": "https://www.wsj.com/market-data/quotes/AAPL?gaa_at=eafs&gaa_n=ASWzDAjHf1Jvm_DfBkgGitLxGwlDC2VFfkyeU3ora5VpP1k1gJJfptWjtU4o&gaa_ts=6851a5a8&gaa_sig=FmQcgCrdYtgMPhMwfFTpCtEva8_OZ5j1fx1cEBn0_THBq1EUa8A0Tmo3piNM3OQ488O2rScdH4NuSLly_DIdpQ%3D%3D",
      "snippet": "Apple Inc. engages in the design, manufacture, and sale of smartphones, personal computers, tablets, wearables and accessories, and other varieties of related ...",
      "position": 6
    }
  ],
  "people_also_ask": [
    {
      "question": "What is the Apple Inc?",
      "snippet": "Apple Inc., originally Apple Computer, Inc., is a multinational corporation that creates and markets consumer electronics and attendant computer software, and is a digital distributor of media content. Apple's core product lines are the iPhone smartphone, iPad tablet computer, and the Mac personal computer.",
      "title": "History of Apple Inc. - Wikipedia",
      "link": "https://en.wikipedia.org/wiki/History_of_Apple_Inc."
    },
    {
      "question": "Who owns Apple Inc?",
      "snippet": "Apple (AAPL) Ownership Overview Approximately 50.57% of the company's stock is owned by Institutional Investors, 0.06% is owned by Insiders, and 49.38% is owned by Public Companies and Individual Investors. The ownership structure of Apple (AAPL) stock is a mix of institutional, retail, and individual investors.",
      "title": "Who owns Apple? AAPL Stock Ownership - TipRanks.com",
      "link": "https://www.tipranks.com/stocks/aapl/ownership"
    },
    {
      "question": "What is Apple Inc. best known for?",
      "snippet": "It is best known for its consumer electronics, software, and services. Founded in 1976 as Apple Computer Company by Steve Jobs, Steve Wozniak and Ronald Wayne, the company was incorporated by Jobs and Wozniak as Apple Computer, Inc. the following year.",
      "title": "Apple Inc. - Wikipedia",
      "link": "https://en.wikipedia.org/wiki/Apple_Inc."
    },
    {
      "question": "Who is the current owner of Apple?",
      "snippet": "Tim Cook (Aug 24, 2011–)\nApple / CEO"
    }
  ],
  "related_searches": [
    {
      "query": "Apple iPhone 13"
    },
    {
      "query": "apple inc คืออะไร"
    },
    {
      "query": "Apple Inc full form"
    },
    {
      "query": "Apple Inc address"
    },
    {
      "query": "Apple Inc investor relations"
    },
    {
      "query": "Apple Inc industry"
    },
    {
      "query": "Apple Inc Annual Report"
    },
    {
      "query": "Apple Inc careers"
    }
  ]
}

可以看到，我们就成功得到了过去一天的搜索结果，结果内容与上文类似。

自定义搜索结果分页

本 API 还支持自定义搜索结果的分页展示，number 和 page 表示分页的页面大小和页数，本文将设置一页里面有 20 个搜索结果的形式来进行分页展示，具体的信息如图所示：

注意：当每页结果超过 10 个时，扣除的积分会翻倍。

代码如下：

curl -X POST 'https://api.acedata.cloud/serp/google' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "query": "apple inc",
  "number": 20,
  "page": 1
}'

运行结果如下：

{
  "knowledge_graph": {
    "title": "Apple",
    "type": "Technology company",
    "image_url": "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcSHmAG45NsvdRfYlNghHFvinM0w2mqjd8A0lXKU2LA&usqp=CAE&s",
    "attributes": {
      "Customer service": "1 (800) 275-2273",
      "Founders": "Steve Jobs, Steve Wozniak, Ronald Wayne",
      "Founded": "April 1, 1976, Los Altos, CA",
      "Stock price": "AAPL (NASDAQ) $198.42 +1.97 (+1.00%)Jun 16, 4:00 PM EDT - Disclaimer",
      "Headquarters": "Cupertino, CA",
      "CEO": "Tim Cook (Aug 24, 2011–)"
    }
  },
  "organic": [
    {
      "title": "Apple",
      "link": "https://www.apple.com/",
      "snippet": "Discover the innovative world of Apple and shop everything iPhone, iPad, Apple Watch, Mac, and Apple TV, plus explore accessories, entertainment, ...",
      "sitelinks": [
        {
          "title": "Support",
          "link": "https://support.apple.com/",
          "snippet": "iPhone Support - Contact - Billing and Subscriptions - Apple Repair"
        },
        {
          "title": "Career Opportunities",
          "link": "https://www.apple.com/careers/us/",
          "snippet": "Work at Apple - Software and Services - Support and Service"
        },
        {
          "title": "Business",
          "link": "https://www.apple.com/business/",
          "snippet": "Small Business - Enterprise - Shop for Business - Apple at Work - ..."
        },
        {
          "title": "Store",
          "link": "https://www.apple.com/store",
          "snippet": "Shop iPhone - Shop Mac - Shop iPad - App Store - ..."
        },
        {
          "title": "Investor Relations",
          "link": "https://investor.apple.com/investor-relations/default.aspx",
          "snippet": "SEC Filings - Stock Price - Leadership and Governance"
        }
      ],
      "position": 1
    },
    {
      "title": "Apple Inc.",
      "link": "https://en.wikipedia.org/wiki/Apple_Inc.",
      "snippet": "Apple Inc. is an American multinational corporation and technology company headquartered in Cupertino, California, in Silicon Valley.",
      "position": 2
    },
    {
      "title": "Apple Inc. | History, Products, Headquarters, & Facts",
      "link": "https://www.britannica.com/money/Apple-Inc",
      "snippet": "Apple Inc. is an American multinational technology company that revolutionized the technology sector through its innovation of computer software, personal ...",
      "date": "7 days ago",
      "position": 3
    },
    {
      "title": "Apple Inc. (AAPL) Company Profile & Facts",
      "link": "https://finance.yahoo.com/quote/AAPL/profile/",
      "snippet": "Apple Inc. designs, manufactures, and markets smartphones, personal computers, tablets, wearables, and accessories worldwide.",
      "position": 4
    },
    {
      "title": "AAPL: Apple Inc Stock Price Quote - NASDAQ GS",
      "link": "https://www.bloomberg.com/quote/AAPL:US",
      "snippet": "Apple Inc. designs, manufactures, and markets smartphones, personal computers, tablets, wearables and accessories, and sells a variety of related accessories.",
      "position": 5
    },
    {
      "title": "Apple Inc. (AAPL) Stock Price Today",
      "link": "https://www.wsj.com/market-data/quotes/AAPL?gaa_at=eafs&gaa_n=ASWzDAgqDxGuyZUvNqcmVhmXBoGHd3y-StLOZpo82befc3s9jFqSwwJzjPmn&gaa_ts=68514b6e&gaa_sig=a-sNk_J7mCIayZx21oIaY6Ge6vifnmxy7A4psXod_wP6ng9689uAwZYvUOUQPv_dxcArYe_RQbKxCkwngcK_bQ%3D%3D",
      "snippet": "Apple Inc. engages in the design, manufacture, and sale of smartphones, personal computers, tablets, wearables and accessories, and other varieties of related ...",
      "position": 6
    },
    {
      "title": "Apple",
      "link": "https://www.linkedin.com/company/apple",
      "snippet": "External link for Apple. Industry: Computers and Electronics Manufacturing. Company size: 10,001+ employees. Headquarters: Cupertino, California. Type: Public ...",
      "position": 7
    },
    {
      "title": "Apple | AAPL Stock Price, Company Overview & News",
      "link": "https://www.forbes.com/companies/apple/",
      "snippet": "Apple Inc. engages in the design, manufacture, and sale of smartphones, personal computers, tablets, wearables and accessories, and other variety of related ...",
      "position": 8
    },
    {
      "title": "Apple Inc. (AAPL) Stock Price, News, Quote & History",
      "link": "https://finance.yahoo.com/quote/AAPL/",
      "snippet": "Find the latest Apple Inc. (AAPL) stock quote, history, news and other vital information to help you with your stock trading and investing.",
      "position": 9
    },
    {
      "title": "iCloud",
      "link": "https://www.icloud.com/",
      "snippet": "At iCloud.com, you can access your photos, files, and more from any web browser. Changes you make will sync to your iPhone and other devices.",
      "position": 10
    },
    {
      "title": "Apple Inc (AAPL) Stock Price & News - Google Finance",
      "link": "https://www.google.com/finance/quote/AAPL:NASDAQ?hl=en",
      "snippet": "Apple Inc. is an American multinational corporation and technology company headquartered in Cupertino, California, in Silicon Valley.",
      "position": 11
    },
    {
      "title": "Apple Inc Company Profile - GlobalData",
      "link": "https://www.globaldata.com/company-profile/apple-inc/",
      "snippet": "Apple Inc (Apple) designs, manufactures, and markets smartphones, tablets, personal computers, and wearable devices. The company offers software applications ...",
      "position": 12
    },
    {
      "title": "The Founding of Apple Computer, Inc. - This Month in ...",
      "link": "https://guides.loc.gov/this-month-in-business-history/april/apple-computer-founded",
      "snippet": "Apple Computer, Inc. was founded on April 1, 1976, by college dropouts Steve Jobs and Steve Wozniak, who brought to the new company a vision of changing the ...",
      "position": 13
    },
    {
      "title": "Apple Inc",
      "link": "https://vimeo.com/appleinc",
      "snippet": "Apple Inc is a member of Vimeo, the home for high quality videos and the people who love them.",
      "position": 14
    }
  ],
  "people_also_ask": [
    {
      "question": "What is the Apple Inc?"
    },
    {
      "question": "Who owns Apple Inc?"
    },
    {
      "question": "What is Apple Inc. best known for?",
      "title": "Apple Inc. - Wikipedia",
      "snippet": "It is best known for its consumer electronics, software, and services. Founded in 1976 as Apple Computer Company by Steve Jobs, Steve Wozniak and Ronald Wayne, the company was incorporated by Jobs and Wozniak as Apple Computer, Inc. the following year.",
      "link": "https://en.wikipedia.org/wiki/Apple_Inc.#:~:text=It%20is%20best%20known%20for,%2C%20Inc.%20the%20following%20year."
    },
    {
      "question": "What is the meaning of Inc in Apple Inc?",
      "title": "Inc. | English meaning - Cambridge Dictionary",
      "snippet": "abbreviation for incorporated: used in the names of US companies that are legally established: Bishop Computer Services, Inc.",
      "link": "https://dictionary.cambridge.org/dictionary/english/inc#:~:text=abbreviation%20for%20incorporated%3A%20used%20in,Bishop%20Computer%20Services%2C%20Inc."
    }
  ],
  "related_searches": [
    {
      "query": "apple inc คืออะไร"
    },
    {
      "query": "Apple Inc full form"
    },
    {
      "query": "Apple Inc address"
    },
    {
      "query": "Apple Inc investor relations"
    },
    {
      "query": "Apple Inc industry"
    },
    {
      "query": "Apple Inc Annual Report"
    },
    {
      "query": "Apple Inc careers"
    },
    {
      "query": "Apple 17 pro"
    }
  ]
}

可以看到，这里它对搜索结果进行了分页展示，一页里面展示了 20 条结果，结果的内容与上文类似。

作者崔庆才发表于 2026-06-18 阅读次数：本文字数： 35k 阅读时长 ≈ 32 分钟

技术教程 OpenCode 对接 Suno MCP

📘 Overview：OpenCode MCP Overview →

你正在终端里写一段产品发布日志，写完之后突然想到：如果有一段 30 秒的 BGM 配合视频版 release notes 就更完整了。接上 Suno MCP Server 之后，OpenCode 可以直接根据你描述的情绪、风格、节奏现场写歌，不用切到浏览器，也不需要单独的音乐生成账号。

Suno MCP 适合在 OpenCode 里随手生成发布配乐、产品演示 BGM、demo 视频背景音乐、甚至完整的带歌词的成品歌曲。

获取 API Token

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

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

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

想用 Claude Desktop / Claude.ai 网页版直接 OAuth 一键授权？请看 Suno 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，适合”我自己的机器，一次配好，所有项目都能用”。

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "suno": {
      "type": "remote",
      "url": "https://suno.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 suno 也会回显 OAuth explicitly disabled，代表生效。

项目级：仅当前项目生效

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

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "suno": {
      "type": "remote",
      "url": "https://suno.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....，临时配置已删除。

$ opencode --version
1.15.13

$ opencode mcp list

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

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

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

1	opencode mcp debug suno

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

🤖 选模型的实测建议：在 OpenCode 里要真正让模型主动调用 Suno 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	写一首轻快的 lofi 嘻哈，2 分钟左右，没有歌词，用作编程视频的背景音乐

自定义歌词 + 风格

1	用 indie rock 风格唱这段歌词：（粘贴歌词），男声，2 分 30 秒

翻唱已生成歌曲

1	把上一首歌改成爵士风格翻唱

从副歌续写

1	副歌不错，从副歌往后再续 30 秒

工具列表

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

工具	说明
suno_generate_music	一句话描述生成整首歌
suno_generate_custom_music	自己写歌词、定风格和人声
suno_extend_music	从某个时间点续写已有歌曲
suno_cover_music	换一种风格翻唱
suno_mashup_music	把两首歌混搭成一首
suno_stems_music	分离人声和伴奏
suno_generate_lyrics	AI 生成歌词
suno_create_persona	保存声音风格

API 开发教程 Veo Reshoot API 对接说明

本文将介绍 Veo Reshoot API 的对接说明。该接口用于对一段已经生成的 Veo 视频按照新的镜头运动方式重新生成，画面内容保持一致，但镜头机位与运动会按 motion_type 重新演绎。

申请流程

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

基本使用

调用本接口需要传入下列参数：

video_id（必填）：来源视频的任务 ID。不能是 /veo/extend 的输出视频。
motion_type（必填）：新的镜头运动方式，使用大写下划线风格的简洁别名。

`motion_type` 支持值

别名	含义
`STATIONARY`	镜头固定不动
`STATIONARY_UP`	镜头固定，向上俯仰
`STATIONARY_DOWN`	镜头固定，向下俯仰
`STATIONARY_LEFT`	镜头固定，左摇
`STATIONARY_RIGHT`	镜头固定，右摇
`STATIONARY_DOLLY_IN_ZOOM_OUT`	镜头固定，前推 + 推焦
`STATIONARY_DOLLY_OUT_ZOOM_IN`	镜头固定，后退 + 拉焦
`UP`	镜头上升
`DOWN`	镜头下降
`LEFT_TO_RIGHT`	镜头从左向右平移
`RIGHT_TO_LEFT`	镜头从右向左平移
`FORWARD`	镜头向前推进
`BACKWARD`	镜头向后退
`DOLLY_IN_ZOOM_OUT`	移动中前推 + 推焦
`DOLLY_OUT_ZOOM_IN`	移动中后退 + 拉焦

请求示例：

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

返回结果结构与 /veo/videos 相同。

计费说明

单次重拍：1.20 Credit。

异步回调

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

作者崔庆才发表于 2026-06-16 阅读次数：本文字数： 986 阅读时长 ≈ 1 分钟

API 开发教程 hCaptcha 协议识别 API 对接说明

本文将介绍一种 hCaptcha 协议识别 API 对接说明，它可让用户无需识别和点选 hCaptcha 验证码图片，仅需通过提交 Website Key 即可实现后台自动解码，完成验证。

申请流程

要使用 hCaptcha 协议识别 API，首先到 Ace Data Cloud 控制台获取您的 API Token，留作备用。

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

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

📘 完整文档：hCaptcha 协议识别 API →

基本使用

首先先了解下基本的使用方式，就是输入需要处理 hCaptcha验证码的网站URL，便可获得处理后的结果，首先需要简单地传递一个 website_url 字段，我们的示例网站是：https://accounts.hcaptcha.com/demo，我们需要在 website_url 页面中获取 website_key，首先需要打开这个网页，按F12进入控制台，最后在Element页面进行全局搜索 hcaptcha-demo，我们可以得到下面的结果：

其中 data-sitekey 对应的一串字符串便是 website_key的值，下面是具体的参数结果：

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

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

另外设置了 Request Body，包括：

website_url：需要处理验证码的网站URL。
website_key：在hCaptcha中的网站密钥标识符。

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

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

1
2
3

{
  "token": "P1_eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.hadwYXNza2V5xQda4nQzFgUbYJqILiiwbvyhjocSilg8RjFHvIHmCzmqUNZa9hesIWEVRx5KIbMVeAQzSTWCwXmiQrPZuIEmZz-ZPL6DPNmB3ZXtJNsVYRLdRyvWPTB7EYskJG85yDVor2TcgQFNqAahhKT3WXjtk3S54ZBhv7QvaImUmos8MWgUOvUZHsvUtojN-izWIrBkD1if_71quOHvcvEVTLcSLx9dOgzpNAJ8_6BmJEsGlPbMGnSKrS1QfpPyzvgrnpjjIY_6TMYwJrR0EwJgCdp_lfc4mkxl0NJsZt8D_q7jcv3v6jt1CZ2qbqF5_-i4y0MYnQMCm1T62xBPdiEyst_FtGuWxJllkrrmWN0edyWcWeasLcCS6qpRry0H7RU7DYQnML6dmQoZg15NT0tFrAYeLK7EwvJxzcFbvUQ-Tc5QVk7tzvKpDtUVfQeZmRRgxWbCFf6bAT1z0uUwdma1O1lcTkSZCC5cVTaprkkKE04Ov4aCIKg2N7WGj4r0AOykisAISX5oidF3gejDTJy9vU1hgaCYFOimnwRKyqRsJdznptzhzDOQuICuAHYT3is1sY26ltJGOZTdDKkt2i2owCoAylgLbBP8VjTOGrsM12IH3Xsy076O40RCG6zThWN5TFKSpl7PNA6l2KoW-P3_K9WORjx2DSvKTAwqcouSU-0Rc_8Hlq9cIuS1iDhiNfJnJ_zNy_2gXSR2j7NP7m_lsfwELKypKm6pPzIhOuz5RwPotfPQfXOMdF3Xy98iQiihZmuHENvLAhjV_W7NL9TK3THPwDTFriS8ghIncl02v-fVARXDiuFTvjjlegL7xbHgIrOhLpunsxLiwdImUWatEI9jqaf84X4BtoS0TGYo4pHkpIG10dhoz3vooeSToAws6tz7ZWSHm6naksZ41X_WIxd7N8P9yzxrbLgVv-nHia5qHQLDmiZf3alITKhtisennw8NpespaQIVZzw_B16bdUNKqHCCTLdFbr16-3KpRoHzOOU2kBhV-gDN0NiA3ecqIMnyMdnpKlUpnjJ5sMA3e0pKEX_Vbu8DE8zfkcwLIwCIb2BLrKEHnCvv4JX8TfBktzMc5oTtZyEu-E_6ew0mSm_nhVsGtmLXSsB81FP9VGGRd50buIXRNW4GFp3XdTmYyuN32kc-AHJ5kKDj2HGraHxKco0McT7nV2bgx97k-C7hgxL2x5t3lC97edphh2kt2-gXuTxxfB7K-ZG6w5d1MnRte4ZG7TxvPFFi5693IFRFbvcr-U3WyGZJmGGdfV55PnoIU9Qn-WDtBU4EXyvd_KTt-asHtI6VQiVSNzacemTfsu9WBF33f2gafDY4qqhyXDPNsu6BZCGMSBhxDPURY74OBr4mYOdhjELY07nSkr9RQtQwiiSa8B8XFlezCPafjgdbmmNzG3PXa3n23sSwVnJHpHhq79eTP_KeeCiqlCvNsHLEfiH5HCNRGp7v5b342wBk__BWFimJMvohz0rucTVYgVFBdTOomUTuqCPeUgDP3X6BnNqyVDRA-HrdRl-RkU6mnw-3-IwyMZQ-fEnFMzbGp3zaoY7Do2jKvKKILoq6Q8zlDYkrLwuXjDP-nernI2hxP9wVOUVmtq5Rs19RLUI4MNWZAqwG-wGnaoB756d8nfmh5XhFzvArE5bpL50FY1yJqv7nbPW7JNnkfZG80yVRrIZO_F9NEb3n4eiIzg9Gu9fv8ncyChiCCp-swK5B7_w-XsAlco98bO-YK-fFMJOhyt0PU8Zc-hYoCa6cLVTvhdPzIUA0CQOemg4Pz6PX6SVwLYSlOXYkzbrgBlyH5YBS3oaRCeavVLrJsKt0_KwHwgBa1mdP5mlYUpBDbKR4PKwknU7y111JH0B4fO39dOVA-zecvDG0bnuy98Jym4KUchZr1tXabMcM20mg1UvcxMfnKOx0ojBcVwYA7kPQK3EzMnwX9NbAzYP6IlMgjFK9ZM7HCXxN6J1_6kw10RT4O58-Pbh3cMSrZDfM-GuG7p7XrVpJrX8TD195DCJqx-DmVv3Bs3CiuCPTvGrSZ58KE4hQagidGreUD2WXxLBFfTv1RgM3eXMtROs7hddyBajIu401lxucNbpRB7lYV7pJwxG7LQoSZ2G2LzG8eFPVPIkDNVOa8nGzh-sWaF7kc7bVv-P4FXbLX0WCjvQRES2MCbXPyJ-OpZZXZcJy7SOsGY3jZbTkGoez19cRQLiFO35gA5l9FBptDKW-_yGemt5XeKsR_FwGPN9C-0k1E-28oB4iKo-h1zb2kJpilhnmG36Z59F5T6W77M7OD_N6VHRWuPClLElO09OrPLHbJmxq9JvMWjTg5JjEaqyTLyLXWgw0N3kZMCqJJeqNj5w5I7dpuJ6ScfXKVaT96v2UESebdbMFT7vkZAkFF8LIowkN56pNwXLHkB2KyIWR2WQL-335BEpQ0AVB6RX4kdociIhtvAdsIE6pvFIwkzyO0OvIHxzOwPxZKdmDmBVMu7YxJStrhY-XWCu4kO5gDIJ0iedPWKNleHDOZuZqGKhzaGFyZF9pZM4xrUyBomtyqDE1ZmUwNDhkonBkAA.dVWyVc6N3lx2ZJQ7NJ9aEsWA-KAIuQ4PMSKVGQuWyCA"
}

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

token，此次 hCaptcha验证码任务处理后验证结果。

可以看到我们得到了处理 hCaptcha验证码的验证结果，然后我们可以用于POST或模拟提交给目标网站，一次性使用，有效期120s，建议在60s内使用，接下来将提供一段CURL版本将处理后token提交到目标网站来通过Recaptcha2验证码。

首先我们需要获取网站是如何发送POST请求，这样我们才能将生成的token传入进去，我们需要先打开F12控制台，然后人工先通过一下，最后我们可以看到网站发送了一个POST请求，我们只需要查看这次的POST请求构造，具体的过程如下：

先人工通过验证，具体的如下图：

再点击submit，观看控制台的network变化，具体的如下图：

分析此次提交的POST请求构造，最后可以右键该请求复制CURL的代码，具体的如下图：

由上图分析可知，此次POST请求的URL为：https://accounts.hcaptcha.com/demo，我们仅需要提交参数 g-recaptcha-response、h-captcha-response 和 email，然后我们只需要将处理后的token传入下面的data中即可，调用token验证所对应CURL代码如下：

1 2	curl 'https://accounts.hcaptcha.com/demo' \ --data-raw 'email=&g-recaptcha-response={token}&h-captcha-response={token}'

调用token验证所对应的Python代码如下：

import requests

token = '{token}'

data = {
    'email': '',
    'g-recaptcha-response': token,
    'h-captcha-response': token
}

response = requests.post('https://accounts.hcaptcha.com/demo',
                        data=data)

if response.status_code == 200:
    print(response.text)

然后我们观察控制台变得了这样的结果：

最后我们就通过了hCaptcha验证码的验证。

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

curl -X POST 'https://api.acedata.cloud/captcha/token/hcaptcha' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "website_key": "a5f74b19-9e45-40e0-b45d-47ff91b7a6c2",
  "website_url": "https://accounts.hcaptcha.com/demo"
}'

Python 的对接代码如下：

import requests

url = "https://api.acedata.cloud/captcha/token/hcaptcha"

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

payload = {
    "website_key": "a5f74b19-9e45-40e0-b45d-47ff91b7a6c2",
    "website_url": "https://accounts.hcaptcha.com/demo"
}

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.

错误响应示例

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

结论

通过本文档，您已经了解了如何使用 hCaptcha 协议识别 API 让用户无需识别和点选 hCaptcha 验证码图片，仅需通过提交 Website Key 即可实现后台自动解码，完成验证。希望本文档能帮助您更好地对接和使用该 API。如有任何问题，请随时联系我们的技术支持团队。

作者崔庆才发表于 2026-06-16 阅读次数：本文字数： 5.9k 阅读时长 ≈ 5 分钟

API 开发教程 身份证人像照片验真 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：需要处理的身份证图片链接。
config：可选配置项，布尔值字段，默认都为 false，支持 copy_warn、border_check_warn、reshoot_warn、detect_ps_warn、temp_id_warn、quality（阈值 0-100）。

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

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

{
  "sim": 99.76,
  "result": "Success",
  "description": "成功",
  "name": "身份证姓名",
  "sex": "身份证性别",
  "nation": "身份证民族",
  "birth": "身份证生日",
  "address": "身份证家庭住址",
  "id_num": "身份证号码",
  "portrait": "/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAEBAQEBAQEBAQEBAQEBAQEBAQEBA.....DEhE2lbPMcOtG3f/DLT/yX8if7Kxn/AD7h85wdttPifRf1e6//2Q==",
  "warnings": "",
  "quality": 0,
  "encryption": null
}

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

sim，相似度，取值范围 [0.00, 100.00]。推荐相似度大于等于70时可判断为同一人，可根据具体场景自行调整阈值（阈值70的误通过率为千分之一，阈值80的误通过率是万分之一）
result，业务错误码，成功情况返回Success, 错误情况请参考下方错误码列表中FailedOperation部分。
description，此处姓名与身份证号码验证的结果。
name，身份证中的姓名信息，如果没有上传身份证图片则是空的。
sex，身份证中的性别信息，如果没有上传身份证图片则是空的。
nation，身份证中的民族信息，如果没有上传身份证图片则是空的。
birth，身份证中的生日信息，如果没有上传身份证图片则是空的。
address，身份证中的家庭住址信息，如果没有上传身份证图片则是空的。
id_num，身份证中的身份证号码信息，如果没有上传身份证图片则是空的。
portrait，身份证头像照片的base64编码，如果抠图失败会拿整张身份证做比对并返回空。
warnings，告警信息，当在Config中配置了告警信息会停止人像比对，Result返回错误（FailedOperation.OcrWarningOccurred）并有此告警信息。
quality，图片质量分数，当请求Config中配置图片模糊告警该参数才有意义，取值范围（0～100），目前默认阈值是50分，低于50分会触发模糊告警。
encryption，敏感数据加密信息。

可以看出身份证信息具有很高的真实性。

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

curl -X POST 'https://api.acedata.cloud/identity/idcard/check-1e' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "image_url": {image_url}
}'

Python 的对接代码如下：

import requests

url = "https://api.acedata.cloud/identity/idcard/check-1e"

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

payload = {
    "image_url": {image_url}
}

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.

错误响应示例

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

结论

通过本文档，您已经了解了如何使用身份证人像照片验真 API 对用于传入身份证人像面照片，识别身份证照片上的信息，并将姓名、身份证号、身份证人像照片与权威库的证件照进行比对，是否属于同一个人，从而验证身份证信息的真实性。希望本文档能帮助您更好地对接和使用该 API。如有任何问题，请随时联系我们的技术支持团队。

作者崔庆才发表于 2026-06-15 阅读次数：本文字数： 3k 阅读时长 ≈ 3 分钟

产品推广 用 5 秒视频讲一个精彩开场：Pika 视频生成 API，短内容的爆发点（含超多示例与图例）

在短内容时代，第一眼的动态决定了你是否拥有第二次讲述的机会。Ace Data Cloud 的 Pika Videos API，让你把“灵感句子/参考图/参考视频”变成 5–6 秒高质感动效——是短视频开场、产品亮点、表情包、动图广告、栏目片头的绝佳素材源。

关键链接

文档页：Pika Videos Generation API https://platform.acedata.cloud/documents/pika-videos
接口：POST https://api.acedata.cloud/pika/videos

可视化参数与界面示意

文生视频参数与模型选择：
自动生成代码与 Try 运行：

一、案例合集（每个案例含请求、返回与视频/封面字段）

案例 1：文生视频（1.5 模型）快速做“开场钩子”

输入（cURL，节选）

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

输出（节选）

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

案例 2：视频生视频（2.0 模型）加风格特效

表单与代码生成示意：
输入（Python，节选）

import requests
url = "https://api.acedata.cloud/pika/videos"
headers = {"accept": "application/json","authorization": "Bearer {token}","content-type": "application/json"}
payload = {
  "action": "generate",
  "effect": "Pink Hair",
  "prompt": "moving",
  "model": "2.0",
  "video_url": "https://cdn.acedata.cloud/0slqxa.mp4"
}
print(requests.post(url, json=payload, headers=headers).text)

输出（节选）

{
  "success": true,
  "data": [
    {
      "id": "d4472f11-bbce-4512-8054-cab1c04e3a8b",
      "state": "complete",
      "prompt": "Pink Hair",
      "model": "Pro",
      "quality": "1080p",
      "video_url": "https://cdn.pika.art/v1/d4472f11-bbce-4512-8054-cab1c04e3a8b/Pink_Hair_seed776225645.mp4",
      "image_url": "https://cdn.pika.art/v1/d4472f11-bbce-4512-8054-cab1c04e3a8b/poster.jpg",
      "duration": 5.04
    }
  ]
}

案例 3：Webhook 回调（批量更稳定）

回调设置示意：
回调示例页：
输出（回调载荷，节选）

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

二、工作流建议（轻量但高效）

写“1 句钩子文案”与“1 个镜头意图”；
文生视频用 1.5 模型跑 3–5 个版本，挑最佳；
视频生视频用 2.0 模型给已有视频加风格/惊喜；
导入编辑软件，拼接成自然节奏点；
用回调做批量产出，素材库沉淀 video_url/image_url/duration/state。

三、适用场景

短视频开场/转场、栏目片头、LOGO reveal；
表情包与社交动效、产品亮点动画；
直播间活动小动画、广告动图素材。

四、提示词与参数技巧

动作词更清楚：出现/飞入/爆闪/旋转/拆解/聚合/抖动；
节奏尽量短：5–6 秒最抓人；
保持统一风格：配色/光影/运动一致性，形成“品牌节奏”。

为什么是 Pika

快速产出：文本生视频（1.5 模型）与视频生视频（2.0 模型）两套能力，分钟级出片；
成熟效果：内置多种特效（如 Pink Hair、Wizard Cat 等），创意更具“可玩性”；
易于编排：返回封面图、清晰度、时长、状态等结构化字段，自动化接入素材库；
成本友好：按量计费，先拿免费额度快速验证，再规模应用。

三类典型用法

短视频开场/转场
- “Ta-da” 式惊喜出现、LOGO 飞入、产品旋转上镜，5 秒内抓住视线；
- 把文本脚本拆成多个“开场钩子”，批量生成备用动效。
表情包与社交动效
- 用一句流行语 + 角色形象，做自带节奏的动图包，社群传播率更高；
产品亮点展示
- 用视频生视频套上风格特效，打造更统一的品牌动效体系；

工作流建议：轻量但高效

写下“1 句钩子文案”与“1 个镜头意图”；
文生视频：选择 1.5 模型，生成 3–5 个版本，选最佳；
视频生视频：用 2.0 模型给已有视频“换风格/加惊喜”；
导入到你的编辑软件，和主视频拼接，形成自然的节奏点。

接入 3 步走

申请：进入 Ace Data Cloud 平台 Pika 文档页，点击 Acquire 获取凭证（通常有免费额度）；
发起：传入 action=generate，选择 model（1.5 文生、2.0 视频生），给出 prompt，可选 effect；
回调：生成需要时间，建议设置 callback_url，自动接收 video_url 与封面 image_url。

真实案例

一家 3C 品牌在“开箱视频”开头加入 Pika 生成的“电流穿梭”动效，5 秒捕获注意力；随后每次单品发布都复用同一风格开场，形成独特“品牌节奏”，平均完播率提升显著。

现在就让你的内容动起来

打开 Ace Data Cloud，搜索 Pika Videos，领取免费额度。今天写一句话，明天你的开场就能惊艳所有人。

作者崔庆才发表于 2026-06-14 阅读次数：本文字数： 3.3k 阅读时长 ≈ 3 分钟

API 开发教程 获取 AceDataCloud 平台模型列表

返回平台上全部可用的 LLM / 图像 / 视频 / 音频 / 嵌入 / 重排序模型——按 OpenAI /v1/models 风格的扁平视图返回，兼容 OpenAI SDK。一个 Proxy 服务通常对应数十乃至上百个模型。

适用场景：

在你产品里渲染「模型选择下拉」。
给路由层做模型可用性检查。
同步到 LiteLLM / OpenRouter 风格的中间层。

ℹ️ 本接口属于 AceDataCloud 平台管理 API，统一前缀 https://platform.acedata.cloud/api/v1/。

接口概览

项	内容
方法	`GET`
URL	`https://platform.acedata.cloud/api/v1/models/`
鉴权	❌ 公开

鉴权说明

本接口完全公开，无需账户令牌或登录态。

💡 但是：如果带上账户令牌，响应会按你已申请的服务过滤，仅返回你能调用的模型。

查询参数

参数	类型	必填	默认	说明
`service_id`	UUID	否	—	按服务过滤
`tag`	string	否	—	按标签过滤（如 `chat`、`embedding`、`image`、`video`、`tts`）
`limit`	integer	否	100	每页条数，最大 200
`offset`	integer	否	0	偏移
`ordering`	string	否	—	排序字段

请求示例

cURL

# 全部模型
curl 'https://platform.acedata.cloud/api/v1/models/?limit=200' \
  -H 'accept: application/json'

# 只看 chat 类
curl 'https://platform.acedata.cloud/api/v1/models/?tag=chat&limit=200' \
  -H 'accept: application/json'

Python

import requests

resp = requests.get(
    "https://platform.acedata.cloud/api/v1/models/",
    headers={"accept": "application/json"},
    params={"tag": "chat", "limit": 200},
    timeout=10,
)
data = resp.json()
print(f"共 {data['count']} 个 chat 模型")
for m in data["items"][:20]:
    print(f"  {m['id']:50s}  ${m.get('prompt_price') or 0:.6f}/1K in, ${m.get('completion_price') or 0:.6f}/1K out")

Node.js

1
2
3

const r = await fetch('https://platform.acedata.cloud/api/v1/models/?limit=200')
const { count, items } = await r.json()
console.log(`共 ${count} 个模型`)

响应示例（HTTP 200）

{
  "count": 187,
  "items": [
    {
      "id": "gpt-4.1",
      "object": "model",
      "owned_by": "openai",
      "service_id": "38ecf158-36f2-42f2-8e7f-6786cdfc2452",
      "service_alias": "openai",
      "service_title": "OpenAI",
      "context_window": 1048576,
      "max_output_tokens": 32768,
      "prompt_price": 0.000002,
      "completion_price": 0.000008,
      "cached_prompt_price": 0.0000005,
      "tags": ["chat", "vision", "tool_call"],
      "created_at": 1733616000
    }
  ]
}

ℹ️ 字段命名同时兼容 OpenAI 官方 /v1/models 响应（id、object、owned_by），可直接喂给 OpenAI SDK。

响应字段说明

字段	类型	说明
`id`	string	模型 ID（如 `gpt-4.1`、`claude-sonnet-4`、`midjourney`、`veo-3`）
`object`	string	恒为 `"model"`（OpenAI 兼容字段）
`owned_by`	string	模型所属方（`openai` / `anthropic` / `google` / `meta` / `xai`…）
`service_id`	UUID	该模型挂载的平台服务 ID
`service_alias`	string	服务别名
`service_title`	string	服务标题
`context_window`	integer	上下文窗口长度（Token 数，LLM 专属）
`max_output_tokens`	integer	单次最大输出 Token 数
`prompt_price`	number \	null	输入 Token 单价（单位：USD / Token，即美元每 Token，不是每 1K）
`completion_price`	number \	null	输出 Token 单价（USD / Token）
`cached_prompt_price`	number \	null	命中 prompt cache 的输入单价（USD / Token）
`tags`	array	模型能力标签：`chat` / `vision` / `tool_call` / `audio` / `embedding` / `rerank` / `image` / `video` / `tts` / `stt` 等
`created_at`	integer	模型上架时间（Unix 秒级时间戳，OpenAI 兼容字段）

错误处理

HTTP	code	含义
400	`invalid`	参数非法

实用提示

OpenAI SDK 兼容：本接口响应可直接用作 OpenAI Python SDK 的 client.models.list() 替代源。
价格是按 Token 计：不是按千 Token——这与 OpenAI 官方定价表显示的”per 1M tokens”不同。换算时记得乘 1,000,000。
null 价格表示按调用次数计费：通常是图像 / 视频 / 音频类模型，每次调用按固定 Credit 数计费，看创建 AceDataCloud 平台充值订单的套餐表。
过滤实际可调用的模型：带上账户令牌，只返回你已申请的服务下的模型。

API 开发教程 Grok Videos Generation API 对接说明

本文将介绍 Grok Videos Generation API 的对接说明，它可以通过输入文本提示词、输入图片以及可选的参考图片来生成 Grok Imagine（xAI）视频。

申请流程

要使用 API，需要先到 Grok Videos Generation API 对应页面申请对应的服务，进入页面之后，点击「Acquire」按钮，如图所示：

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

在首次申请时会有免费额度赠送，可以免费使用该 API。

模型说明

本 API 支持两种模型：

grok-imagine-video（默认）：支持文生视频（仅传 prompt）和图生视频（传 image_url），价格更低。
grok-imagine-video-1.5-preview：仅支持图生视频，必须传入 image_url。

基本使用

首先了解下基本的使用方式，输入提示词 prompt、模型 model 等参数，便可生成对应的视频。

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

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

另外设置了 Request Body，包括：

prompt：描述想要生成视频内容的文本提示词。使用 grok-imagine-video 做文生视频时必填；传入 image_url 时可选。
model：生成视频的模型，可选 grok-imagine-video（默认）或 grok-imagine-video-1.5-preview。
image_url：图生视频的输入图片链接。当 model 为 grok-imagine-video-1.5-preview 时必填。
reference_image_urls：可选的参考图片链接数组，用于引导视频的风格或内容。
aspect_ratio：生成视频的宽高比，可选 1:1 / 16:9 / 9:16 / 4:3 / 3:4 / 3:2 / 2:3。
resolution：输出分辨率，可选 480p（默认）或 720p，分辨率越高消耗的额度越多。
duration：生成视频的时长（秒），取值范围 1–15，默认 8。按输出秒数计费。
callback_url：异步回调地址，设置后 API 会立即返回 task_id，任务完成时将结果 POST 到该地址。

点击「Try」按钮即可进行测试，得到的结果类似如下：

{
  "success": true,
  "task_id": "b8976e18-32dc-4718-9ed8-1ea090fcb6ea",
  "trace_id": "fb751e1e-4705-49ea-9fd4-5024b7865ea2",
  "data": [
    {
      "id": "grok-imagine-video:41eb9a5f-3b2d-4d1e-9f5a-6c2f1a0b9e77",
      "video_url": "https://cdn.acedata.cloud/grok/example-video.mp4",
      "state": "succeeded"
    }
  ]
}

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

success：本次视频生成请求是否成功。
task_id：本次视频生成任务的 ID。
trace_id：本次请求的跟踪 ID，用于排查问题。
data：生成的视频结果列表。
- id：生成视频的唯一标识。
- video_url：生成视频的链接地址。
- state：视频生成任务的状态，可选 pending / succeeded / failed。

我们只需要根据结果中 data 的 video_url 链接地址获取生成的视频即可。

对应的 CURL 代码如下：

curl -X POST 'https://api.acedata.cloud/grok/videos' \
-H 'authorization: Bearer ${bearer_token}' \
-H 'accept: application/json' \
-H 'content-type: application/json' \
-d '{
  "prompt": "A cinematic shot of a kitten chasing a butterfly in a sunlit garden",
  "model": "grok-imagine-video",
  "resolution": "480p",
  "duration": 8
}'

对应的 Python 代码如下：

import requests

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

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

payload = {
    "prompt": "A cinematic shot of a kitten chasing a butterfly in a sunlit garden",
    "model": "grok-imagine-video",
    "resolution": "480p",
    "duration": 8
}

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

图生视频

如果想基于一张输入图片生成视频，可以传入 image_url。使用 grok-imagine-video-1.5-preview 时必须提供该字段：

{
  "prompt": "The character slowly turns around and smiles at the camera",
  "model": "grok-imagine-video-1.5-preview",
  "image_url": "https://cdn.acedata.cloud/grok/example-input.png",
  "resolution": "720p",
  "duration": 8
}

参考图引导

如果想用一张或多张参考图引导生成视频的风格或内容，可以在 reference_image_urls 中传入图片链接数组：

{
  "prompt": "A character dancing in the same art style",
  "model": "grok-imagine-video",
  "reference_image_urls": [
    "https://cdn.acedata.cloud/grok/example-reference.png"
  ]
}

异步回调

视频生成需要一定的处理时间。如果不希望保持长连接等待，可以传入 callback_url，此时 API 会立即返回 task_id，任务完成后会将最终结果 POST 到该地址：

{
  "prompt": "A cinematic shot of a kitten chasing a butterfly in a sunlit garden",
  "model": "grok-imagine-video",
  "duration": 8,
  "callback_url": "https://your-domain.com/callback/grok"
}

立即返回的结果如下：

1
2
3

{
  "task_id": "b8976e18-32dc-4718-9ed8-1ea090fcb6ea"
}

查询任务结果

如果使用了异步回调或希望主动查询任务状态，可以通过 Grok Tasks API（POST https://api.acedata.cloud/grok/tasks）根据 task_id 查询任务的最新状态与结果。

计费说明

本服务按生成视频的「输出秒数」计费，单价由 model 与 resolution 共同决定，总价 = 单价 × duration（默认 8 秒）。720p 比 480p 更贵，grok-imagine-video-1.5-preview 比 grok-imagine-video 更贵，具体单价以定价页为准。

错误处理

当请求出现问题时，API 会返回对应的错误码与说明，常见的如下：

400：请求参数有误，例如文生视频缺少 prompt，或 grok-imagine-video-1.5-preview 缺少 image_url，或 duration 超出 1–15 范围。
401：鉴权失败，token 无效或与 API 不匹配。
403：余额不足，或提示词命中内容审核被拒绝。
429：请求过于频繁，触发上游限流，请稍后重试。
500：服务器内部错误或上游生成失败。

作者崔庆才发表于 2026-06-13 阅读次数：本文字数： 3.6k 阅读时长 ≈ 3 分钟

产品推广 Claude.ai 对接 Face Transform 面部转换 MCP

📘 完整指南：在 Claude.ai 里用全部 AceData Cloud MCP →

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

配置

在 claude.ai 网页版 Settings → Customize → Connectors → Add custom connector 中填写：

字段	值
Name	`face`
URL	`https://face.mcp.acedata.cloud/mcp`

首次连接会跳转到 AceData Cloud 完成 OAuth 授权。

使用示例

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

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

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

工具

工具	说明
face_detect_keypoints	检测 90+ 面部关键点
face_beautify	美颜：磨皮 / 美白 / 瘦脸 / 大眼
face_change_age	年龄变换（变老 / 变年轻）
face_change_gender	性别变换
face_swap	换脸（两张图之间转移人脸）
face_cartoonize	卡通化
face_detect_liveness	活体检测

API 开发教程 获取 AceDataCloud 平台 API 调用量导出

异步生成包含所选时间段内全部业务接口调用流水的 CSV 文件，并返回下载 URL。适合月度对账、给财务出 BI 报表、给第三方审计师交付明细等场景。

📌 调用记录数量超过 1 万条时强烈建议用本接口而不是分页拉取调用记录列表——服务端生成 CSV 更快。

ℹ️ 本接口属于 AceDataCloud 平台管理 API，统一前缀 https://platform.acedata.cloud/api/v1/。

接口概览

项	内容
方法	`POST`
URL	`https://platform.acedata.cloud/api/v1/usages/export/`
鉴权	✅ 需要账户令牌
Content-Type	`application/json`

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

请求头：

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

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

请求体

字段	类型	必填	说明
`user_id`	UUID	✅	当前账户用户 ID（同样在 Body 里，不在 query 里）
`start_at`	datetime	✅	起始时间（ISO8601）
`end_at`	datetime	✅	结束时间（ISO8601）。单次导出窗口建议 ≤ 90 天
`application_id`	UUID	否	按 Application 过滤
`service_id`	UUID	否	按服务过滤
`credential_id`	UUID	否	按凭证过滤
`status_code`	integer	否	按 HTTP 状态码过滤

请求示例

cURL

curl -X POST 'https://platform.acedata.cloud/api/v1/usages/export/' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer platform-v1-92eb****629c' \
  -H 'content-type: application/json' \
  -d '{
    "user_id": "89518d07-5560-4b05-92c1-667f3ddf6a4b",
    "start_at": "2026-04-01T00:00:00Z",
    "end_at": "2026-04-30T23:59:59Z"
  }'

Python

import requests
import time

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

# 1. 发起导出任务
resp = requests.post(
    "https://platform.acedata.cloud/api/v1/usages/export/",
    headers={
        "authorization": f"Bearer {PLATFORM_TOKEN}",
        "content-type": "application/json",
    },
    json={
        "user_id": USER_ID,
        "start_at": "2026-04-01T00:00:00Z",
        "end_at": "2026-04-30T23:59:59Z",
    },
    timeout=30,
)
task = resp.json()
print(f"导出任务已创建：{task['id']}, 状态: {task['state']}")

# 2. 轮询状态直至生成完成
while task["state"] in ("Pending", "Processing"):
    time.sleep(2)
    task = requests.get(
        f"https://platform.acedata.cloud/api/v1/usages/export/{task['id']}",
        headers={"authorization": f"Bearer {PLATFORM_TOKEN}"},
    ).json()

if task["state"] == "Completed":
    print(f"✅ 导出完成，下载 URL: {task['file_url']}")
else:
    print(f"❌ 导出失败：{task.get('error')}")

Node.js

const r = await fetch('https://platform.acedata.cloud/api/v1/usages/export/', {
  method: 'POST',
  headers: {
    authorization: 'Bearer platform-v1-92eb****629c',
    'content-type': 'application/json',
  },
  body: JSON.stringify({
    user_id: '89518d07-5560-4b05-92c1-667f3ddf6a4b',
    start_at: '2026-04-01T00:00:00Z',
    end_at: '2026-04-30T23:59:59Z',
  }),
})
const task = await r.json()
console.log('任务 ID:', task.id)

响应示例（HTTP 202）

{
  "id": "exp-9c8b7a6d5e4f3a2b1c0d",
  "user_id": "89518d07-5560-4b05-92c1-667f3ddf6a4b",
  "state": "Pending",
  "start_at": "2026-04-01T00:00:00Z",
  "end_at": "2026-04-30T23:59:59Z",
  "file_url": null,
  "expires_at": null,
  "created_at": "2026-04-26T08:30:00Z"
}

完成后 state 变为 Completed 且 file_url 包含 CSV 下载链接（一般 24h 内有效）。

响应字段说明

字段	类型	说明
`id`	string	导出任务 ID
`state`	string	`Pending` / `Processing` / `Completed` / `Failed`
`file_url`	string \	null	完成后的 CSV 下载 URL（一般 24h 内有效）
`expires_at`	string \	null	下载 URL 失效时间
`start_at`	string	导出窗口起始
`end_at`	string	导出窗口结束
`error`	string \	null	失败原因（仅 `state=Failed` 时返回）

CSV 列定义

file_url 下载的 CSV 文件含以下列（首行为表头）：

1	created_at, application_id, service_id, credential_id, api_id, method, path, status_code, consumption, duration_ms, client_ip, request_id

字段含义同调用记录列表。

错误处理

HTTP	code	含义
400	`invalid`	`user_id` / `start_at` / `end_at` 缺失或格式错误
400	`window_too_large`	时间窗口超过限制（默认 90 天）
401	`not_authenticated`	缺少账户令牌
403	`permission_denied`	`user_id` 不是你的

实用提示

大窗口分段导出：跨年导出建议按月分多次任务。
下载 URL 有时效：一般 24 小时；过期需重新发起导出任务。
不要把 file_url 写在前端代码里：URL 含签名，应在后端转存到自己的存储再分发给用户。
CSV 编码 UTF-8 BOM：Excel 直接打开中文不乱码。

API 开发教程 Python SDK 接入教程

acedatacloud 是 Ace Data Cloud 官方 Python SDK，把 api.acedata.cloud 上所有服务封装成类型化的 client.openai.chat.completions.create(...)、client.images.generate(...)、client.search.google(...) 等方法，同时提供同步和异步两套客户端。

底层基于 httpx，支持 SSE 流式、自动重试、类型化异常和 pydantic 类型校验。

源码与包地址：

SDK 仓库：https://github.com/AceDataCloud/SDK
PyPI：https://pypi.org/project/acedatacloud/

安装

1 2	pip install acedatacloud # 或 uv add / poetry add

如果需要 X402 链上付费（无 API Token 路径），再装一个：

1	pip install acedatacloud-x402

干净 venv 的版本检查输出：

$ python -c "import importlib.metadata as m; print(m.version('acedatacloud'))"
2026.4.26.1

$ python -c "from acedatacloud import AceDataCloud, AsyncAceDataCloud; print('ok')"
ok

结果说明：

包版本是 2026.4.26.1（CalVer，2026 年 4 月 26 日修订）。
AceDataCloud 是同步客户端，AsyncAceDataCloud 是 asyncio 异步客户端。
本 SDK 不依赖 pydantic，响应体统一返回 dict。这一点和 openai-python 不同，迁移时需要注意。

准备 API Token

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

1	export ACEDATACLOUD_API_TOKEN={token}

构造客户端时不传 api_token，SDK 会自动读取 ACEDATACLOUD_API_TOKEN 环境变量。如果你的环境里已经存了 ACEDATACLOUD_API_KEY（项目仓库约定），请显式传入：AceDataCloud(api_token=os.environ["ACEDATACLOUD_API_KEY"])。

示例 1：chat.completions（同步）

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

程序运行结果：

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}

结果说明：

id 是上游响应 ID，可以在使用历史里搜到。
content ADC_PY_SDK_OK 是模型真实返回的固定标识。
res["usage"] 返回 dict，不是 pydantic model；一次调用大约消耗 24 token。

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

stream=True 时 create 返回一个普通生成器，每次 yield 一个解析好的 chunk dict。

import os, time
from acedatacloud import AceDataCloud

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

t0 = time.time()
first_chunk_ms = None
chunks = 0
collected = []

for chunk in client.openai.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Count from 1 to 5, separated by single spaces, no extra text."}],
    max_tokens=30,
    temperature=0,
    stream=True,
):
    if first_chunk_ms is None:
        first_chunk_ms = int((time.time() - t0) * 1000)
    chunks += 1
    delta = (chunk.get("choices") or [{}])[0].get("delta", {}).get("content")
    if delta:
        collected.append(delta)

print("total_elapsed_ms", int((time.time() - t0) * 1000))
print("first_chunk_ms", first_chunk_ms)
print("chunks", chunks)
print("collected", "".join(collected).strip())

程序运行结果：

total_elapsed_ms 2111
first_chunk_ms 2104
chunks 12
collected 1 2 3 4 5

结果说明：

首帧延迟 2104 ms，后续 11 帧只用了 7 ms 就到齐——一旦上游开始流，本地是顺手就能消费。
chunk 是普通 dict，按 OpenAI SSE 格式逐层 .get() 安全取值即可。
实际生产里推荐边 yield 边推 SSE 给前端，整体首字延迟接近 2 秒。

示例 3：AsyncAceDataCloud（异步）

AsyncAceDataCloud 的 API 跟同步版完全对称，只是所有 IO 方法返回 coroutine。适合 FastAPI / aiohttp / asyncio 服务。

import os, asyncio, time
from acedatacloud import AsyncAceDataCloud

async def main():
    client = AsyncAceDataCloud(api_token=os.environ["ACEDATACLOUD_API_KEY"])
    t0 = time.time()
    res = await client.openai.chat.completions.create(
        model="gpt-4o-mini",
        messages=[{"role": "user", "content": "Reply with exactly: ADC_PY_ASYNC_OK"}],
        max_tokens=20,
        temperature=0,
    )
    print("elapsed_ms", int((time.time() - t0) * 1000))
    print("id", res["id"])
    print("content", res["choices"][0]["message"]["content"])
    await client.close()

asyncio.run(main())

程序运行结果：

1
2
3

elapsed_ms 2392
id chatcmpl-DldFwRlrgtYDBpIr0T55aDQI4GlbF
content ADC_PY_ASYNC_OK

结果说明：

异步版本和同步版本走的是同一条 HTTP 路径，只是连接池实现不同（httpx.AsyncClient）。
退出时显式 await client.close() 把连接池关掉；长生命周期服务里只需要在进程退出前关一次。
单次延迟跟同步差不多，并发场景下异步才显出优势——一个 event loop 可以同时跑几十上百个 inflight 请求。

示例 4：images.generate（NanoBanana）

NanoBanana 是同步生成的图像服务，不要传 wait——SDK 调用就会一直阻塞到上游 200 返回。

import os, time
from acedatacloud import AceDataCloud

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

t0 = time.time()
res = client.images.generate(
    provider="nano-banana",
    model="nano-banana",
    prompt="A minimalist logo of a yellow banana on a white background, flat design",
)
print("elapsed_ms", int((time.time() - t0) * 1000))
print("task_id", res.get("task_id"))
print("trace_id", res.get("trace_id"))
data = res.get("data") or []
if data:
    print("image_url", data[0].get("image_url"))

程序运行结果：

elapsed_ms 18977
task_id 9e71f40f-1579-480d-adf4-07a95450904f
trace_id 5aa21d7f-af84-48e6-9ce0-9c6c36c8e5d9
image_url https://platform.cdn.acedata.cloud/nanobanana/884e92df-a497-44e0-9681-35c7a00e0a6c.png

结果说明：

image_url 是 CDN 上的稳定地址，可以直接下载或嵌入网页。
18.9 秒里几乎都是上游模型推理；本地 SDK 开销只有几毫秒。
对于 Midjourney、Sora、Veo、Suno 这种真正异步的任务，需要用 wait=True 或手动 TaskHandle.wait() 轮询，详见 SDK 任务轮询与流式响应。

示例 5：类型化错误处理

import os
from acedatacloud import AceDataCloud
from acedatacloud import AuthenticationError, RateLimitError, ValidationError

bad = AceDataCloud(api_token="definitely-not-a-real-token")

try:
    bad.openai.chat.completions.create(
        model="gpt-4o-mini",
        messages=[{"role": "user", "content": "hi"}],
        max_tokens=5,
    )
except AuthenticationError as err:
    print("err_class", type(err).__name__)
    print("status", err.status_code)
    print("code", err.code)
except RateLimitError as err:
    # 429，SDK 已经自动指数退避重试 2 次仍失败才会抛
    print("rate limited:", err.code)
except ValidationError as err:
    # 400，例如缺字段、模型名不存在
    print("bad request:", err.code, err.message)

异常层级跟 TypeScript 一致：AuthenticationError (401)、TokenMismatchError (token 与服务不匹配)、InsufficientBalanceError (余额不足)、ResourceDisabledError (服务被禁用)、ValidationError (400)、RateLimitError (429)、ModerationError (403 内容审核)、APIError (兜底)、TimeoutError（超时）、TransportError（网络层）。

配置选项

from acedatacloud import AceDataCloud

client = AceDataCloud(
    # 必填之一：显式 token 或环境变量 ACEDATACLOUD_API_TOKEN
    api_token="...",

    # 平台 API 根地址，默认 https://api.acedata.cloud
    base_url="https://api.acedata.cloud",

    # 部分服务（如 dashboard 元数据）走 platform 域名
    platform_base_url="https://platform.acedata.cloud",

    # 单次请求超时，秒；默认 300.0
    timeout=300.0,

    # 自动重试次数，默认 2；重试条件：408 / 409 / 429 / 5xx / 网络错误
    max_retries=2,

    # 自定义请求头
    headers={"x-app": "my-service/1.0"},
)

Python SDK 的 timeout 和 TaskHandle 的 poll_interval / max_wait 单位都是秒，TypeScript SDK 用的是毫秒，跨语言迁移时要特别注意。详见 SDK 任务轮询与流式响应。

SDK 默认读取 ACEDATACLOUD_API_TOKEN 环境变量；本文为了和 Claude Code VS Code 教程等其它教程统一，示例里用的是 ACEDATACLOUD_API_KEY，需要 api_token=os.environ["ACEDATACLOUD_API_KEY"] 显式注入。

进阶：X402 支付钩子

from acedatacloud import AceDataCloud
from acedatacloud_x402 import create_x402_payment_handler

client = AceDataCloud(
    payment_handler=create_x402_payment_handler(
        network="base",
        evm_signer=my_evm_signer,
        prefer_scheme="exact",   # 或 "upto"
    )
)

完整流程和真实链上结果见 SDK + X402 支付钩子。

如何查看剩余额度

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

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

了解更多

作者崔庆才发表于 2026-06-11 阅读次数：本文字数： 6.9k 阅读时长 ≈ 6 分钟

API 开发教程 OpenAI Images Generations API 申请及使用

OpenAI Images Generations API 目前支持多种图像生成模型，包括经典的 dall-e-3、文字渲染能力更强的 gpt-image-1、最新一代的 gpt-image-2，以及通过同一接口接入的 nano-banana / nano-banana-2 / nano-banana-pro 系列模型。它们都能根据文本描述生成高质量的图像。

本文档主要介绍 OpenAI Images Generations API 操作的使用流程，利用它我们可以轻松使用 OpenAI 系列的图像生成功能。

申请流程

要使用 OpenAI Images Generations API，首先可以到 OpenAI Images Generations API 页面点击「Acquire」按钮，获取请求所需要的凭证：

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

在首次申请时会有免费额度赠送，可以免费使用该 API。

GPT-Image-2 模型

gpt-image-2 是 OpenAI 推出的新一代图像生成模型，相比 dall-e-3 和 gpt-image-1，在以下方面有明显提升：

指令遵循能力更强：能够准确理解复杂构图、计数、位置关系等结构化指令。
文字渲染更清晰：海报、菜单、信息图、标志等场景下的英文与数字几乎不会出现错乱。
风格表现更丰富：原生支持电影感人像、复古海报、儿童插画、产品摄影、信息图等多种风格。
原生多比例 + 高分辨率支持：覆盖 5 种比例（1:1、4:3、3:4、16:9、9:16）共 3 档分辨率（1K / 2K / 4K）。

调用方式与其它模型完全一致，只需将 model 字段设置为 gpt-image-2 即可。返回结果中的 url 是一个永久托管在 platform.cdn.acedata.cloud 上的图片链接，可以直接在浏览器中打开或嵌入到网页中。

支持的 `size` 取值

gpt-image-2 只检查 size 的格式，只要不是 auto 或空串，就需要匹配 WIDTHxHEIGHT（例如 1024x1024、2048x1152、800x600）；任何其他形态会返回 400。所有尺寸（1K / 2K / 4K / 自定义）按单张统一扣费，不按尺寸加价。

上游对自定义尺寸的硬约束：宽高均为 16 的倍数、长边 ≤ 3840、总像素数 ≤ 8,294,400。超出范围会被上游拒绝并以 4xx 返回。

比例	1K 推荐	2K 推荐	4K 推荐
1:1	`1024x1024`	`2048x2048`	`2880x2880`
4:3	`1536x1024`	`2048x1536`	`3264x2448`
3:4	`1024x1536`	`1536x2048`	`2448x3264`
16:9	`1792x1024`	`2048x1152`	`3840x2160`
9:16	`1024x1792`	`1152x2048`	`2160x3840`

你也可以传 size: "auto" 或者省略 size 字段，此时由模型自行选择默认尺寸。

1K 档下上游输出不保证严格像素对齐——你传 1024x1024 可能拿到 1254x1254，比例保持一致。如果你重新把它当作 size 传进来，计费不变。

4K 单次调用通常需要 4–8 分钟，建议配合后文的 callback_url 异步回调使用。

关于 n 参数

gpt-image-2 目前不支持 n > 1：该参数会被静默忽略，无论传 n=1 还是 n=10，单次请求都只会返回 1 张图，并且只按 1 张计费。如果你需要一次拿到多张候选图，请自行并发发起多次请求（建议同时传不同的 prompt 或不同的 seed，否则得到的几张图可能高度相似）。该限制同样适用于 gpt-image-1 / gpt-image-1.5，以及 nano-banana / nano-banana-2 / nano-banana-pro 系列。dall-e-2 是目前唯一原生支持 n > 1 的模型；dall-e-3 仅支持 n = 1。

下面通过几个不同方位的真实示例来直观感受 gpt-image-2 的能力。

场景一：电影感人像

提示词中可以使用电影术语（35mm 胶片、浅景深、霓虹光等）来精准控制氛围与质感。

Python 样例调用代码：

import requests

url = "https://api.acedata.cloud/openai/images/generations"

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

payload = {
    "model": "gpt-image-2",
    "prompt": "A cinematic portrait of a young woman standing in a convenience store at night, illuminated by soft pink and cyan neon signs through the window. Shot on 35mm film, shallow depth of field, slight grain, melancholic mood.",
    "size": "1024x1536"
}

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

返回结果如下：

{
  "success": true,
  "task_id": "ab58a5df-6f46-4874-bff6-93169e2849a3",
  "created": 1777048800,
  "data": [
    {
      "revised_prompt": "A cinematic portrait of a young woman standing in a convenience store at night, illuminated by soft pink and cyan neon signs through the window. Shot on 35mm film, shallow depth of field, slight grain, melancholic mood.",
      "url": "https://platform.cdn.acedata.cloud/gpt-image/ab58a5df-6f46-4874-bff6-93169e2849a3_0.png"
    }
  ]
}

生成的图片如下所示：

场景二：复古旅行海报（带文字渲染）

gpt-image-2 在排版与字体渲染方面表现稳定，非常适合用来生成海报、菜单、贺卡等带文字的设计稿。

payload = {
    "model": "gpt-image-2",
    "prompt": "A vintage travel poster of the Amalfi Coast, Italy. Stylized art-deco illustration of cliffside lemon-yellow houses cascading down to a turquoise sea, with a small white sailboat in the harbor. Bold typography at the top reads AMALFI and at the bottom ITALIA 1958. Limited color palette: cream, sea-blue, lemon yellow, terracotta. Slight paper-grain texture.",
    "size": "1024x1536"
}

返回结果中的 url 字段对应的图片如下：

可以看到模型不仅准确还原了 Art Deco 海报的视觉风格，标题文字 AMALFI 与 ITALIA 1958 都被清晰、正确地渲染出来。

场景三：复杂构图与计数

下面这个提示词用来测试模型对“数量”和“位置”等结构化指令的遵循能力。

payload = {
    "model": "gpt-image-2",
    "prompt": "A wooden bookshelf consisting of three shelves: On the top shelf, there should be one book. On the second shelf, there should be three books. On the bottom shelf, there should be seven books. Soft warm lighting, photorealistic, cozy library atmosphere.",
    "size": "1024x1024"
}

生成的图片如下：

可以看到三层书架上的书本数量（1 / 3 / 7）与提示词完全一致，这是 dall-e-3 时代很难稳定做到的。

场景四：插画风格（横屏）

通过指定艺术媒介与情绪关键词，可以引导模型产出风格化的插画。

payload = {
    "model": "gpt-image-2",
    "prompt": "A soft, poetic children's book illustration of a small fox reading a book under a glowing mushroom in a moonlit forest. Watercolor and pencil texture, gentle pastel colors, dreamy atmosphere, hand-drawn feel.",
    "size": "1536x1024"
}

生成的横屏插画如下：

异步与回调

gpt-image-2 单次调用通常需要 60～90 秒，如果不希望保持长连接，可以使用本文后续介绍的 callback_url 异步回调机制，调用流程与其它模型完全一致。

Nano Banana 系列模型

nano-banana 系列是基于 Gemini 的图像生成模型，已通过同一个 /openai/images/generations 接口接入，无需切换 endpoint，只要把 model 改为下表中的任意一个即可。

模型	计费（Credits / 次）	适用场景
`nano-banana`	0.14	普通图像生成，速度最快、成本最低
`nano-banana-2`	0.28	质量与细节明显提升
`nano-banana-pro`	0.35	系列中的旗舰，构图、细节、文字均最佳

重要：参数支持范围

Nano Banana 通过适配层接入 OpenAI 协议，与 gpt-image-* 相比仅支持以下参数：model、prompt、size。

size 会按下表映射为内部 aspect_ratio，未列出的尺寸会退化为 1:1：

1024x1024 / 512x512 / 256x256 → 1:1

1792x1024 → 16:9

1024x1792 → 9:16

不支持 n、quality、style、response_format、background、output_format 等参数；填了也会被忽略。

返回结构遵循 OpenAI 格式（data[].url），但 created 固定为 0，且不会返回 b64_json，revised_prompt 始终等于原始 prompt。

基本调用

import requests

url = "https://api.acedata.cloud/openai/images/generations"

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

payload = {
    "model": "nano-banana",
    "prompt": "a small red apple on a white table, photoreal",
    "size": "1024x1024"
}

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

返回结果如下：

{
  "created": 0,
  "data": [
    {
      "url": "https://platform.cdn.acedata.cloud/nanobanana/6870b330-65c4-436c-bb80-819fdae7a7a4.png",
      "revised_prompt": "a small red apple on a white table, photoreal"
    }
  ]
}

生成的图片可以直接通过返回的 url 字段访问：

升级到旗舰模型 `nano-banana-pro`

只需把 model 改为 nano-banana-pro，其余参数完全一致：

payload = {
    "model": "nano-banana-pro",
    "prompt": "abstract painting",
    "size": "1024x1024"
}

返回示例：

{
  "created": 0,
  "data": [
    {
      "url": "https://platform.cdn.acedata.cloud/nanobanana/6227fcc9-3442-4aa3-a76c-4a4441a99649.png",
      "revised_prompt": "abstract painting"
    }
  ]
}

异步回调

callback_url 异步回调机制对 nano-banana 同样有效，调用流程与其它模型完全一致，详见下文异步回调一节。

基本使用

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

在第一次使用该接口时，我们至少需要填写三个内容，一个是 authorization，直接在下拉列表里面选择即可。另一个参数是 model， model 就是我们选择使用 OpenAI DALL-E 官网模型类别，这里我们主要有 1 种模型，详情可以看我们提供的模型。最后一个参数是prompt，prompt 是我们输入要生成图像的提示词。

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

Python 样例调用代码：

import requests

url = "https://api.acedata.cloud/openai/images/generations"

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

payload = {
    "model": "dall-e-3",
    "prompt": "A cute baby sea otter"
}

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

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

{
  "created": 1721626477,
  "data": [
    {
      "revised_prompt": "A delightful image showcasing a young sea otter, who is born brown, with wide charming eyes. It is delightfully lying on its back, paddling in the calm sea waters. Its dense, velvety fur appears wet and shimmering, capturing the essence of its habitat. The small creature curiously plays with a sea shell with its small paws, looking absolutely innocent and charming in its natural environment.",
      "url": "https://dalleprodsec.blob.core.windows.net/private/images/5d98aa7c-80c6-4523-b571-fc606ad455b9/generated_00.png?se=2024-07-23T05%3A34%3A48Z&sig=GAz%2Bi3%2BkHOQwAMhxcv22tBM%2FaexrxPgT9V0DbNrL4ik%3D&ske=2024-07-23T08%3A41%3A10Z&skoid=e52d5ed7-0657-4f62-bc12-7e5dbb260a96&sks=b&skt=2024-07-16T08%3A41%3A10Z&sktid=33e01921-4d64-4f8c-a055-5bdaffd5e33d&skv=2020-10-02&sp=r&spr=https&sr=b&sv=2020-10-02"
    }
  ]
}

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

created，生成此次图像生成的 ID，用于唯一标识此次任务。
data，包含图像生成的结果信息。

其中 data 是包含了模型生成图片的具体信息，它里面的 url 是生成图片的详情链接，可以发现如图所示。

图片质量参数 `quality`

接下来将介绍如何设置图像生成结果的一些详细参数，其中图片质量参数 quality 包含俩种，第一个 standard 表示生成标准的图片，另一个 hd 表示创建的图像具有更精细的细节和更大的一致性。

下面设置图片质量参数为 standard ，具体设置如下图：

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

Python 样例调用代码：

import requests

url = "https://api.acedata.cloud/openai/images/generations"

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

payload = {
    "model": "dall-e-3",
    "prompt": "A cute baby sea otter",
    "quality": "standard"
}

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

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

{
  "created": 1721636023,
  "data": [
    {
      "revised_prompt": "A cute baby sea otter is lying playfully on its back in the water, with its fur looking glossy and soft. One of its tiny paws is reaching out curiously, and it has an expression of pure joy and warmth on its face as it looks up to the sky. Its body is surrounded by bubbles from its playful twirling in the water. A gentle breeze is playing with its fur making it look more charming. The scene portrays the tranquility and charm of marine life.",
      "url": "https://dalleprodsec.blob.core.windows.net/private/images/a93ee5e7-3abd-4923-8d79-dc9ef126da46/generated_00.png?se=2024-07-23T08%3A13%3A55Z&sig=wTXGYvUOwUIkaB2CxjK9ww%2FHjS8OwYUWcYInXYKwcAM%3D&ske=2024-07-23T11%3A32%3A05Z&skoid=e52d5ed7-0657-4f62-bc12-7e5dbb260a96&sks=b&skt=2024-07-16T11%3A32%3A05Z&sktid=33e01921-4d64-4f8c-a055-5bdaffd5e33d&skv=2020-10-02&sp=r&spr=https&sr=b&sv=2020-10-02"
    }
  ]
}

返回的结果与基本使用的内容一致，可以看到图片质量参数为 standard 的生成图片如下图所示：

与上述相同操作，仅需将图片质量参数设置为 hd ，可以得到如下图所示的图片：

可以看到 hd 比 standard 生成的图片具有更精细的细节和更大的一致性。

图片大小尺寸参数 `size`

我们还可以设置生成图片的尺寸大小，我们可以进行下面的设置。

下面设置图片的尺寸大小为 1024 * 1024 ，具体设置如下图：

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

Python 样例调用代码：

import requests

url = "https://api.acedata.cloud/openai/images/generations"

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

payload = {
    "model": "dall-e-3",
    "prompt": "A cute baby sea otter"
    "size": "1024x1024"
}

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

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

{
  "created": 1721636652,
  "data": [
    {
      "revised_prompt": "A delightful depiction of a baby sea otter. The small mammal is captured in its natural habitat in the ocean, floating on its back. It has thick brown fur that is sleek and wet from the sea water. Its eyes are closed as if it is enjoying a moment of deep relaxation. The water around it is calm, reflecting the peacefulness of the scene. The background should hint at a diverse marine ecosystem, with visible strands of kelp floating on the surface, suggesting the baby otter's preferred environment.",
      "url": "https://dalleprodsec.blob.core.windows.net/private/images/9d625ac6-fd2b-42a9-84a6-8c99eb357ccf/generated_00.png?se=2024-07-23T08%3A24%3A24Z&sig=AXtYXowEakGxfRp8LhC2DwqL%2F07LhEDW40oCP%2BdTO8s%3D&ske=2024-07-23T18%3A00%3A45Z&skoid=e52d5ed7-0657-4f62-bc12-7e5dbb260a96&sks=b&skt=2024-07-16T18%3A00%3A45Z&sktid=33e01921-4d64-4f8c-a055-5bdaffd5e33d&skv=2020-10-02&sp=r&spr=https&sr=b&sv=2020-10-02"
    }
  ]
}

返回的结果与基本使用的内容一致，可以看到图片的尺寸大小为 1024 * 1024 的生成图片如下图所示：

与上述相同操作，仅需将图片的尺寸大小为 1792 * 1024 ，可以得到如下图所示的图片：

可以看到图片的尺寸大小很明显不一样，另外还可以设置更多尺寸大小，详情信息参考我们官网文档。

图片风格参数 `style`

图片风格参数 style 包含俩个参数，第一种 vivid 表示生成的图片是更加生动的，另一种 natural 表示生成的图片更加的自然一点。

下面设置图片风格参数为 vivid ，具体设置如下图：

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

Python 样例调用代码：

import requests

url = "https://api.acedata.cloud/openai/images/generations"

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

payload = {
    "model": "dall-e-3",
    "prompt": "A cute baby sea otter",
    "style": "vivid"
}

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

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

{
  "created": 1721637086,
  "data": [
    {
      "revised_prompt": "A baby sea otter with soft, shiny fur and sparkling eyes floating playfully on calm ocean waters. This adorable creature is trippingly frolicking amidst small, gentle waves under a bright, clear, sunny sky. The tranquility of the sea contrasts subtly with the delightful energy of this young otter. The critter gamely clings to a tiny piece of driftwood, its small paws adorably enveloping the floating object.",
      "url": "https://dalleprodsec.blob.core.windows.net/private/images/6e48f701-7fd3-4356-839e-a2f6f0fe82d9/generated_00.png?se=2024-07-23T08%3A31%3A37Z&sig=4percxqTbUR1j3BQmkhvj%2FAhHzInKI%2FqiTo1MP69coI%3D&ske=2024-07-27T10%3A39%3A55Z&skoid=e52d5ed7-0657-4f62-bc12-7e5dbb260a96&sks=b&skt=2024-07-20T10%3A39%3A55Z&sktid=33e01921-4d64-4f8c-a055-5bdaffd5e33d&skv=2020-10-02&sp=r&spr=https&sr=b&sv=2020-10-02"
    }
  ]
}

返回的结果与基本使用的内容一致，可以看到图片风格参数为 vivid 的生成图片如下图所示：

与上述相同操作，仅需将图片风格参数为 natural ，可以得到如下图所示的图片：

可以看到 vivid 比 natural 生成的图片具有更加生动逼真。

图片链接的格式参数 `response_format`

最后一个图片链接的格式参数 response_format 也有俩种，第一种 b64_json 是对图片链接进行 Base64 编码，另一种 url 就是普通的图片链接，可以直接查看图片。

下面设置图片链接的格式参数为 url ，具体设置如下图：

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

Python 样例调用代码：

import requests

url = "https://api.acedata.cloud/openai/images/generations"

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

payload = {
    "model": "dall-e-3",
    "prompt": "A cute baby sea otter",
    "response_format": "url"
}

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

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

{
  "created": 1721637575,
  "data": [
    {
      "revised_prompt": "A charming depiction of a baby sea otter. The otter is seen resting serenely on its back amidst the gentle, blue ocean waves. The baby otter's fur is an endearing mix of soft greyish brown shades, glinting subtly in the muted sunlight. Its small paws are touching, lifted slightly towards the sky as if playing with an unseen object. Its round, expressive eyes are wide in curiosity, sparking with life and innocence. Use a realistic style to evoke the otter's natural habitat and its adorably fluffy exterior.",
      "url": "https://dalleprodsec.blob.core.windows.net/private/images/87792c5f-8b6d-412e-81dd-f1a1baa19bd2/generated_00.png?se=2024-07-23T08%3A39%3A47Z&sig=zzRAn30TqIKHdLVqZPUUuSJdjCYpoJdaGU6BeoA76Jo%3D&ske=2024-07-23T13%3A32%3A13Z&skoid=e52d5ed7-0657-4f62-bc12-7e5dbb260a96&sks=b&skt=2024-07-16T13%3A32%3A13Z&sktid=33e01921-4d64-4f8c-a055-5bdaffd5e33d&skv=2020-10-02&sp=r&spr=https&sr=b&sv=2020-10-02"
    }
  ]
}

返回的结果与基本使用的内容一致，可以看到图片链接的格式参数为 url 的生成图片的链接为图片 URL 这是可以直接访问的，图片内容如下图所示：

与上述相同操作，仅需将图片链接的格式参数为 b64_json ，可以得到结果 Base64 编码后的图片链接，具体结果如下图所示：

{
  "created": 1721638071,
  "data": [
    {
      "b64_json": "iVBORw0..............v//AQEAAP4AAAD+AAADAQAAAwEEA/4D//8Q/Pbw64mKbVTFoQAAAABJRU5ErkJggg==",
      "revised_prompt": "A charming image of a young baby sea otter. The otter is gently floating on a calm blue sea, basking in the warm, golden rays of sunlight streaming down from a clear sky above. The otter's fur is a rich chocolate brown, and it looks incredibly soft and fluffy. The otter's eyes are bright and expressive, filled with childlike curiosity and joy. It has small, pricked ears and a button-like nose which adds to its overall cuteness. In the sea around it, twinkling droplets of water can be seen, pepped up by the sunlight, the sight is certainly a delightful one."
    }
  ]
}

异步回调

由于 OpenAI Images Generations API 生成图片的时间可能相对较长，如果 API 长时间无响应，HTTP 请求会一直保持连接，导致额外的系统资源消耗，所以本 API 也提供了异步回调的支持。

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

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

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

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

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

import requests

url = "https://api.acedata.cloud/openai/images/generations"

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

payload = {
    "model": "dall-e-3",
    "prompt": "A cute baby sea otter",
    "callback_url": "https://webhook.site/3d32690d-6780-4187-a65c-870061e8c8ab"
}

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

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

1
2
3

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

稍等片刻，我们可以在 Webhook URL 上观察到生成图片的结果，内容如下：

{
  "success": true,
  "task_id": "6a97bf49-df50-4129-9e46-119aa9fca73c",
  "trace_id": "9b4b1ff3-90f2-470f-b082-1061ec2948cc",
  "data": {
    "created": 1721626477,
    "data": [
      {
        "revised_prompt": "A delightful image showcasing a young sea otter...",
        "url": "https://dalleprodsec.blob.core.windows.net/private/images/..."
      }
    ]
  }
}

可以看到结果中有一个 task_id 字段，data 字段包含了和同步调用一样的图片生成结果，通过 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.

错误响应示例

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

结论

通过本文档，您已经了解了如何使用 OpenAI Images Generations API 轻松使用官方 OpenAI DALL-E 的图像生成功能。希望本文档能帮助您更好地对接和使用该 API。如有任何问题，请随时联系我们的技术支持团队。

作者崔庆才发表于 2026-06-11 阅读次数：本文字数： 16k 阅读时长 ≈ 15 分钟

API 开发教程 连接器（Connector）使用教程

连接器（Connector）是 AceData Cloud / Nexior 平台为 AI 助手提供的「外部能力总线」。它把 GitHub、Google Drive、Notion、Slack、Linear 等 Web 应用，以及社区里所有遵循 MCP（Model Context Protocol）的工具，统一收编到对话窗口里 —— 你不需要切换页面，就能让模型读你的 PR、查日历、写 Issue、跑数据库查询。

谁会用到：使用 Nexior / Studio 等基于平台的对话产品的最终用户；以及希望在自己的 Subsite 中预集成第三方工具的站长。

接入入口：登录 studio.acedata.cloud → 顶部「Connector」标签。

三种连接器

类型	来源	配置方式	典型例子
Web Connector	平台预置 OAuth	一键 OAuth 授权	GitHub、Google Drive、Notion、Linear、Atlassian
Built-in MCP	平台托管的 MCP Server	一键开启，无需密钥	Suno、Sora、Veo、Flux、Midjourney、Nano-Banana、SERP
Custom MCP	你自己的 MCP 服务器	手动填 URL + 认证头	公司内网工具、Self-hosted MCP

5 分钟实操

第 1 步：进入 Connector 中心

登录 Studio 后，点击顶部导航 Connector。左侧会按状态分组：Web / Built-in / Custom / Not Connected。

第 2 步：连接 GitHub（Web Connector 示例）

在「Not Connected」分组中找到 GitHub 卡片，点击它；
右侧详情面板出现 Connect 按钮，点击；
浏览器弹窗跳转到 GitHub OAuth 同意页，确认授权；
回到 Studio 后，卡片移动到「Web」分组，状态变为 Connected。

第 3 步：调整工具权限

点击已连接的卡片，向下滚动到「Tool Permissions」：

Read-Only Tools（只读工具，例如 list_issues / get_pull_request）：默认允许；
Write Tools（写入工具，例如 create_issue / merge_pr）：默认每次询问；
你也可以为单个工具切换 Always allow / Always ask / Never use。

第 4 步：在对话中使用

回到任意聊天，输入：

1	帮我看一下 acedatacloud/Nexior 上 main 分支最近 10 个 PR 的标题和合入状态。

模型会自动调用 GitHub Connector 暴露的 list_pull_requests 工具，把结果格式化后发回给你。

添加自定义 MCP Server

如果你已经有一个对外暴露的 MCP HTTP Server（例如公司内部的数据库代理），可以这样接入：

Connector 页右上角 Add → Add Custom Connector；
填写：
- Name：Internal DB
- Endpoint URL：https://mcp.example.com/mcp
- Headers：Authorization: Bearer xxx（如有）；
保存后，平台会拉一次 tools/list，把扫描到的工具罗列在权限面板里。

协议要求：自定义 Connector 必须遵循 MCP HTTP/SSE 规范。直接的纯 REST API 暂不支持，请考虑用 MCPs 仓库里的脚手架包一层。

常见问题

Q：Connector 授权后立即显示 Coming Soon？
A：表示该提供商的 OAuth 应用本站点还未配置。请联系站点管理员（白标场景）或换用 studio.acedata.cloud 主站，主站已为常用 OAuth 全部开通。

Q：Built-in 和 Custom 有什么区别？
A：Built-in 由平台运行（你只用为模型 Token 付费），Custom 由你自己运行（消耗你自己的服务器资源 + 凭证）。两者对模型来说都是普通工具调用。

Q：能在 API 里使用 Connector 吗？
A：能。/openai/chat/completions 接口支持 tools 字段，平台会把已连接的 Connector 自动注入；详见 OpenAI Chat Completions 工具调用章节。

API 开发教程 获取 AceDataCloud 平台服务申请详情

通过 Application ID 获取单个服务申请的完整状态——比列表接口多出 service 完整对象（含 packages 套餐）、credentials_count 等字段，适用于详情页。

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

接口概览

项	内容
方法	`GET`
URL	`https://platform.acedata.cloud/api/v1/applications/{application_id}`
鉴权	✅ 需要账户令牌

⚠️ URL 不要带尾部斜杠——/applications/{id} 不是 /applications/{id}/。

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

请求头：

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

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

ℹ️ 与列表接口不同，详情接口的权限校验是直接对单一对象做，无需传 ?user_id=。但你访问别人的申请会得到 403 permission_denied。

路径参数

参数	类型	必填	说明
`application_id`	UUID	✅	Application ID

请求示例

cURL

1
2
3

curl 'https://platform.acedata.cloud/api/v1/applications/82f57141-2323-4453-8730-60f7d833a2da' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer platform-v1-92eb****629c'

Python

import requests

app_id = "82f57141-2323-4453-8730-60f7d833a2da"
resp = requests.get(
    f"https://platform.acedata.cloud/api/v1/applications/{app_id}",
    headers={
        "accept": "application/json",
        "authorization": "Bearer platform-v1-92eb****629c",
    },
    timeout=10,
)
app = resp.json()
print(f"服务：{app['service']['title']}")
print(f"剩余 {app['remaining_amount']} {app['service']['unit']} / 已用 {app['used_amount']}")
print(f"已发凭证数：{app.get('credentials_count', 0)}")

Node.js

const appId = '82f57141-2323-4453-8730-60f7d833a2da'
const r = await fetch(`https://platform.acedata.cloud/api/v1/applications/${appId}`, {
  headers: { authorization: 'Bearer platform-v1-92eb****629c' },
})
console.log(await r.json())

响应示例（HTTP 200）

{
  "id": "82f57141-2323-4453-8730-60f7d833a2da",
  "service_id": "38ecf158-36f2-42f2-8e7f-6786cdfc2452",
  "remaining_amount": 100.0,
  "used_amount": 12.34,
  "paid": true,
  "user_id": "89518d07-5560-4b05-92c1-667f3ddf6a4b",
  "disabled": false,
  "allow_consume_global": false,
  "scope": "Individual",
  "type": "Usage",
  "expired_at": null,
  "tags": null,
  "metadata": null,
  "credentials_count": 3,
  "service": {
    "id": "38ecf158-36f2-42f2-8e7f-6786cdfc2452",
    "alias": "openai",
    "title": "OpenAI",
    "type": "Api",
    "unit": "Credit",
    "free_amount": 1.0,
    "packages": [
      { "id": "...", "type": "Usage", "price": 10.0, "amount": 100.0 }
    ]
  },
  "created_at": "2026-04-26T07:52:27.462400Z",
  "updated_at": "2026-04-26T08:42:13.123456Z"
}

响应字段说明

字段含义同列表接口，额外包含：

字段	类型	说明
`credentials_count`	integer	该 Application 当前已签发的 API 凭证数量
`service`	object	完整的服务对象（含 `packages` 套餐、`unit`、`free_amount`），可直接渲染服务详情面板

错误处理

HTTP	code	含义
401	`not_authenticated`	缺少账户令牌
403	`permission_denied`	该 Application 不属于你
404	`not_found`	Application 不存在或已删除
500	—	URL 末尾误加斜杠，去掉后重试

实用提示

详情接口比列表更贵：会跑额外的关联查询。如果只是周期性余额监控，应该用列表接口配合 ?low_balance=true。
credentials_count=0 是正常的：刚申请完还没创建凭证。这时跳创建 AceDataCloud 平台 API 凭证即可。
disabled=true 排查思路：检查工单 / 邮件通知，看是否因风控、欠费、违规调用被关停；不能通过 API 解除，必须联系客服。

产品推广 JetBrains 对接 Luma MCP

📘 完整指南：在 JetBrains（IntelliJ IDEA / PyCharm / WebStorm 等）里用全部 11 个 AceData Cloud MCP →

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

获取 API Token

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

配置

编辑配置：Junie 或 Claude 插件设置 → MCP Servers → Add Server

Name: luma
Type: HTTP (Streamable)
URL: https://luma.mcp.acedata.cloud/mcp
Headers:
  Authorization = Bearer 你的Token

保存后在 Junie / Claude 插件的工具栏即可看到工具。

使用示例

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

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

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

工具

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

产品推广 Gemini CLI 对接 Hailuo (MiniMax) MCP

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

MiniMax 海螺是文生视频 / 图生视频模型，支持 Director Mode 精确控制运镜。通过 MCP 接入 Gemini CLI 后，可以直接在对话里调用，不用切窗口、不用复制粘贴。

获取 API Token

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

配置

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

gemini mcp add hailuo \
  --type http \
  --url https://hailuo.mcp.acedata.cloud/mcp \
  --header "Authorization: Bearer 你的Token"

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

{
  "mcpServers": {
    "hailuo": {
      "httpUrl": "https://hailuo.mcp.acedata.cloud/mcp",
      "headers": { "Authorization": "Bearer 你的Token" }
    }
  }
}

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

使用示例

用 hailuo-02 生成 6 秒视频：傍晚的山间小路，雾气漫过来，镜头慢慢推进

用 hailuo-01-director 生成视频：[拉镜头]一个咖啡馆的桌面特写转到[摇镜头]整个店内

用这张图（链接 xxx）做 image2video，让画面里的鸟从树枝飞起

工具

工具	说明
hailuo_generate_video	通过文本或图片生成视频（hailuo-02 / hailuo-02-pro / hailuo-01-director / hailuo-01-live）

API 开发教程 Midjourney Imagine API 申请及使用

Midjourney 是一款非常强大的 AI 绘图工具，只要输入关键字，就能在短短一两分钟生成十分精美的图像。Midjourney 以其出色的绘图能力在业界独树一帜，如今，Midjourney 早已在各个行业和领域广泛应用，其影响力愈发显著。

本文档主要介绍 Midjourney API 中 Imagine 操作的使用流程，利用它我们可以轻松通过文本生成所需要的图像。

申请流程

要使用 Midjourney Imagine API，首先可以到 Midjourney Imagine API 页面点击「Acquire」按钮，获取请求所需要的凭证：

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

在首次申请时会有免费额度赠送，可以免费使用该 API。

基本使用

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

在第一次使用该接口时，我们至少需要填写两个内容，一个是 authorization，直接在下拉列表里面选择即可。另一个参数是 prompt， prompt 就是我们想生成的图片描述内容，建议用英文描述，画的图会更准确效果更好，这里我们用了示例内容 Lamborghini speeds inside a volcano，代表要画一个兰博基尼在火山飞驰。

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

主要请求参数：

prompt：图片描述词（支持自动翻译）。
mode：生成模式，可选 fast/relax/turbo，默认 fast。
timeout：超时时间（秒），超时会直接返回。
translation：是否自动翻译非英文 prompt。
split_images：是否将 2x2 结果拆分返回单张。
action/image_id：对历史图片继续操作时需指定。
callback_url：异步回调地址。

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

{
  "image_url": "https://midjourney.cdn.acedata.cloud/attachments/1233387694839697411/1234197197067915365/36rgqit64j90qptsxnyq_Lamborghini_speeds_inside_a_volcano_id0494_f47263b6-ff92-44a3-88ee-51cf0e706aae.png?ex=662fdb36&is=662e89b6&hm=ca9be54907726937ed02517a13466bef2afb2825b7cda4b313de56a3c3310d0d&width=1024&height=1024",
  "image_width": 1024,
  "image_height": 1024,
  "image_id": "1234197197067915365",
  "raw_image_url": "https://midjourney.cdn.acedata.cloud/attachments/1233387694839697411/1234197197067915365/36rgqit64j90qptsxnyq_Lamborghini_speeds_inside_a_volcano_id0494_f47263b6-ff92-44a3-88ee-51cf0e706aae.png?ex=662fdb36&is=662e89b6&hm=ca9be54907726937ed02517a13466bef2afb2825b7cda4b313de56a3c3310d0d&",
  "raw_image_width": 2048,
  "raw_image_height": 2048,
  "progress": 100,
  "actions": [
    "upscale1",
    "upscale2",
    "upscale3",
    "upscale4",
    "reroll",
    "variation1",
    "variation2",
    "variation3",
    "variation4"
  ],
  "task_id": "1bae3bec-3ac4-4180-a148-74ee6cb68b98",
  "success": true
}

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

task_id，生成此图像任务的 ID，用于唯一标识此次图像生成任务。
image_id，图片的唯一标识，在下次需要对图片进行变换操作时需要传此参数。
image_url，缩略图的 URL，直接打开即可查看生成的效果。
image_width：缩略图的像素宽度。
image_height：缩略图的像素高度。
raw_image_url：原图的 URL，和缩略图内容一样，但相比缩略图更加高清，加载速度会更慢一些。
raw_image_width：原图的像素宽度。
raw_image_height：原图的像素高度。
actions，可以对生成的图片进行的进一步操作列表。这里一共列了 8 个，其中 upscale 代表放大，variation 代表变换。所以 upscale1 代表的就是对左上角第一张图片进行放大操作，variation3 就是代表根据左下角第三张图片进行变换操作。

打开 image_url 或者 raw_image_url 所对应的链接，可以发现如图所示。

可以看到，这里生成了一张 2x2 的预览图。到现在为止，第一次 API 调用就完成了。

图像放大与变换

下面我们尝试针对当前生成的照片进行进一步的操作，比如我们觉得右上角第二张的图片还不错，但我们想进行一些变换微调，那么就可以进一步将 action 填写为 variation2，同时将 image_id 传递即可：

这时候得到的结果如下：

{
  "image_url": "https://midjourney.cdn.acedata.cloud/attachments/1233387694839697411/1234201336543969401/36rgqit64j90qptsxnyq_Lamborghini_speeds_inside_a_volcano_id0494_10dc56a7-ec16-4bac-878e-2338f2ae5f5d.png?ex=662fdf10&is=662e8d90&hm=9aec96bca35ae20b6f9ab536101b9c4ea255eb6216cbf7000ac554937da071f3&width=1024&height=1024",
  "image_width": 1024,
  "image_height": 1024,
  "image_id": "1234201336543969401",
  "raw_image_url": "https://midjourney.cdn.acedata.cloud/attachments/1233387694839697411/1234201336543969401/36rgqit64j90qptsxnyq_Lamborghini_speeds_inside_a_volcano_id0494_10dc56a7-ec16-4bac-878e-2338f2ae5f5d.png?ex=662fdf10&is=662e8d90&hm=9aec96bca35ae20b6f9ab536101b9c4ea255eb6216cbf7000ac554937da071f3&",
  "raw_image_width": 2048,
  "raw_image_height": 2048,
  "progress": 100,
  "actions": [
    "upscale1",
    "upscale2",
    "upscale3",
    "upscale4",
    "reroll",
    "variation1",
    "variation2",
    "variation3",
    "variation4"
  ],
  "task_id": "f4961620-1104-409f-9dc1-ba3ed15c2f4d",
  "success": true
}

打开 image_url，新生成的图片如下所示：

可以看到，针对上一张右上角的图片，我们再次得到了四张类似的照片。

这时候我们可以挑选其中一张进行精细化地放大操作，比如选第四张，那就可以 action 传入 upscale4，通过 image_id 再次传入当前图像的 ID 即可。

注意： upscale 操作相比 variation 来说，Midjourney 的耗时会更短一些。

返回结果如下：

{
  "image_url": "https://midjourney.cdn.acedata.cloud/attachments/1233387694839697411/1234202545208033400/36rgqit64j90qptsxnyq_Lamborghini_speeds_inside_a_volcano_id0494_34edc3f5-2bd0-4f5b-a372-03270b02289b.png?ex=662fe031&is=662e8eb1&hm=f8006c4d33a03dfd027dffe4eb46ab0d113a4910aef07497f0b335c8998b7858&width=512&height=512",
  "image_width": 512,
  "image_height": 512,
  "image_id": "1234202545208033400",
  "raw_image_url": "https://midjourney.cdn.acedata.cloud/attachments/1233387694839697411/1234202545208033400/36rgqit64j90qptsxnyq_Lamborghini_speeds_inside_a_volcano_id0494_34edc3f5-2bd0-4f5b-a372-03270b02289b.png?ex=662fe031&is=662e8eb1&hm=f8006c4d33a03dfd027dffe4eb46ab0d113a4910aef07497f0b335c8998b7858&",
  "raw_image_width": 1024,
  "raw_image_height": 1024,
  "progress": 100,
  "actions": [
    "upscale_2x",
    "upscale_4x",
    "variation_subtle",
    "variation_strong",
    "zoom_out_2x",
    "zoom_out_1_5x",
    "pan_left",
    "pan_right",
    "pan_up",
    "pan_down"
  ],
  "task_id": "03f62b17-a6f1-4c8e-9b4d-1fc7bd5b1180",
  "success": true
}

其中 image_url 如图所示：

这样我们就成功得到了一张兰博基尼的照片。

同时注意到 actions 里面又包含了几个可进行的操作，介绍如下：

upscale_2x：对画面放大 2 倍，得到 2 倍高清图。
upscale_4x：对画面放大 4 倍，得到 4 倍高清图。
zoom_out_2x：对画面进行缩小两倍操作（周围区域填充）。
zoom_out_1_5x：对画面进行缩小 1.5 倍操作（周围区域填充）。
pan_left：对画面进行左偏移操作。
pan_right：对画面进行右便宜操作。
pan_up：对画面进行上偏移操作。
pan_down：对画面进行下偏移操作。

可以继续按照上述流程传入对应的变换指令进行连续生图操作。

图像改写（垫图）

该 API 也支持图像改写，俗称垫图，我们可以输入一张图片 URL 以及需要改写的描述文字，该 API 就可以返回改写后的图片。

注意：输入的图片 URL 需要是一张纯图片，不能是一个网页里面展示一张图片，否则无法进行图像改写。建议使用图床来上传获取图片的 URL。

例如，我们这里有一张公路落日的图片，公路旁边有一些树木和楼房，如图所示：

现在我们想在它的基础上改写成海滩旁边，同时放一辆汽车停在路边。我们就可以构造如下的 prompt：

1	https://cdn.acedata.cloud/v014oc.png an illustration of a car parked on the beach --iw 2

可以看到，我们的 prompt 的最开头是一个 HTTPS 开头的图片链接，然后接着加一个空格，后面跟上 prompt 文字的内容。这里我们还用了额外的一些高级参数，如 —iw 2 来调整图片的权重。

我们可以将如上内容作为一个整体，传递给 prompt 字段，如图所示：

输出结果如下：

{
  "image_url": "https://midjourney.cdn.acedata.cloud/attachments/1234427310434947145/1234539663515975690/atmateosa5693_An_illustration_of_a_car_parked_on_the_beach_id26_cc8650ec-7e4b-4685-8911-78172430d8a7.png?ex=66311a28&is=662fc8a8&hm=c39707a1f22bc7f12874060ea6ed58ba37c188139ccc9a13c61ed9f37e66ea74&width=1456&height=816",
  "image_width": 1456,
  "image_height": 816,
  "image_id": "1234539663515975690",
  "raw_image_url": "https://midjourney.cdn.acedata.cloud/attachments/1234427310434947145/1234539663515975690/atmateosa5693_An_illustration_of_a_car_parked_on_the_beach_id26_cc8650ec-7e4b-4685-8911-78172430d8a7.png?ex=66311a28&is=662fc8a8&hm=c39707a1f22bc7f12874060ea6ed58ba37c188139ccc9a13c61ed9f37e66ea74&",
  "raw_image_width": 2912,
  "raw_image_height": 1632,
  "progress": 100,
  "actions": [
    "upscale1",
    "upscale2",
    "upscale3",
    "upscale4",
    "reroll",
    "variation1",
    "variation2",
    "variation3",
    "variation4"
  ],
  "task_id": "24a79e8b-a79d-471a-aef7-089dc0627ee8",
  "success": true
}

这时候我们就得到了如下生成的图片：

可以看到，在原来的图片整体风格和构图不变的前提下，整个场景变成了海滩旁边，同时公路上还出现了汽车，这就是 Prompt with Image。

图像融合

该 API 也支持图像融合，我们可以传入多张图片，以实现不同的图片融合效果。

比如说这里我们一共有两张图片，一张是一只玩具熊，另一张是一个电锯，分别如图所示：

现在我们想把二者融合起来，让这只熊拿着这个电锯，怎么做呢？

我们可以构造如下的 prompt：

1	https://cdn.acedata.cloud/8fapzl.png https://cdn.acedata.cloud/c1igbw.png The bear is holding the chainsaw --iw 2

可以发现，和 Image with Prompt 类似，我们这里将多张图片 URL 放在了 prompt 开头，并以空格分隔，最后再加上文字 prompt，将如上内容作为一个整体传递给 prompt 参数，运行效果如下：

{
  "image_url": "https://midjourney.cdn.acedata.cloud/attachments/1234291876639674388/1234547236830973972/kcisok_The_bear_is_holding_the_chainsaw_id8873344_ad605bc4-ba19-4807-b94f-367dab672f7a.png?ex=66312136&is=662fcfb6&hm=0fb1e2261c9a30b04de9da9b23b7562eb73677f1bbda1fae52c7243b12d25aac&width=1024&height=1024",
  "image_width": 1024,
  "image_height": 1024,
  "image_id": "1234547236830973972",
  "raw_image_url": "https://midjourney.cdn.acedata.cloud/attachments/1234291876639674388/1234547236830973972/kcisok_The_bear_is_holding_the_chainsaw_id8873344_ad605bc4-ba19-4807-b94f-367dab672f7a.png?ex=66312136&is=662fcfb6&hm=0fb1e2261c9a30b04de9da9b23b7562eb73677f1bbda1fae52c7243b12d25aac&",
  "raw_image_width": 2048,
  "raw_image_height": 2048,
  "progress": 100,
  "actions": [
    "upscale1",
    "upscale2",
    "upscale3",
    "upscale4",
    "reroll",
    "variation1",
    "variation2",
    "variation3",
    "variation4"
  ],
  "task_id": "891f2645-ee15-4c7b-ac24-d98163c8e57e",
  "success": true
}

我们就得到了如下结果：

可以看到，我们就成功实现了图片融合。

注意：图片融合最多可以支持 5 个图片 URL 作为输入，也就是最多支持 5 张图片融合，输入格式同上。

局部变换

该 API 也支持图像的局部绘图功能，但只支持在上文内容下生成的图片，我们可以传入一张生成图片的的唯一ID，局部重绘的行为参数 action 以及需要重绘区域的掩码mask，以实现在改掩码区域进行重绘。

比如说这里我们有一张生成关于猫的图片：

现在我们想对这个猫脸进行重绘，怎么做呢？

首先我们需要获取该区域的掩码mask，此mask是通过灰度图片进行Base64编码得来的，下面提供一些获取掩码的工具代码：

Python获取掩码示例代码：

import sys
import os
from PySide6.QtWidgets import *
from PySide6.QtGui import QPainter, QMouseEvent, QPen, QColor, QImage
from PySide6.QtCore import Qt, QPoint

class DrawingWidget(QWidget):
    def __init__(self, imagePath):
        super().__init__()
        self.setAttribute(Qt.WA_StaticContents)
        self.background_image = QImage(imagePath)
        imageSize = self.background_image.size()*0.8
        self.setFixedSize(imageSize)
        self.foreground_image = QImage(self.size(), QImage.Format_ARGB32)
        self.foreground_image.fill(Qt.transparent)
        self.drawing = False
        self.lastPoint = QPoint()
        self.pen_color = QColor(255, 255, 255, 255)
        self.pen_size = 50

    def set_pen_size(self, size):
        self.pen_size = size

    def mousePressEvent(self, event: QMouseEvent):
        if event.button() == Qt.LeftButton:
            self.drawing = True
            self.lastPoint = event.pos()

    def mouseMoveEvent(self, event: QMouseEvent):
        if event.buttons() & Qt.LeftButton and self.drawing:
            painter = QPainter(self.foreground_image)
            painter.setRenderHint(QPainter.Antialiasing, True)
            pen = QPen(self.pen_color, self.pen_size,
                       Qt.SolidLine, Qt.RoundCap, Qt.RoundJoin)
            painter.setPen(pen)
            painter.drawLine(self.lastPoint, event.pos())
            self.lastPoint = event.pos()
            self.update()

    def mouseReleaseEvent(self, event: QMouseEvent):
        if event.button() == Qt.LeftButton and self.drawing:
            self.drawing = False

    def paintEvent(self, event):
        canvasPainter = QPainter(self)
        canvasPainter.drawImage(
            self.rect(), self.background_image, self.background_image.rect())
        canvasPainter.drawImage(
            self.rect(), self.foreground_image, self.foreground_image.rect())

    def save_image(self, path):
        self.foreground_image.save(path)

class MainWindow(QDialog):
    def __init__(self, imagePath):
        super().__init__()
        self.setWindowTitle("mask tool")
        self.drawing_widget = DrawingWidget(imagePath)
        self.currentPath = os.getcwd().replace("\\", "/")
        self.tempPath = self.currentPath + "/temp.jpg"
        self.projectPath = ""
        self.setDone = False

    def init_ui(self):
        layout = QVBoxLayout()
        layout.addWidget(self.drawing_widget)
        controls_layout = QHBoxLayout()
        size_label = QLabel("pen size:")
        controls_layout.addWidget(size_label)
        self.size_slider = QSlider(Qt.Horizontal)
        self.size_slider.setMinimum(100)
        self.size_slider.setMaximum(400)
        self.size_slider.setValue(400)
        self.size_slider.valueChanged.connect(self.update_pen_size)
        controls_layout.addWidget(self.size_slider)
        self.lineEdit_addPromp = QLineEdit()
        layout.addWidget(self.lineEdit_addPromp)
        save_button = QPushButton("   Start partial redrawing   ")
        save_button.clicked.connect(self.save_image)
        controls_layout.addWidget(save_button)
        dont_button = QPushButton("   Cancel partial redraw   ")
        dont_button.clicked.connect(self.dont_image)
        controls_layout.addWidget(dont_button)
        layout.addLayout(controls_layout)
        self.setLayout(layout)

    def update_pen_size(self):
        size = self.size_slider.value()
        self.drawing_widget.set_pen_size(size)

    def save_image(self):
        tempImage = self.currentPath + "/temp.jpg"
        self.drawing_widget.save_image(self.tempPath)
        self.prompt = self.lineEdit_addPromp.text()
        self.setDone = True
        self.close()

    def dont_image(self):
        self.setDone = False
        self.close()

    def closeEvent(self, event):
        if self.setDone:
            pass
        else:
            self.setDone = False
        event.accept()


if __name__ == '__main__':
    imagePath = "test.png"
    app = QApplication(sys.argv)
    mainWindow = MainWindow(imagePath)
    mainWindow.init_ui()
    mainWindow.exec()

通过以上代码可以获得掩码图片，在这个过程中我们需要注意掩码图片必须与原图片一样的尺寸，然后掩码图片中白色的区域就是需要重绘的区域，下面展示猫图片需要重绘的掩码图片与原图的对比：

原图片：

掩码图片：

最后我们还需要将掩码图片转换为基于Base64的编码，接下来提供转换Base64编码的代码：

Python转换Base64示例代码：

import cv2
import base64

image_path = 'temp.jpg'
gray_image = cv2.imread(image_path)
_, buffer = cv2.imencode('.jpg', gray_image)
base64_encoded = base64.b64encode(buffer).decode('utf-8')
with open('grayscale_image_base64.txt', 'w') as f:
    f.write(base64_encoded)

print("success!")

注意：上述 Python 代码描述了 mask 的生成过程，如果您要将其对接到您的产品中，请根据其原理编写对应语言的代码。

通过以上代码，我们获得了需要重绘的掩码 mask ，下面我们还需要需要将参数 action 设置为 variation_region ，生成图片的ID image_id （获取该参数参考上文的内容），以及传入对应的掩码 mask ，其它参数信息如下：

action：对图片进行操作的行为，此处为 variation_region ，表示对图片进行局部重绘。
prompt：对图像进行局部重绘的描述词（可选参数）。
image_id：图片的唯一标识，方便对图像进行局部重绘。
mask：图片对应的掩码区域的base64编码（图片是上面image_id指定的）。

因此根据以上规则我们需要设置正确的的参数，参数 prompt 是一个非必填参数，这里为了方便对比将掩码区域的 prompt 设置为 A cute cat ，具体的参数设置如下图所示：

代码示例

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

部分代码示例如下：

CURL

curl -X POST 'https://api.acedata.cloud/midjourney/imagine' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "prompt": "A  cute cat ",
  "action": "variation_region",
  "image_id": "1265875488702726144",
  "mask": "/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAIBAQEBAQIBAQECAgICAgQDAgICAgUEBAMEBgUGBgYFBgYGBwkIBgcJBwYGCAsICQoKCgoKBggLDAsKDAkKCgr/2wBDAQICAgICAgUDAwUKBwYHCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgr/wAARCAGaAZoDASIAAhEBAxEB/8QAHwAAAQUBAQEBAQEAAAAAAAAAAAECAwQFBgcICQoL/8QAtRAAAgEDAwIEAwUFBAQAAAF9AQIDAAQRBRIhMUEGE1FhByJxFDKBkaEII0KxwRVS0fAkM2JyggkKFhcYGRolJicoKSo0NTY3ODk6Q0RFRkdISUpTVFVWV1hZWmNkZWZnaGlqc3R1dnd4eXqDhIWGh4iJipKTlJWWl5iZmqKjpKWmp6ipqrKztLW2t7i5usLDxMXGx8jJytLT1NXW19jZ2uHi4+Tl5ufo6erx8vP09fb3+Pn6/8QAHwEAAwEBAQEBAQEBAQAAAAAAAAECAwQFBgcICQoL/8QAtREAAgECBAQDBAcFBAQAAQJ3AAECAxEEBSExBhJBUQdhcRMiMoEIFEKRobHBCSMzUvAVYnLRChYkNOEl8RcYGRomJygpKjU2Nzg5OkNERUZHSElKU1RVVldYWVpjZGVmZ2hpanN0dXZ3eHl6goOEhYaHiImKkpOUlZaXmJmaoqOkpaanqKmqsrO0tba3uLm6wsPExcbHyMnK0tPU1dbX2Nna4uPk5ebn6Onq8vP09fb3+Pn6/9oADAMBAAIRAxEAPwD+f+iiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKK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/GlvIP8ASbeP7T/on7yK7luDLH+//wAI/i58MPjn4Asfij8G/iVoPi/w3qjTf2f4h8M6vFqFhdGKaSKXybmEmKURyxyR5BPMZzzX8GFeu/sxftp/tX/sX+JD4v8A2Vv2iPFngS7mv7K91KLQdbkgtdSmtpDJa/bLb/U30cZeQeVcxyxYklGCJSCAf3P0V/Nn+zF/weiftb+APDh0H9qf9lLwn8S7uDTLGDT9a8Pa7L4cuZ5Yoitzc3o8m7hlkl/dy4toraKIiQeXiQCL03/iOaP/AEi9/wDM1/8A3loA/f8Aor8AP+I5o/8ASL3/AMzX/wDeWj/iOaP/AEi9/wDM1/8A3loA/f8Aor8AP+I5o/8ASL3/AMzX/wDeWj/iOaP/AEi9/wDM1/8A3loA/f8Aor8AP+I5o/8ASL3/AMzX/wDeWvlv9p3/AIO6P+Crnxj8U/b/AIFa74Q+EOiWmoXz2lh4d8MW2qXNxbSv/o0V9c6rHcxzSwxx4822itRKZJCY8eWIwD+qOiv5BP8AiKL/AOC6P/R8v/mM/DH/AMq6P+Iov/guj/0fL/5jPwx/8q6AP6+65L4ufFz4YfAzwBf/ABR+MnxK0Hwh4b0tof7Q8Q+JtXi0+wtTLNHFF51zMRFEJJZI48kjmQY5r+TH/iKL/wCC6P8A0fL/AOYz8Mf/ACrr5b/ad/bT/av/AG0PEg8X/tU/tEeLPHd3Df3t7psWva3JPa6bNcyCS6+x23+psY5CkY8q2jiixHEMARAAA/TT/g4F/wCDkbwr/wAFAvhvd/sSfsT6RqNr8ML2+Wbxz4u8SaSkdz4na0vvNtYbKNiZLWxMkFtc+bII7qUiKMx2wiljufxuoooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKAP/Z"
}'

Python

import requests

url = "https://api.acedata.cloud/midjourney/imagine"

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

payload = {
    "prompt": "A  cute cat ",
    "action": "variation_region",
    "image_id": "1265875488702726144",
    "mask": "/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAIBAQEBAQIBAQECAgICAgQDAgICAgUEBAMEBgUGBgYFBgYGBwkIBgcJBwYGCAsICQoKCgoKBggLDAsKDAkKCgr/2wBDAQICAgICAgUDAwUKBwYHCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgr/wAARCAGaAZoDASIAAhEBAxEB/8QAHwAAAQUBAQEBAQEAAAAAAAAAAAECAwQFBgcICQoL/8QAtRAAAgEDAwIEAwUFBAQAAAF9AQIDAAQRBRIhMUEGE1FhByJxFDKBkaEII0KxwRVS0fAkM2JyggkKFhcYGRolJicoKSo0NTY3ODk6Q0RFRkdISUpTVFVWV1hZWmNkZWZnaGlqc3R1dnd4eXqDhIWGh4iJipKTlJWWl5iZmqKjpKWmp6ipqrKztLW2t7i5usLDxMXGx8jJytLT1NXW19jZ2uHi4+Tl5ufo6erx8vP09fb3+Pn6/8QAHwEAAwEBAQEBAQEBAQAAAAAAAAECAwQFBgcICQoL/8QAtREAAgECBAQDBAcFBAQAAQJ3AAECAxEEBSExBhJBUQdhcRMiMoEIFEKRobHBCSMzUvAVYnLRChYkNOEl8RcYGRomJygpKjU2Nzg5OkNERUZHSElKU1RVVldYWVpjZGVmZ2hpanN0dXZ3eHl6goOEhYaHiImKkpOUlZaXmJmaoqOkpaanqKmqsrO0tba3uLm6wsPExcbHyMnK0tPU1dbX2Nna4uPk5ebn6Onq8vP09fb3+Pn6/9oADAMBAAIRAxEAPwD+f+iiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKK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/GlvIP8ASbeP7T/on7yK7luDLH+//wAI/i58MPjn4Asfij8G/iVoPi/w3qjTf2f4h8M6vFqFhdGKaSKXybmEmKURyxyR5BPMZzzX8GFeu/sxftp/tX/sX+JD4v8A2Vv2iPFngS7mv7K91KLQdbkgtdSmtpDJa/bLb/U30cZeQeVcxyxYklGCJSCAf3P0V/Nn+zF/weiftb+APDh0H9qf9lLwn8S7uDTLGDT9a8Pa7L4cuZ5Yoitzc3o8m7hlkl/dy4toraKIiQeXiQCL03/iOaP/AEi9/wDM1/8A3loA/f8Aor8AP+I5o/8ASL3/AMzX/wDeWj/iOaP/AEi9/wDM1/8A3loA/f8Aor8AP+I5o/8ASL3/AMzX/wDeWj/iOaP/AEi9/wDM1/8A3loA/f8Aor8AP+I5o/8ASL3/AMzX/wDeWvlv9p3/AIO6P+Crnxj8U/b/AIFa74Q+EOiWmoXz2lh4d8MW2qXNxbSv/o0V9c6rHcxzSwxx4822itRKZJCY8eWIwD+qOiv5BP8AiKL/AOC6P/R8v/mM/DH/AMq6P+Iov/guj/0fL/5jPwx/8q6AP6+65L4ufFz4YfAzwBf/ABR+MnxK0Hwh4b0tof7Q8Q+JtXi0+wtTLNHFF51zMRFEJJZI48kjmQY5r+TH/iKL/wCC6P8A0fL/AOYz8Mf/ACrr5b/ad/bT/av/AG0PEg8X/tU/tEeLPHd3Df3t7psWva3JPa6bNcyCS6+x23+psY5CkY8q2jiixHEMARAAA/TT/g4F/wCDkbwr/wAFAvhvd/sSfsT6RqNr8ML2+Wbxz4u8SaSkdz4na0vvNtYbKNiZLWxMkFtc+bII7qUiKMx2wiljufxuoooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKACiiigAooooAKKKKAP/Z"
}

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

响应示例

请求成功后，API 将返回换脸后端图片结果信息。例如：

{
  "image_url": "https://platform.cdn.acedata.cloud/midjourney/6c9450d8-1c22-4f85-a527-e7a7bfb4a61b.png?imageMogr2/thumbnail/!50p",
  "image_width": 1024,
  "image_height": 1024,
  "actions": [
    "upscale1",
    "upscale2",
    "upscale3",
    "upscale4",
    "reroll",
    "variation1",
    "variation2",
    "variation3",
    "variation4"
  ],
  "raw_image_url": "https://platform.cdn.acedata.cloud/midjourney/6c9450d8-1c22-4f85-a527-e7a7bfb4a61b.png",
  "raw_image_width": 2048,
  "raw_image_height": 2048,
  "progress": 100,
  "image_id": "1265876571323891712",
  "task_id": "6c9450d8-1c22-4f85-a527-e7a7bfb4a61b",
  "success": true
}

可以发现这是对掩码区域的图像进行了重绘操作，返回的结果与上文的是一致的，结果如下图所示：

可以看到，我们就成功实现了对生成的图片的自定义区域进行局部重绘。

异步回调

由于 Midjourney 生成图片需要等待一段时间，所以本 API 也默认设计为了长等待模式。但在部分场景下，长等待可能会带来一些额外的资源开销，因此本 API 也提供了异步 Webhook 回调的方式，当图片生成成功或失败时，其结果都会通过 HTTP 请求的方式发送到指定的 Webhook 回调 URL。回调 URL 接收到结果之后可以进行进一步的处理。

下面演示具体的调用流程。

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

将此 URL 复制下来，就可以作为 Webhook 来使用，此处的样例为 https://webhook.site/995d0a91-d737-40a7-a3b9-5baf68ed924c。

接下来，我们可以设置字段 callback_url 为上述 Webhook URL，同时填入 prompt，如图所示：

点击测试之后会立即得到一个 task_id 的响应，用于标识当前生成任务的 ID，如图所示：

稍等片刻，等图片生成结束，可以发发现 Webhook URL 收到了一个 HTTP 请求，如图所示：

其结果就是当前任务的结果，内容如下：

{
  "success": true,
  "task_id": "f6e39eaf-652a-4bf5-a15c-79d8b143b80a",
  "image_url": "https://midjourney.cdn.acedata.cloud/attachments/1234291876639674388/1234551030549839932/kcisok_A_cat_sitting_on_a_table_id2724480_591c5c85-ec80-42ab-9fe5-9adfbed192e4.png?ex=663124be&is=662fd33e&hm=da725eb74aae375d60beec38b4cd26c5a7b373b1662f222ff838a8ea6fd5e798&width=1024&height=1024",
  "image_width": 1024,
  "image_height": 1024,
  "image_id": "1234551030549839932",
  "raw_image_url": "https://midjourney.cdn.acedata.cloud/attachments/1234291876639674388/1234551030549839932/kcisok_A_cat_sitting_on_a_table_id2724480_591c5c85-ec80-42ab-9fe5-9adfbed192e4.png?ex=663124be&is=662fd33e&hm=da725eb74aae375d60beec38b4cd26c5a7b373b1662f222ff838a8ea6fd5e798&",
  "raw_image_width": 2048,
  "raw_image_height": 2048,
  "progress": 100,
  "actions": [
    "upscale1",
    "upscale2",
    "upscale3",
    "upscale4",
    "reroll",
    "variation1",
    "variation2",
    "variation3",
    "variation4"
  ]
}

其中 success 字段标识了该任务是否执行成功，如果执行成功，还会有同样的 actions, image_id, image_url 字段，和上文介绍的返回结果是一样的，另外还有 task_id 用于标识任务，以实现 Webhook 结果和最初 API 请求的关联。

如果图片生成失败，Webhook URL 则会收到类似如下内容：

{
  "success": false,
  "task_id": "7ba0feaf-d20b-4c22-a35a-31ec30fc7715",
  "error": {
    "code": "bad_request",
    "message": "Unrecognized argument(s): `-c`, `x`"
  }
}

这里的 success 字段会是 false，同时还会有 error.code 和 error.message 字段描述了任务错误的详情信息，Webhook 服务器根据对应的结果进行处理即可。

流式输出

Midjourney 官方在生成图片的时候是有进度的，在最开始是一张模糊的照片，然后经过几次迭代之后，图片逐渐变得清晰，最后得到完整的图片。

所以，一张图片的生成过程大约可以分为「发送命令」->「开始生图（多次迭代逐渐清晰）」->「生图完毕」的阶段。

在没开启流式输出的情况下，本 API 从发起请求到返回结果，实际上是从上述「发送命令」->「生图完毕」的全过程，中间生图的过程也全被包含在里面，由于 Midjourney 本身生成图片速度较慢，整个过程大约需要等待一分钟或更久。

所以为了更好的用户体验，本 API 支持流式输出，即当「开始生图」的时候就开始返回结果，每当绘制进度有变化，就会流式将结果输出，直至生图结束。

如果想流式返回响应，可以更改请求头里面的 accept 参数，修改为 application/x-ndjson，不过调用代码需要有对应的更改才能支持流式响应。

Python 样例代码：

import requests

url = 'https://api.acedata.cloud/midjourney/imagine'
headers = {
    'content-type': 'application/json',
    'accept': 'application/x-ndjson',
    'authorization': 'Bearer {token}'
}
body = {
    "prompt": "a beautiful cat --v 6"
}
r = requests.post(url, headers=headers, json=body, stream=True)
for line in r.iter_lines():
    print(line.decode())

运行结果：

1
2
3

{"image_url":"https://midjourney.cdn.acedata.cloud/attachments/1234291876639674388/1234558451443699803/eae94f0f-0ba5-4b3c-9bad-59fb33ac2cbc_grid_0.webp?ex=66312ba7&is=662fda27&hm=4625d5f12158bffc07c4faaf6ce75af6f1396122f148b33b91f3e20b48fecc8b&width=256&height=256","image_width":256,"image_height":256,"image_id":"1234558451443699803","raw_image_url":"https://midjourney.cdn.acedata.cloud/attachments/1234291876639674388/1234558451443699803/eae94f0f-0ba5-4b3c-9bad-59fb33ac2cbc_grid_0.webp?ex=66312ba7&is=662fda27&hm=4625d5f12158bffc07c4faaf6ce75af6f1396122f148b33b91f3e20b48fecc8b&","raw_image_width":512,"raw_image_height":512,"progress":35,"actions":[],"task_id":"49589d2c-b6b3-4fbf-9f82-93068509c76f","success":true}
{"image_url":"https://midjourney.cdn.acedata.cloud/attachments/1234291876639674388/1234558458595115149/eae94f0f-0ba5-4b3c-9bad-59fb33ac2cbc_grid_0.webp?ex=66312ba9&is=662fda29&hm=9af53fa645127131a88dfbb3930add7abda710c12a3d6c30c457d6a067b36bab&width=256&height=256","image_width":256,"image_height":256,"image_id":"1234558458595115149","raw_image_url":"https://midjourney.cdn.acedata.cloud/attachments/1234291876639674388/1234558458595115149/eae94f0f-0ba5-4b3c-9bad-59fb33ac2cbc_grid_0.webp?ex=66312ba9&is=662fda29&hm=9af53fa645127131a88dfbb3930add7abda710c12a3d6c30c457d6a067b36bab&","raw_image_width":512,"raw_image_height":512,"progress":75,"actions":[],"task_id":"49589d2c-b6b3-4fbf-9f82-93068509c76f","success":true}
{"image_url":"https://midjourney.cdn.acedata.cloud/attachments/1234291876639674388/1234558483408490566/kcisok_A_landscape_painting_of_a_beautiful_sunset_id5963392_eae94f0f-0ba5-4b3c-9bad-59fb33ac2cbc.png?ex=66312baf&is=662fda2f&hm=185ea8f130806bf8bd96911bd251808455fd65596edcdb459f9b3cfd7860387c&width=1024&height=1024","image_width":1024,"image_height":1024,"image_id":"1234558483408490566","raw_image_url":"https://midjourney.cdn.acedata.cloud/attachments/1234291876639674388/1234558483408490566/kcisok_A_landscape_painting_of_a_beautiful_sunset_id5963392_eae94f0f-0ba5-4b3c-9bad-59fb33ac2cbc.png?ex=66312baf&is=662fda2f&hm=185ea8f130806bf8bd96911bd251808455fd65596edcdb459f9b3cfd7860387c&","raw_image_width":2048,"raw_image_height":2048,"progress":100,"actions":["upscale1","upscale2","upscale3","upscale4","reroll","variation1","variation2","variation3","variation4"],"task_id":"49589d2c-b6b3-4fbf-9f82-93068509c76f","success":true}

可以看到，启用流式输出之后，返回结果就是逐行的 JSON 了。

在 Node.js 环境中，实现代码可写为如下：

const axios = require("axios");

const url = "https://api.acedata.cloud/midjourney/imagine";
const headers = {
  "content-type": "application/json",
  accept: "application/x-ndjson",
  authorization: "Bearer {token}",
};
const body = {
  prompt: "a beautiful cat --v 6",
  action: "generate",
};

axios
  .post(url, body, { headers: headers, responseType: "stream" })
  .then((response) => {
    console.log(response.status);
    response.data.on("data", (chunk) => {
      console.log(chunk.toString());
    });
  })
  .catch((error) => {
    console.error(error);
  });

这些示例运行的结果都是相似的。

请注意，流式输出结果中有一个称为 progress 的字段，表示生成进度，范围从 0 到 100。如果需要，您可以在页面上显示这些信息。

注意：当生成未完全完成时，actions 字段为空，表示无法对中间图像执行进一步处理操作。生成完成后，在生成过程中生成的 image_url 将被销毁。

此外，您可以通过指定 accept=application/x-ndjson 的请求头和 callback_url 的请求体，将流式结果与异步回调结合起来，然后 callback_url 可以接收到多个流式结果的 POST 请求。

作者崔庆才发表于 2026-06-08 阅读次数：本文字数： 41k 阅读时长 ≈ 37 分钟

API 开发教程 查询 AceDataCloud 平台分销推广信息

返回当前账户的分销（联盟营销 / Affiliate）数据——包括分销专属链接、邀请的下级用户数、累计佣金、可提现余额、近期成交记录等。

适用场景：

在你自己的产品里嵌入「赚取佣金」面板。
自动化邀请脚本、邀请仪表盘。
月度结算时拉取明细。

ℹ️ 本接口属于 AceDataCloud 平台管理 API，统一前缀 https://platform.acedata.cloud/api/v1/。

接口概览

项	内容
方法	`GET`
URL	`https://platform.acedata.cloud/api/v1/distribution/`
鉴权	✅ 需要账户令牌

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

请求头：

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

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

请求示例

cURL

1
2
3

curl 'https://platform.acedata.cloud/api/v1/distribution/' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer platform-v1-92eb****629c'

Python

import requests

resp = requests.get(
    "https://platform.acedata.cloud/api/v1/distribution/",
    headers={"authorization": "Bearer platform-v1-92eb****629c"},
    timeout=10,
)
data = resp.json()
print(f"专属推广链接: {data['referral_url']}")
print(f"邀请的用户数: {data['referred_users_count']}")
print(f"累计佣金: ¥{data['total_commission']}")
print(f"可提现余额: ¥{data['withdrawable_balance']}")

Node.js

const r = await fetch('https://platform.acedata.cloud/api/v1/distribution/', {
  headers: { authorization: 'Bearer platform-v1-92eb****629c' },
})
console.log(await r.json())

响应示例（HTTP 200）

{
  "user_id": "89518d07-5560-4b05-92c1-667f3ddf6a4b",
  "referral_code": "ABC123XYZ",
  "referral_url": "https://platform.acedata.cloud/?ref=ABC123XYZ",
  "referred_users_count": 87,
  "active_users_count": 31,
  "commission_rate": 0.20,
  "total_commission": 4521.30,
  "withdrawable_balance": 1820.50,
  "pending_balance": 124.30,
  "withdrawn_total": 2576.50,
  "currency": "CNY",
  "recent_orders": [
    {
      "order_id": "fa927d12-...",
      "referred_user_id": "uuser-abc...",
      "amount": 63.2,
      "commission": 12.64,
      "paid_at": "2026-04-25T15:23:00Z"
    }
  ],
  "tier": "Standard",
  "next_tier_at": 10000,
  "all_tiers": [
    { "name": "Standard",   "min_commission": 0,     "commission_rate": 0.20 },
    { "name": "Pro",        "min_commission": 1000,  "commission_rate": 0.25 },
    { "name": "Enterprise", "min_commission": 10000, "commission_rate": 0.30 }
  ]
}

响应字段说明

字段	类型	说明
`user_id`	UUID	当前用户 ID
`referral_code`	string	专属推广码
`referral_url`	string	完整推广链接（含 `?ref=` 参数）
`referred_users_count`	integer	已通过此链接注册的用户总数
`active_users_count`	integer	其中曾有付费行为的活跃用户数
`commission_rate`	number	当前佣金率（已结算订单按此比例分成）
`total_commission`	number	累计佣金（含已提现、可提现、待结算）
`withdrawable_balance`	number	当前可立即提现的余额
`pending_balance`	number	待结算余额（订单 3 天后转入可提现）
`withdrawn_total`	number	历史已提现总额
`currency`	string	结算货币代码
`recent_orders`	array	近期带分销关系的订单（最多 20 条），含 `order_id` / `referred_user_id` / `amount` / `commission`
`tier`	string	当前推广等级
`next_tier_at`	number	达到下一级所需累计佣金
`all_tiers`	array	全部等级定义

错误处理

HTTP	code	含义
401	`not_authenticated`	缺少账户令牌
403	`not_enabled`	你的账户尚未开通分销功能（联系客服开通）

实用提示

3 天结算锁定期：被邀请用户付费后，佣金先进 pending_balance，3 天后无退款则转入 withdrawable_balance。
多级分销：默认只支持一级（邀请的用户付费才有佣金）。多级分销请联系客服开通企业版。
提现：在 AceDataCloud 平台分销中心手动发起提现，支持支付宝、银行卡、USDT。
推广素材：去分销中心下载海报、Banner、邮件模板。

MCP 教程 Midjourney MCP 对接指南

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

功能概览

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

图像生成（Imagine） — 通过文本提示词生成高质量图像
图像编辑 — 对已生成的图像进行局部修改
图像变换 — 放大、缩放、平移已有图像
图像混合（Blend） — 将多张图像融合为新图像
参考图生成 — 使用参考图片引导生成
图像描述（Describe） — 根据图片生成文本描述
提示词翻译 — 将中文提示词翻译为英文
种子获取 — 获取图像的 seed 值用于复现
视频生成 — 基于图像生成动态视频
任务查询 — 监控生成进度并获取结果

前置准备

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

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

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

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

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

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

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

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

Claude Desktop

编辑配置文件：

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

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

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

Claude Code（终端命令行）

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

VS Code（GitHub Copilot）

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

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

Cursor

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

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

其他支持 MCP 的客户端

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

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

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

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

安装

pip 安装（推荐）：

1	pip install mcp-midjourney

或源码安装：

1
2
3

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

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

在 Claude Desktop 中使用（本地）

编辑 Claude Desktop 配置文件：

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

添加以下配置：

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

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

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

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

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

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

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

或者使用 uvx：

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

可用工具列表

工具名	说明
`midjourney_imagine`	通过文本提示词生成图像
`midjourney_edit`	编辑已有图像的局部区域
`midjourney_transform`	放大、缩放、平移已有图像
`midjourney_blend`	将多张图像混合为一张
`midjourney_with_reference`	使用参考图生成图像
`midjourney_describe`	根据图片生成文本描述
`midjourney_translate`	翻译提示词为英文
`midjourney_get_seed`	获取图像的 seed 值
`midjourney_generate_video`	基于图像生成视频
`midjourney_extend_video`	延长已有视频
`midjourney_get_task`	查询单个任务状态
`midjourney_get_tasks_batch`	批量查询任务状态

使用示例

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

「帮我生成一张赛博朋克风格的城市夜景」
「把这张图片的背景改成海边」
「将这四张图片混合成一张」
「描述一下这张图片里的内容」
「把这张图片做成视频」
「放大这张图片的第二个变体」

MCP 教程 Seedance MCP 对接指南

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

功能概览

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

文本生成视频 — 通过文本提示词生成高质量视频
图片生成视频 — 以图片为参考生成视频（首帧、末帧、参考图等模式）
多模型支持 — 支持 Seedance 1.5 Pro、1.0 Pro、1.0 Lite 等多种模型
多种分辨率 — 支持 480p、720p、1080p 多种分辨率
多种画面比例 — 支持 16:9、9:16、1:1、4:3、3:4、21:9 等比例
灵活时长 — 支持 2-12 秒的视频时长
音频生成 — 部分模型支持同时生成音频
任务查询 — 监控生成进度并获取结果

前置准备

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

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

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

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

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

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

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

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

Claude Desktop

编辑配置文件：

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

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

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

Claude Code（终端命令行）

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

VS Code（GitHub Copilot）

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

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

Cursor

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

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

其他支持 MCP 的客户端

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

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

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

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

安装

pip 安装（推荐）：

1	pip install mcp-seedance

或源码安装：

1
2
3

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

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

在 Claude Desktop 中使用（本地）

编辑 Claude Desktop 配置文件：

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

添加以下配置：

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

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

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

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

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

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

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

或者使用 uvx：

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

可用工具列表

工具名	说明
`seedance_generate_video`	通过文本提示词生成视频
`seedance_generate_video_from_image`	以图片为参考生成视频
`seedance_get_task`	查询单个任务状态
`seedance_get_tasks_batch`	批量查询任务状态
`seedance_list_models`	列出所有可用模型及其能力
`seedance_list_resolutions`	列出可用分辨率和画面比例
`seedance_list_actions`	列出所有可用工具和工作流示例

使用示例

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

「帮我用 Seedance 生成一段城市街头延时摄影视频」
「用这张照片作为第一帧，生成一段 8 秒的视频」
「生成一段 1080p 竖屏 9:16 的短视频」
「用 Seedance 1.5 Pro 模型生成带音频的视频」

API 开发教程 X402 订单支付教程

除了直接按 API 请求付费，Ace Data Cloud 也支持用 X402 支付控制台订单。订单支付和 API 调用的核心协议相同：第一次请求返回 402，客户端签出 X-Payment，然后用同一个请求重试。

区别在于订单支付属于平台 API，需要账户令牌；而直接调用 api.acedata.cloud 的 AI API 可以只用 X402，不需要 API Token。

准备订单

进入 Ace Data Cloud 控制台，选择需要支付的订单，记录订单 ID。

如果你还没有订单，可以在套餐页面创建一个待支付订单。订单价格以页面显示为准，X402 402 响应中的 maxAmountRequired 是最终签名依据。

创建账户令牌

订单支付请求需要账户令牌。打开平台 Token 页面，创建一个 platform-v1-... 格式的 token。

后续请求使用：

1	Authorization: Bearer {platform_token}

账户令牌不同于普通 API Token。普通 API Token 用于消费 API 额度；账户令牌用于代表你的账户操作平台资源，例如订单支付。

触发 402

先发送一次不带 X-Payment 的请求：

POST https://platform.acedata.cloud/api/v1/orders/{order_id}/pay/
Authorization: Bearer {platform_token}
Content-Type: application/json

{
  "pay_way": "X402"
}

返回状态为 402，响应中包含 accepts：

{
  "x402Version": 1,
  "error": "Payment required for this order.",
  "accepts": [
    {
      "scheme": "exact",
      "network": "base",
      "maxAmountRequired": "1200000",
      "resource": "http://platform.acedata.cloud/api/v1/orders/.../pay/",
      "payTo": "0x...",
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "extra": {
        "name": "USD Coin",
        "version": "2",
        "chainId": 8453,
        "verifyingContract": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
      }
    }
  ]
}

创建 10 Credits 订单并触发 402 的程序运行结果：

created order 78481793-304e-47f7-bc0c-8231aec9cc1e
created state Pending
created price 1.26

http_status=402
x402Version 1
error Payment required for this order.
accepts [
  ('base', 'exact', '1200000', '0x4F0E2D3477a1B94CF33d16E442CEe4733dadCeE7'),
  ('solana', 'exact', '1200000', '5iVXFrYaYWX2GUTbkQj8mDBoBhAX8bneYigS2LJTia43')
]
description Ace Data Cloud Credits x 10.0

结果说明：

订单创建成功后状态是 Pending，此时还没有链上付款。
第一次 pay/ 请求没有携带 X-Payment，所以返回 HTTP 402。
accepts 同时给出 Base exact 和 Solana exact，本教程后续选择 Base。
订单创建时价格是 1.26，进入 X402 支付流程后应用 X402 支付折扣，实际签名和结算金额为 1.2 USDC，对应 1200000 atomic USDC。

注意这里 resource 是服务端返回并参与签名的字段，客户端不要把其中的协议、路径或订单 ID 自己改写。

签名并重试

订单支付可以复用 @acedatacloud/x402-client 或 acedatacloud-x402 的低层签名函数。下面是 TypeScript 示例：

import { Wallet } from 'ethers';
import { signEVMPayment } from '@acedatacloud/x402-client';

const platformToken = process.env.ACE_PLATFORM_TOKEN!;
const orderId = process.env.ACE_ORDER_ID!;
const wallet = new Wallet(process.env.EVM_PRIVATE_KEY!);

const url = `https://platform.acedata.cloud/api/v1/orders/${orderId}/pay/`;
const body = { pay_way: 'X402' };

const first = await fetch(url, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${platformToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(body)
});

if (first.status !== 402) {
  throw new Error(`expected 402, got ${first.status}`);
}

const paymentRequired = await first.json();
const requirement = paymentRequired.accepts.find(
  (item: any) => item.network === 'base' && item.scheme === 'exact'
);

const evmProvider = {
  async request({ method, params }: { method: string; params?: unknown[] }) {
    if (method !== 'eth_signTypedData_v4') throw new Error(`unsupported method: ${method}`);
    const [, typedDataJson] = params as [string, string];
    const typedData = JSON.parse(typedDataJson);
    return wallet.signTypedData(typedData.domain, typedData.types, typedData.message);
  }
};

const envelope = await signEVMPayment(requirement, evmProvider, wallet.address);
const xPayment = Buffer.from(JSON.stringify(envelope), 'utf8').toString('base64');

const paid = await fetch(url, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${platformToken}`,
    'Content-Type': 'application/json',
    'X-Payment': xPayment
  },
  body: JSON.stringify(body)
});

if (!paid.ok) {
  throw new Error(`payment failed: ${paid.status} ${await paid.text()}`);
}

console.log(await paid.json());

同一个订单用 Base exact 签名并重试后的程序运行结果：

status 200
payer 0x5d4f08D5c2bb60703284bc06671Eb680fA41B105
has_x_payment_response True
settle_header {'success': True, 'network': 'base', 'transaction': '0xfec08cc00a159ea1ec692b32faa9bf3d17595a986301169e689d94f58bc44151', 'errorReason': None}
order {'id': '78481793-304e-47f7-bc0c-8231aec9cc1e', 'state': 'Finished', 'pay_way': 'X402', 'price': 1.2, 'pay_id': '0xfec08cc00a159ea1ec692b32faa9bf3d17595a986301169e689d94f58bc44151'}

链上确认结果：

tx 0xfec08cc00a159ea1ec692b32faa9bf3d17595a986301169e689d94f58bc44151
status 1
block 46726704
explorer https://basescan.org/tx/0xfec08cc00a159ea1ec692b32faa9bf3d17595a986301169e689d94f58bc44151
transfer {"from":"0x5d4f08D5c2bb60703284bc06671Eb680fA41B105","to":"0x4F0E2D3477a1B94CF33d16E442CEe4733dadCeE7","value":"1200000"}

结果说明：

status 200 表示平台订单支付接口接受了这次 X-Payment。
has_x_payment_response True 表示响应头包含 Base64 编码的 X-PAYMENT-RESPONSE 收据。
settle_header.success=True 且 network=base 表示 Facilitator 已完成 Base settlement。
订单最终状态是 Finished，pay_way 是 X402，pay_id 写入链上交易哈希。
BaseScan 上的 Transfer 事件显示付款地址向平台收款地址转账 1200000 atomic USDC，也就是 1.2 USDC。

成功响应与收据

订单支付成功后，响应体是订单信息。平台还会在响应头 X-PAYMENT-RESPONSE 中携带 Base64 编码的 settlement response，解码后常见字段包括：

字段	说明
`success`	Facilitator settlement 是否成功。
`transaction`	链上结算交易哈希。
`network`	支付网络。
`payer`	付款钱包地址。
`amount`	实际结算金额，使用 atomic units。

如果你需要对账，建议同时保存订单 ID、付款钱包地址、transaction 和订单最终状态。

注意事项

订单支付需要平台账户令牌，不能只靠 X402 钱包签名完成。
maxAmountRequired 使用 USDC atomic units，1200000 表示 1.2 USDC。
不要自行拼收款地址或资产地址，以 402 响应中的 accepts 为准。
如果同一个 X-Payment 被重复提交，Facilitator 会按 nonce 做重放保护。

作者崔庆才发表于 2026-06-05 阅读次数：本文字数： 5.3k 阅读时长 ≈ 5 分钟

产品推广 Cline 对接 Kling MCP

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

Kling 是快手的视频生成模型，文生视频 / 图生视频 / 扩展视频都能做，画面细腻。通过 MCP 接入 Cline 后，可以直接在对话里调用，不用切窗口、不用复制粘贴。

获取 API Token

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

配置

编辑配置：Cline 设置面板 → MCP Servers → Edit Settings（会打开 cline_mcp_settings.json）

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

保存后 Cline 会自动重新加载 MCP，工具即时可用。

使用示例

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

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

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

工具

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

产品推广 Gemini CLI 对接 Seedance MCP

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

字节跳动出品的视频模型，舞蹈、运动、连贯动作表现优异，支持竖屏 9:16 短视频。通过 MCP 接入 Gemini CLI 后，可以直接在对话里调用，不用切窗口、不用复制粘贴。

获取 API Token

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

配置

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

gemini mcp add seedance \
  --type http \
  --url https://seedance.mcp.acedata.cloud/mcp \
  --header "Authorization: Bearer 你的Token"

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

{
  "mcpServers": {
    "seedance": {
      "httpUrl": "https://seedance.mcp.acedata.cloud/mcp",
      "headers": { "Authorization": "Bearer 你的Token" }
    }
  }
}

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

使用示例

用 Seedance 生成一段竖屏短视频：一个女孩在樱花树下转圈跳舞，9:16

把这张图（链接 xxx）做成一段 5 秒动作视频

生成一段 10 秒 1080P 美食制作视频：寿司师傅切金枪鱼，特写镜头

工具

工具	说明
seedance_generate_video	文生视频 / 图生视频，可选音频

产品推广 Codex CLI 对接 Flux MCP

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

Black Forest Labs 出品的顶级开源图像模型，写实风格、Kontext 编辑能力一流。通过 MCP 接入 Codex CLI 后，可以直接在对话里调用，不用切窗口、不用复制粘贴。

获取 API Token

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

配置

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

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

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

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

使用示例

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

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

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

工具

工具	说明
flux_generate_image	文生图（Flux pro / dev / ultra）
flux_edit_image	对已有图按提示词编辑（用 flux-kontext-pro / max 模型）

产品推广 Cursor 对接 Fish 语音 MCP

📘 Overview：Cursor MCP Overview →

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

获取 API Token

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

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

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

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

配置 Cursor

.cursor/mcp.json：

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

哪些场景特别合适

用 fish_generate_audio 把这段中文合成成 mp3，用默认音色
把这段英文合成成 wav，采样率 44100，使用音色 ID xxxx
把这段播客脚本合成成 mp3，bitrate 128，低延迟模式

工作流提示

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

工具

工具	说明
fish_generate_audio	文本转语音（s1 / s2-pro 模型，可选音色、采样率、格式、延迟模式）

产品推广 OpenCode MCP Overview

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

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

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

为什么要在 OpenCode 里接 MCP

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

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

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

AceData Cloud 提供哪些 MCP Server

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

MCP Server	领域	适合做什么	工具数	OpenCode 教程
Suno	AI 音乐	写歌、配乐、歌词、翻唱、续写、人声分离	35	查看教程
Midjourney	AI 绘画	文生图、混图、放大、编辑、生成视频	16	查看教程
Flux	AI 绘画	快速出图、商用级图片、Kontext 图片编辑	6	查看教程
Seedream	AI 绘画	中文 prompt 出图、商品图、海报、图片编辑	6	查看教程
NanoBanana	AI 图片编辑	商品换景、虚拟试衣、人物/物体一致性编辑	4	查看教程
Luma	AI 视频	文生视频、图生视频、视频延伸、首尾帧控制	8	查看教程
Sora	AI 视频	高质量文生视频、图生视频、角色一致性	10	查看教程
Veo	AI 视频	Google Veo 视频、原生音频、1080p / 4K	12	查看教程
Seedance	AI 视频	动作视频、短视频、配音、竖屏素材	7	查看教程
Google 搜索	实时搜索	Google 网页、图片、新闻、地图、视频搜索	11	查看教程
ShortURL	效率工具	长链转短链、批量短链、分享链接整理	4	查看教程

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

配置在哪里写

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

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

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

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

字段说明：

字段	说明
`type`	固定为 `remote`，代表远程托管 MCP Server
`url`	AceData 提供的对应服务地址
`enabled`	是否启用，临时关闭某个 MCP 时改成 `false` 即可
`oauth`	必须显式设为 `false`。AceData MCP 走 Bearer Token 鉴权，不走 OAuth；不写这一行时 OpenCode 会把 401 当成 OAuth 挑战，最终 `opencode mcp list` 报 `SSE error: Non-200 status code (401)`
`headers.Authorization`	`Bearer <token>`，推荐用 `{env:ACEDATACLOUD_API_KEY}` 占位符引用环境变量

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

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

真实连通性验证

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

$ opencode --version
1.15.13

$ opencode mcp list

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

调试单个 MCP 连接：

1	opencode mcp debug shorturl

选模型的实测建议

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

场景	推荐模型	说明
对话 + 大量 MCP 工具	`acedatacloud/gpt-5-mini` 或 `acedatacloud/gpt-5`	实测可以正常发出工具调用，例如让 `gpt-5` 调用 `shorturl_create` 直接返回 `https://surl.id/r/1uNdf1MEkM` 短链
纯对话 / 阅读代码 / 不调用 MCP	`acedatacloud/claude-sonnet-4-6`、`acedatacloud/claude-haiku-4-5-20251001`	Claude 系列对自然语言任务表现更好
关掉 MCP、只做规划	`acedatacloud/claude-opus-4-7`	适合架构、重构方案的深度思考

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

常见工作流

终端里写 README 顺手生图

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

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

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

发版素材一条龙

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

下一步

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

产品推广 Windsurf 对接 Hailuo (MiniMax) MCP

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

MiniMax 海螺是文生视频 / 图生视频模型，支持 Director Mode 精确控制运镜。通过 MCP 接入 Windsurf 后，可以直接在对话里调用，不用切窗口、不用复制粘贴。

获取 API Token

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

配置

编辑配置：~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "hailuo": {
      "serverUrl": "https://hailuo.mcp.acedata.cloud/mcp",
      "headers": { "Authorization": "Bearer 你的Token" }
    }
  }
}

保存后重启 Windsurf 即可使用工具。

使用示例

用 hailuo-02 生成 6 秒视频：傍晚的山间小路，雾气漫过来，镜头慢慢推进

用 hailuo-01-director 生成视频：[拉镜头]一个咖啡馆的桌面特写转到[摇镜头]整个店内

用这张图（链接 xxx）做 image2video，让画面里的鸟从树枝飞起

工具

工具	说明
hailuo_generate_video	通过文本或图片生成视频（hailuo-02 / hailuo-02-pro / hailuo-01-director / hailuo-01-live）

产品推广 JetBrains 对接 Seedream MCP

📘 完整指南：在 JetBrains（IntelliJ IDEA / PyCharm / WebStorm 等）里用全部 11 个 AceData Cloud MCP →

字节跳动出品的图像模型，中文语义理解强，擅长国风、东方审美、写实摄影。通过 MCP 接入 JetBrains（IntelliJ IDEA / PyCharm / WebStorm 等）后，可以直接在对话里调用，不用切窗口、不用复制粘贴。

获取 API Token

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

配置

编辑配置：Junie 或 Claude 插件设置 → MCP Servers → Add Server

Name: seedream
Type: HTTP (Streamable)
URL: https://seedream.mcp.acedata.cloud/mcp
Headers:
  Authorization = Bearer 你的Token

保存后在 Junie / Claude 插件的工具栏即可看到工具。

使用示例

用 Seedream 生成一幅中国风山水画：远山、溪流、茅草亭

生成一张国潮风插画：锦鲤跃出水面，背景祥云

把这张照片（链接 xxx）按文字指令修改（SeedEdit 3.0）

工具

工具	说明
seedream_generate_image	文生图（3.0 / 4.0 / 4.5 / 5.0）
seedream_edit_image	图像编辑（SeedEdit 3.0）

API 开发教程 上传文件到 AceDataCloud 平台 CDN

把本地文件上传到 AceDataCloud 平台 CDN，获得一个永久可访问的 URL（https://cdn.acedata.cloud/xxxxxx.png 风格），可立即在其他业务接口（如 Midjourney、Suno、Flux）的 image_url、reference_url 等参数中引用。

适用场景：

在调用 Midjourney /midjourney/imagine 前先把垫图上传到 CDN 拿到 URL。
把上一步生成的视频缓存起来用作下一步的输入。
临时托管用户上传的素材，避免自建 S3。

ℹ️ 本接口属于 AceDataCloud 平台管理 API，统一前缀 https://platform.acedata.cloud/api/v1/。

接口概览

项	内容
方法	`POST`
URL	`https://platform.acedata.cloud/api/v1/files/`
鉴权	✅ 需要账户令牌
Content-Type	`multipart/form-data`（不是 JSON）

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

请求头：

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

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

请求体（multipart/form-data）

字段	类型	必填	说明
`file`	file	✅	二进制文件流。单文件上限默认 50 MB
`filename`	string	否	自定义文件名；不传则用 multipart 自带的文件名
`metadata`	string	否	JSON 字符串，挂在文件上的元数据（注意是字符串不是对象，因为 multipart 不支持原生嵌套 JSON）

请求示例

cURL

curl -X POST 'https://platform.acedata.cloud/api/v1/files/' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer platform-v1-92eb****629c' \
  -F 'file=@./photo.jpg'

Python

import requests

PLATFORM_TOKEN = "platform-v1-92eb****629c"

with open("photo.jpg", "rb") as f:
    resp = requests.post(
        "https://platform.acedata.cloud/api/v1/files/",
        headers={
            "accept": "application/json",
            "authorization": f"Bearer {PLATFORM_TOKEN}",
        },
        files={"file": ("photo.jpg", f, "image/jpeg")},
        timeout=60,
    )

data = resp.json()
print(f"✅ 上传成功：{data['url']}")
# 直接用于其他业务接口：
# requests.post("https://api.acedata.cloud/midjourney/imagine",
#     json={"prompt": "...", "image_urls": [data["url"]]}, ...)

Node.js

const fs = require('fs')
const FormData = require('form-data')

const form = new FormData()
form.append('file', fs.createReadStream('./photo.jpg'))

const r = await fetch('https://platform.acedata.cloud/api/v1/files/', {
  method: 'POST',
  headers: {
    authorization: 'Bearer platform-v1-92eb****629c',
    ...form.getHeaders(),
  },
  body: form,
})
const data = await r.json()
console.log('CDN URL:', data.url)

响应示例（HTTP 201）

{
  "id": "f-9c8b7a6d5e4f3a2b1c0d",
  "user_id": "89518d07-5560-4b05-92c1-667f3ddf6a4b",
  "filename": "photo.jpg",
  "size": 184729,
  "content_type": "image/jpeg",
  "url": "https://cdn.acedata.cloud/qrd7gw.jpg",
  "metadata": null,
  "created_at": "2026-04-26T08:30:00Z"
}

直接把 url 字段拿去其他业务接口里用就行——CDN 永久公开可访问，无需鉴权。

响应字段说明

字段	类型	说明
`id`	string	文件 ID
`user_id`	UUID	上传者用户 ID
`filename`	string	文件名
`size`	integer	字节数
`content_type`	string	MIME 类型
`url`	string	CDN 访问 URL
`metadata`	object \	null	自定义元数据（如果上传时传了 `metadata` 字段）
`created_at`	string	上传时间

错误处理

HTTP	code	含义
400	`invalid`	没附 `file` 字段、字段名不对、`metadata` 不是合法 JSON 字符串
401	`not_authenticated`	缺少账户令牌
413	`payload_too_large`	文件超过 50 MB（默认）

实用提示

上传图片做垫图：Midjourney image_urls、Flux image_url、Veo reference_url 都接受 CDN URL，不接受 base64。先用本接口拿 URL 是常规操作。
url 是永久 URL——目前没有自动清理策略，但敏感数据请勿上传。如有需求请联系客服设短期 TTL。
metadata 字段：multipart/form-data 不支持原生嵌套 JSON，传字符串：”{\"campaign\":\"summer\"}“，平台会反序列化。
大批量上传：推荐 2-4 个并发，单连接即可达到 ~10 MB/s。

API 开发教程 身份证识别及信息核验 API 对接说明

本文将介绍一种身份证识别及信息核验 API 对接说明，它可以通过输入身份证图片或姓名和身份证号码，来校验姓名和身份证号的真实性和一致性。本接口用于校验姓名和身份证号的真实性和一致性，您可以通过输入姓名和身份证号或传入身份证人像面照片提供所需验证信息。

申请流程

要使用 API，需要先到身份证识别及信息核验 API 对应页面申请对应的服务，进入页面之后，点击「Acquire」按钮，如图所示：

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

在首次申请时会有免费额度赠送，可以免费使用该 API。

基本使用

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

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

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

另外设置了 Request Body，包括：

image_url：需要处理的身份证图片链接。
encryption：可选，敏感字段加密参数（如需上送密文）。

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

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

{
  "result": "0",
  "description": "姓名和身份证号一致",
  "name": "身份证姓名",
  "id_card": "身份证号码",
  "sex": "身份证性别",
  "nation": "身份证民族",
  "birth": "身份证生日",
  "address": "身份证家庭住址"
}

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

result，认证结果码，收费情况如下。
- 收费结果码：
  - 0: 姓名和身份证号一致
  - -1: 姓名和身份证号不一致
- 不收费结果码：
  - -2: 非法身份证号（长度、校验位等不正确）
  - -3: 非法姓名（长度、格式等不正确）
  - -4: 证件库服务异常
  - -5: 证件库中无此身份证记录
  - -6: 权威比对系统升级中，请稍后再试
  - -7: 认证次数超过当日限制。
description，此处姓名与身份证号码验证的结果。
name，身份证中的姓名信息，如果没有上传身份证图片则是空的。
id_card，身份证中的身份证号码信息，如果没有上传身份证图片则是空的。
sex，身份证中的性别信息，如果没有上传身份证图片则是空的。
nation，身份证中的民族信息，如果没有上传身份证图片则是空的。
birth，身份证中的生日信息，如果没有上传身份证图片则是空的。
address，身份证中的家庭住址信息，如果没有上传身份证图片则是空的。

可以看出身份证中姓名与身份证号码的信息是一致性并且有效的，同时也使用OCR技术提取了其它的信息并展示出来。

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

curl -X POST 'https://api.acedata.cloud/identity/idcard/ocr' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "image_url": {image_url}
}'

Python 的对接代码如下：

import requests

url = "https://api.acedata.cloud/identity/idcard/ocr"

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

payload = {
    "image_url": {image_url}
}

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

自定义信息验证

我们也提供了一种不泄露身份证图片信息的方式来验证，可以只传入姓名name 和身份证号码 id_card 来进行校验姓名和身份证号的真实性和一致性，下面是填的具体信息：

点击运行后得到如下结果：

{
    "address": "",
    "birth": "",
    "description": "姓名和身份证号一致",
    "id_card": "身份证号码",
    "name": "身份证姓名",
    "nation": "",
    "result": "0",
    "sex": ""
 }

这样从结果看就不会泄露其它隐私信息了，这也可以完成校验姓名和身份证号的真实性和一致性。

错误处理

在调用 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.

错误响应示例

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

结论

通过本文档，您已经了解了如何使用身份证识别及信息核验 API 对输入的图片或姓名与身份证号码信息来进行校验姓名和身份证号的真实性和一致性。希望本文档能帮助您更好地对接和使用该 API。如有任何问题，请随时联系我们的技术支持团队。

作者崔庆才发表于 2026-05-31 阅读次数：本文字数： 2.7k 阅读时长 ≈ 2 分钟

API 开发教程 Sora Videos Generation API 对接说明

本文将介绍 Sora Videos Generation API 的对接说明，通过该 API 可以输入自定义参数来生成 Sora 官方的视频。本 API 支持两种版本模式：

Version 1（经典模式）：支持 duration（10/15/25 秒）、orientation（横屏/竖屏）、size（small/large 清晰度）、参考图 image_urls、角色视频 character_url 等参数。
Version 2（合作商模式）：支持 seconds（4/8/12 秒）、像素级分辨率 size（如 1280x720）、参考图 input_reference 等参数。

申请流程

要使用 API，需要先到 Sora Videos Generation API 对应页面申请对应的服务，进入页面之后，点击「Acquire」按钮，如图所示：

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

在首次申请时会有免费额度赠送，可以免费使用该 API。

基本使用（Version 1）

首先先了解 Version 1 的基本使用方式，就是输入提示词 prompt、参考图片链接数组 image_urls 以及模型 model，便可获得处理后的结果，具体的内容如下：

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

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

另外设置了 Request Body，包括：

model：生成视频的模型，支持 sora-2（标准模式）和 sora-2-pro（高清模式）。其中 sora-2-pro 可以支持 duration 为 25 秒的视频，而 sora-2 只支持 10、15 秒。
size：视频清晰度，small 为标准清晰度、large 为 HD 清晰度（仅 Version 1）。
duration：视频时长，支持 10、15、25 秒，其中 25 秒仅 sora-2-pro 支持（仅 Version 1）。
orientation：画幅方向，支持 landscape（横屏）、portrait（竖屏）（仅 Version 1）。
image_urls：参考图片链接数组，用于图生视频（仅 Version 1）。
character_url：角色视频链接，视频中不能出现真人（仅 Version 1）。
character_start/character_end：角色出现的起止秒数，范围差值为 1-3 秒（仅 Version 1）。
prompt：提示词（必填）。
callback_url：异步回调结果的 URL。
version：API 版本，"1.0"（默认）或 "2.0"。

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

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

{
  "success": true,
  "task_id": "6bf7fb83-5814-4e3e-a4ad-bfa0c26c0b33",
  "trace_id": "96166698-4b66-478d-a26b-77a7269c9e01",
  "data": [
    {
      "id": "sora-2:task_01k7770rgsevxsmtpbn7xnm5gh",
      "video_url": "https://filesystem.site/gptimage/vg-assets/assets%2Ftask_01k7770rgsevxsmtpbn7xnm5gh%2Ftask_01k7770rgsevxsmtpbn7xnm5gh_genid_0bf958d3-cae7-4298-b7b6-99ae439a1ea6_25_10_10_14_06_975715%2Fvideos%2F00000%2Fsrc.mp4?st=2025-10-10T12%3A30%3A38Z&se=2025-10-16T13%3A30%3A38Z&sks=b&skt=2025-10-10T12%3A30%3A38Z&ske=2025-10-16T13%3A30%3A38Z&sktid=a48cca56-e6da-484e-a814-9c849652bcb3&skoid=8ebb0df1-a278-4e2e-9c20-f2d373479b3a&skv=2019-02-02&sv=2018-11-09&sr=b&sp=r&spr=https%2Chttp&sig=jigY6Z5qp8%2BTXYobaW0EAJ4%2Fbx6G7t6V1P0iyDeUq48%3D&az=oaivgprodscus",
      "state": "succeeded"
    }
  ]
}

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

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

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

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

curl -X POST 'https://api.acedata.cloud/sora/videos' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "size": "large",
  "duration": 15,
  "orientation": "landscape",
  "prompt": "cat running on the river",
  "model": "sora-2"
}'

图生视频任务（Version 1）

如果想进行图生视频任务，首先参数 image_urls 必须传入参考图片链接，就可以指定如下内容：

image_urls：该图生视频任务采用的参考图链接数组。注意不可传递真实的带有头像的人物图像，否则可能导致任务失败。

填写样例如下：

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

对应的代码：

import requests

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

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

payload = {
    "size": "large",
    "duration": 15,
    "orientation": "landscape",
    "prompt": "cat running on the river",
    "model": "sora-2",
    "image_urls": ["https://cdn.acedata.cloud/11wfp4.png"]
}

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

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

{
  "success": true,
  "task_id": "dd392ff0-dcb7-4c7a-afd0-9bd4f65c803a",
  "trace_id": "04fd151c-e942-4c1c-a6ab-9a1b1fe54172",
  "data": [
    {
      "id": "sora-2:task_01k777af4hfmg9g7yfvwsc6zws",
      "video_url": "https://filesystem.site/gptimage/vg-assets/assets%2Ftask_01k777af4hfmg9g7yfvwsc6zws%2Ftask_01k777af4hfmg9g7yfvwsc6zws_genid_92bae0c5-1703-4a5f-9d9f-c9ed2f9e7176_25_10_10_14_12_924695%2Fvideos%2F00000%2Fsrc.mp4?st=2025-10-10T12%3A37%3A32Z&se=2025-10-16T13%3A37%3A32Z&sks=b&skt=2025-10-10T12%3A37%3A32Z&ske=2025-10-16T13%3A37%3A32Z&sktid=a48cca56-e6da-484e-a814-9c849652bcb3&skoid=aa5ddad1-c91a-4f0a-9aca-e20682cc8969&skv=2019-02-02&sv=2018-11-09&sr=b&sp=r&spr=https%2Chttp&sig=5j4dibeaSsDmEka5c%2B9CKHZhRPdqfClQ0tIh03TWXsM%3D&az=oaivgprodscus",
      "state": "succeeded"
    }
  ]
}

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

角色生成视频任务（Version 1）

如果想进行角色生成视频任务，首先参数 character_url 必须传入创建角色需要的视频链接，注意视频中一定不能出现真人，否则会失败，就可以指定如下内容：

character_url：创建角色需要的视频链接，注意视频中一定不能出现真人，否则会失败。

填写样例如下：

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

对应的代码：

import requests

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

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

payload = {
    "size": "small",
    "duration": 10,
    "orientation": "landscape",
    "prompt": "cat running on the river",
    "character_url": "https://cdn.acedata.cloud/pdidf5.mp4",
    "model": "sora-2",
    "character_end": 3,
    "character_start": 1
}

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

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

{
  "success": true,
  "task_id": "d9bf5461-29b5-47fd-be90-1fe9197df259",
  "trace_id": "b7992643-9207-40d6-956b-7577728acc67",
  "data": [
    {
      "id": "sora-2:task_01k8ykrztefavaypw6xanw305b",
      "video_url": "https://filesystem.site/cdn/20251101/bee4eeeb4c4660b46dac4548a1ffbc.mp4",
      "state": "succeeded"
    }
  ]
}

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

Version 2.0 模式

除了上述 Version 1.0 模式之外，本 API 还支持 Version 2.0 模式，通过设置 version 参数为 "2.0" 即可启用。Version 2.0 模式支持更短的视频时长和像素级的分辨率控制。

Version 2.0 参数说明

参数	类型	是否必填	说明
`version`	string	是	设置为 `"2.0"`
`prompt`	string	是	生成视频的提示词
`model`	string	否	`sora-2`（默认）或 `sora-2-pro`
`duration`	integer	否	视频时长：`4`（默认）、`8`、`12` 秒
`size`	string	否	分辨率：`720x1280`（默认）、`1280x720`、`1024x1792`、`1792x1024`
`image_urls`	array	否	参考图片 URL 数组，仅使用第一张图片，图片尺寸需要与 `size` 参数一致
`callback_url`	string	否	异步回调 URL

基本示例

curl -X POST 'https://api.acedata.cloud/sora/videos' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "version": "2.0",
  "prompt": "cat running on the river",
  "model": "sora-2",
  "duration": 8,
  "size": "1280x720"
}'

对应的 Python 代码：

import requests

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

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

payload = {
    "version": "2.0",
    "prompt": "cat running on the river",
    "model": "sora-2",
    "seconds": 8,
    "size": "1280x720"
}

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

对应的 JavaScript 代码：

const response = await fetch('https://api.acedata.cloud/sora/videos', {
  method: 'POST',
  headers: {
    'accept': 'application/json',
    'authorization': 'Bearer {token}',
    'content-type': 'application/json'
  },
  body: JSON.stringify({
    version: '2.0',
    prompt: 'cat running on the river',
    model: 'sora-2',
    seconds: 8,
    size: '1280x720'
  })
});
const data = await response.json();
console.log(data);

返回结果格式与 Version 1 相同：

{
  "success": true,
  "task_id": "6bf7fb83-5814-4e3e-a4ad-bfa0c26c0b33",
  "trace_id": "96166698-4b66-478d-a26b-77a7269c9e01",
  "data": [
    {
      "id": "c0cc8dad-0954-421f-be8d-02eb063b3263",
      "video_url": "https://platform.cdn.acedata.cloud/sora/xxxxx.mp4",
      "state": "succeeded"
    }
  ]
}

使用参考图片（Version 2.0）

在 Version 2.0 模式下，可以通过 image_urls 参数传入参考图片来引导视频生成（仅使用第一张图片）：

import requests

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

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

payload = {
    "version": "2.0",
    "prompt": "a person walking through a beautiful garden",
    "model": "sora-2",
    "duration": 4,
    "size": "1280x720",
    "image_urls": ["https://cdn.acedata.cloud/11wfp4.png"]
}

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

注意：参考图片的尺寸应与 size 参数保持一致，例如 size 为 1280x720 时，参考图片尺寸应为 1280×720。

Version 1.0 与 Version 2.0 参数对比

参数	Version 1.0	Version 2.0
`version`	1.0（默认）	2.0
`prompt`	✅	✅
`model`	✅ sora-2 / sora-2-pro	✅ sora-2 / sora-2-pro
`duration`	✅ 10/15/25 秒	✅ 4/8/12 秒
`orientation`	✅ landscape/portrait	❌
`size`	✅ small/large	✅ 720x1280/1280x720/1024x1792/1792x1024
`image_urls`	✅ 多张参考图	✅ 仅使用第一张
`character_url`	✅	❌
`callback_url`	✅	✅

异步回调

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

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

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

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

将此 URL 复制下来，就可以作为 Webhook 来使用，此处的样例为 https://webhook.site/eb238c4f-da3b-47a5-a922-a93aa5405daa。

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

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

1
2
3

{
  "task_id": "b8976e18-32dc-4718-9ed8-1ea090fcb6ea"
}

稍等片刻，我们可以在 https://webhook.site/eb238c4f-da3b-47a5-a922-a93aa5405daa 上观察到生成视频的结果，如图所示：

内容如下：

{
    "success": true,
    "task_id": "b8976e18-32dc-4718-9ed8-1ea090fcb6ea",
    "trace_id": "fb751e1e-4705-49ea-9fd4-5024b7865ea2",
    "data": [
        {
            "id": "sora-2:task_01k777hjrbfrgs2060q5zvf2a5",
            "video_url": "https://filesystem.site/gptimage/vg-assets/assets%2Ftask_01k777hjrbfrgs2060q5zvf2a5%2Ftask_01k777hjrbfrgs2060q5zvf2a5_genid_b8e2e5d1-a579-49ca-a21c-cb3869685cce_25_10_10_14_15_147334%2Fvideos%2F00000%2Fsrc.mp4?st=2025-10-10T12%3A38%3A49Z&se=2025-10-16T13%3A38%3A49Z&sks=b&skt=2025-10-10T12%3A38%3A49Z&ske=2025-10-16T13%3A38%3A49Z&sktid=a48cca56-e6da-484e-a814-9c849652bcb3&skoid=aa5ddad1-c91a-4f0a-9aca-e20682cc8969&skv=2019-02-02&sv=2018-11-09&sr=b&sp=r&spr=https%2Chttp&sig=p4aMqXqkP%2FI1IhOVGCB9JL8vUUvfNBBF12ESpKhKXOk%3D&az=oaivgprodscus",
            "state": "succeeded"
        }
    ]
}

可以看到结果中有一个 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.

错误响应示例

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

结论

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

作者崔庆才发表于 2026-05-31 阅读次数：本文字数： 10k 阅读时长 ≈ 9 分钟

API 开发教程 获取 AceDataCloud 平台服务下的 API 列表

通过服务 ID 获取该服务下挂载的全部 API 端点信息（路径、定价、阶段、关联文档等）。与获取 AceDataCloud 平台 API 列表的区别：本接口只返回指定一个服务下的 API，前者会跨服务返回全部 API。

适用场景：服务详情页右侧的「该服务包含的接口」面板、Agent 工具能力枚举、文档站点导航生成等。

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

接口概览

项	内容
方法	`GET`
URL	`https://platform.acedata.cloud/api/v1/services/{service_id}/apis/`
鉴权	❌ 公开

鉴权说明

本接口完全公开，无需账户令牌或登录态。

路径参数

参数	类型	必填	说明
`service_id`	UUID	✅	服务 ID。注意：必须是 UUID 格式，不支持 alias——这是历史遗留

⚠️ 这里和服务详情接口不一样：详情接口同时支持 UUID 和 alias，本接口只支持 UUID。如果你只有 alias，先调一次详情接口拿到 UUID 再用。

查询参数

参数	类型	必填	默认	说明
`limit`	integer	否	10	每页条数，最大 100
`offset`	integer	否	0	偏移
`stage`	string	否	—	按阶段过滤：`Alpha`/`Beta`/`Stable`/`Deprecated`
`ordering`	string	否	`rank`	排序字段，前缀 `-` 倒序

请求示例

cURL

curl 'https://platform.acedata.cloud/api/v1/services/8efa1d83-9b75-4562-b44a-af95ce563d05/apis/' \
  -H 'accept: application/json'

# 只看稳定版接口
curl 'https://platform.acedata.cloud/api/v1/services/8efa1d83-9b75-4562-b44a-af95ce563d05/apis/?stage=Stable' \
  -H 'accept: application/json'

Python

import requests

service_id = "8efa1d83-9b75-4562-b44a-af95ce563d05"
resp = requests.get(
    f"https://platform.acedata.cloud/api/v1/services/{service_id}/apis/",
    headers={"accept": "application/json"},
    params={"limit": 50},
    timeout=10,
)
data = resp.json()
print(f"该服务下共有 {data['count']} 个 API")
for api in data["items"]:
    print(f"  [{api['stage']:>10}] {api['title']:30s} {api['path']}")

Node.js

const serviceId = '8efa1d83-9b75-4562-b44a-af95ce563d05'
const r = await fetch(`https://platform.acedata.cloud/api/v1/services/${serviceId}/apis/`)
const { count, items } = await r.json()
console.log(`API 数: ${count}`)
items.forEach((api) => console.log(`${api.title} -> ${api.path}`))

响应示例（HTTP 200）

{
  "count": 7,
  "items": [
    {
      "id": "e4fbc3b6-4f44-48fb-a049-40f5c27c7cd3",
      "document_id": "20945baf-b263-457b-be5f-0332c2180a57",
      "service_id": "8efa1d83-9b75-4562-b44a-af95ce563d05",
      "name": "Face Analyze API",
      "title": "五官定位 API",
      "path": "/face/analyze",
      "path2": null,
      "introduction": "该API可用于对请求图片进行五官定位（也称人脸关键点定位），计算构成人脸轮廓的 90 个点。",
      "cost": [
        { "conditions": { "==": [1, 1] }, "consumption": 0.0025 }
      ],
      "stage": "Stable",
      "rank": 10,
      "tags": [],
      "metadata": null,
      "created_at": "2024-08-06T03:20:03.105765Z",
      "updated_at": "2026-04-26T16:16:56.579972Z"
    }
  ]
}

响应字段说明

字段	类型	说明
`count`	integer	符合条件的 API 总数
`items`	array	API 列表
`id`	UUID	API 唯一标识
`document_id`	UUID	关联的开发者文档 ID（可用于跳转获取 AceDataCloud 平台文档详情）
`service_id`	UUID	所属服务 ID（与路径参数相同）
`name`	string	API 英文名
`title`	string	API 显示标题（已本地化）
`path`	string	API 调用路径，业务接口前缀是 `https://api.acedata.cloud`，例如 `/face/analyze` 完整 URL 为 `https://api.acedata.cloud/face/analyze`
`path2`	string	备用路径，可能为 `null`
`introduction`	string	一段话简介
`cost`	array	定价规则（JsonLogic 格式）。`conditions` 匹配请求参数，匹配成功后用 `consumption` 计费
`stage`	string	生命周期阶段：`Alpha`、`Beta`、`Stable`、`Deprecated`
`rank`	integer	排序权重
`tags`	array	标签
`metadata`	object	扩展元数据
`created_at`	string	创建时间
`updated_at`	string	最近更新时间

ℹ️ 本接口不返回 definition（OpenAPI Schema）字段——schema 体量大且很少需要。要看 schema 请调用获取 AceDataCloud 平台 API 详情。

错误处理

HTTP	code	含义
400	`invalid`	`service_id` 不是合法 UUID 格式
404	`not_found`	服务不存在或已下线

实用提示

看到 stage=Deprecated 的 API 请勿在新项目使用，会在未来 6 个月内移除。
多 path 服务：少数服务（如 ChatDoc）有多套接口路径，本接口会返回多条记录。
自动生成 SDK：常见做法是先调 services/?type=Api，再对每个服务调本接口拿到 api_ids，最后调 /apis/{id} 拿 OpenAPI Schema 用 openapi-generator 生成客户端代码。

产品推广 OpenCode + Seedream MCP

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

字节跳动出品的图像模型，中文语义理解强，擅长国风、东方审美、写实摄影。通过 MCP 接入 OpenCode 后，可以直接在对话里调用，不用切窗口、不用复制粘贴。

获取 API Token

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

配置

编辑配置：~/.config/opencode/opencode.json

{
  "mcp": {
    "seedream": {
      "type": "remote",
      "url": "https://seedream.mcp.acedata.cloud/mcp",
      "headers": { "Authorization": "Bearer 你的Token" }
    }
  }
}

重启 OpenCode（或在会话内执行 /mcp reload）即可调用工具。

使用示例

用 Seedream 生成一幅中国风山水画：远山、溪流、茅草亭

生成一张国潮风插画：锦鲤跃出水面，背景祥云

把这张照片（链接 xxx）按文字指令修改（SeedEdit 3.0）

工具

工具	说明
seedream_generate_image	文生图（3.0 / 4.0 / 4.5 / 5.0）
seedream_edit_image	图像编辑（SeedEdit 3.0）

API 开发教程 Midjourney Edits API 对接说明

本文将介绍一种 Midjourney Edits API 对接说明，它是可以通过输入提示词来编辑传入的图片进行生成。

申请流程

要使用 API，需要先到 Midjourney Edits API 对应页面申请对应的服务，进入页面之后，点击「Acquire」按钮，如图所示：

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

在首次申请时会有免费额度赠送，可以免费使用该 API。

基本使用

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

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

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

另外设置了 Request Body，包括：

mask：可以指定图像区域的掩码位置以进行编辑和重新生成。
split_images：将生成的图像分割成多个图像，通过sub_image_urls字段返回。缺省情况下，为false。
action：此次编辑图片生成任务的行为，默认是 generate。
image_url：需要编辑的图片链接。
prompt：提示词。
mode：生成模式，可选 fast/relax/turbo。
callback_url：需要回调结果的URL。

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

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

{
  "sub_image_urls": [
    "https://cdn.midjourney.com/88e16dab-ef48-43a5-af73-bf24065287bc/0_0.png",
    "https://cdn.midjourney.com/88e16dab-ef48-43a5-af73-bf24065287bc/0_1.png",
    "https://cdn.midjourney.com/88e16dab-ef48-43a5-af73-bf24065287bc/0_2.png",
    "https://cdn.midjourney.com/88e16dab-ef48-43a5-af73-bf24065287bc/0_3.png"
  ],
  "image_url": "https://storage.fonedis.cc/attachments/1372468820912115716/1391371957878132849/cat_sitting_table_88e16dab-ef48-43a5-af73-bf24065287bc.png?ex=686ba79d&is=686a561d&hm=ad005d06f6673d6152456e04c3cbec39d062bd9df10448623fae27ddaf8b8a80&",
  "image_width": 960,
  "image_height": 1200,
  "raw_image_url": "https://storage.fonedis.cc/attachments/1372468820912115716/1391371957878132849/cat_sitting_table_88e16dab-ef48-43a5-af73-bf24065287bc.png?ex=686ba79d&is=686a561d&hm=ad005d06f6673d6152456e04c3cbec39d062bd9df10448623fae27ddaf8b8a80&",
  "raw_image_width": 960,
  "raw_image_height": 1200,
  "progress": 100,
  "image_id": "1391372193836826624",
  "task_id": "26c39859-f54a-4998-9e42-3da96eceee8c",
  "success": true
}

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

success，此时图片编辑生成任务的状态情况。
task_id，此时图片编辑生成任务ID。
image_id，此次图片编辑任务的图片ID。
sub_image_urls，图片生成任务的多个图片结果。
image_url，图片生成结果的图片链接。
image_width，图片生成结果的宽度。
image_height，图片生成结果的高度。
progress，此时图片编辑生成任务的进度字段。

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

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

curl -X POST 'https://api.acedata.cloud/midjourney/edits' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "prompt": "A cat sitting on a table",
  "split_images": true,
  "image_url": "https://cdn.acedata.cloud/jgo1cw.jpg",
  "action": "generate"
}'

异步回调

由于 Midjourney Edits 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/556e6971-b41f-4fa8-9151-6e91acd0399f。

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

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

1
2
3

{
  "task_id": "b8b7fdc2-628e-40dd-bc0c-671c3ddac9e9"
}

稍等片刻，我们可以在 https://webhook.site/556e6971-b41f-4fa8-9151-6e91acd0399f 上观察到生成视频的结果，如图所示：

内容如下：

{
    "sub_image_urls": [
        "https://cdn.midjourney.com/f3638ed2-60f6-49dd-897a-6d68c15afb17/0_0.png",
        "https://cdn.midjourney.com/f3638ed2-60f6-49dd-897a-6d68c15afb17/0_1.png",
        "https://cdn.midjourney.com/f3638ed2-60f6-49dd-897a-6d68c15afb17/0_2.png",
        "https://cdn.midjourney.com/f3638ed2-60f6-49dd-897a-6d68c15afb17/0_3.png"
    ],
    "image_url": "https://storage.fonedis.cc/attachments/1372468820912115716/1391374307719905340/cat_sitting_table_f3638ed2-60f6-49dd-897a-6d68c15afb17.png?ex=686ba9cd&is=686a584d&hm=71543c21c38db8a50c7ebcf54bc5208ec349e8592ec9e332f778f74167000ced&",
    "image_width": 960,
    "image_height": 1200,
    "raw_image_url": "https://storage.fonedis.cc/attachments/1372468820912115716/1391374307719905340/cat_sitting_table_f3638ed2-60f6-49dd-897a-6d68c15afb17.png?ex=686ba9cd&is=686a584d&hm=71543c21c38db8a50c7ebcf54bc5208ec349e8592ec9e332f778f74167000ced&",
    "raw_image_width": 960,
    "raw_image_height": 1200,
    "progress": 100,
    "image_id": "1391374390892953600",
    "task_id": "b8b7fdc2-628e-40dd-bc0c-671c3ddac9e9",
    "success": true
}

可以看到结果中有一个 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.

错误响应示例

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

结论

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

作者崔庆才发表于 2026-05-29 阅读次数：本文字数： 4.9k 阅读时长 ≈ 4 分钟

产品推广 Windsurf + NanoBanana MCP

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

基于 Gemini 的多模态图像模型，擅长理解复杂指令、精细编辑、连贯一致的角色。通过 MCP 接入 Windsurf 后，可以直接在对话里调用，不用切窗口、不用复制粘贴。

获取 API Token

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

配置

编辑配置：~/.codeium/windsurf/mcp_config.json

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

保存后在 Windsurf 中刷新 MCP 列表即可看到工具。

使用示例

用 NanoBanana 生成一只穿着宇航服的橘猫，在月球上吃汉堡

把这张人物照（链接 xxx）改成水墨画，保留人物特征

生成一张产品图：一杯冒着热气的咖啡，逆光，木桌，胶片质感

工具

工具	说明
nano_banana_generate	文生图（nano-banana / 2 / pro）
nano_banana_edit	图像编辑

产品推广 Claude Code + Google 搜索 MCP：终端里直接搜 Google，不用切浏览器

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

你在远程服务器上用 Claude Code 排查一个 OOM 问题。看到了一条不太熟悉的内核日志。以前只能复制错误信息，切到本地浏览器搜索，再切回终端。

但如果 Claude Code 能直接搜 Google 呢？

获取 API Token

使用 Serp MCP Server 之前，你需要一个 AceData Cloud 的 API Token。获取方式非常简单：

打开 AceData Cloud 平台，支持 GitHub、Google 或微信登录，注册后自动获得免费额度
登录后，在首页即可看到你的 API Token，点击复制按钮即可获取

AceData Cloud 平台首页 Token

如果额度用完，可以前往控制台充值，支持支付宝、微信和 Stripe

一个 Token 即可使用所有 MCP Server，无需为每个服务单独申请。

💡 如果你不想手动配置，也可以直接在 Claude.ai 网页版中使用，通过 OAuth 连接，无需 API Token。详见 Claude + Google Search MCP 图文教程。

配置 Claude Code

一行命令搞定：

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

⚠️ 注意： -H 必须大写。小写 -h 是 --help，不是 header 参数。

不加 -s 默认是 local scope，只在当前项目目录下生效。建议明确指定 scope：

Scope	命令参数	配置文件	作用范围
`local`（默认）	不加 `-s`，或 `-s local`	`~/.claude.json`	仅在运行命令时所在的项目目录下生效
`user`	`-s user`	`~/.claude.json`	全局生效，所有项目都能用
`project`	`-s project`	项目根目录 `.mcp.json`	仅当前项目，可提交到 git 共享给团队

将 你的Token 替换为上一步复制的 API Token。添加后 Claude Code 自动加载搜索工具。

典型场景

调试生产问题

SSH 到远程服务器，遇到不认识的错误码：

1	搜索 nginx error 502 bad gateway upstream sent too big header 怎么解决

不需要开浏览器，不需要断开 SSH。

技术选型调研

1	搜索一下 2025 年 Python 异步 ORM 的性能对比，SQLAlchemy 2.0 async vs Tortoise ORM

可以限定时间范围，只看最新结果。

查官方文档

1	搜索 Kubernetes CronJob concurrencyPolicy 的官方文档，Forbid 和 Replace 的区别

直接搜官方文档比凭记忆靠谱。

完整工具列表

工具	说明
serp_google_search	Google 搜索（网页/图片/新闻/视频等）

支持指定国家、语言、时间范围。

团队共享配置

项目根目录放 .mcp.json，团队 clone 后自动能用：

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

其他编辑器配置

Cursor — .cursor/mcp.json 中 mcpServers 下添加同样配置
VS Code — .vscode/mcp.json 中 servers 下添加同样配置
Windsurf — .windsurf/mcp.json，格式同 Cursor

产品推广 在 OpenAI Codex CLI 里用 AceData Cloud MCP — 终端 AI 工具全能配置

这是一篇总览文章：把 AceData Cloud 提供的 11 个 MCP Server 一次性接到 Codex CLI，让 OpenAI 的开源终端编程工具在写代码之余顺手生图、写歌、做视频。

Codex CLI 是 OpenAI 官方推出的开源终端 AI 编程助手，原生支持 MCP。

AceData Cloud 提供哪些 MCP Server？

我们把以下能力封装成托管式远程 MCP Server，开箱即用：

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

一个 AceData Cloud Token = 全部 11 个 MCP Server，统一计费、按调用扣费，无月费。

为什么 Codex CLI + MCP

OpenAI 官方维护，长期更新有保障
极简启动 codex，任何 shell 都能用
通过 MCP 调用 AceData Cloud，绕过模型本身的能力上限（写歌、生图、视频）

第 1 步：获取 API Token

打开 AceData Cloud 平台，支持 GitHub、Google、微信、邮箱、手机号登录，注册即送免费额度。
登录后首页就能看到你的 API Token，点击复制。

AceData Cloud 首页 Token

余额不足时去控制台 → 充值，支持支付宝、微信、Stripe。

第 2 步：在 Codex CLI 中添加 MCP

Codex CLI 用 TOML 格式的配置文件 ~/.codex/config.toml。在文件末尾追加：

[mcp_servers.suno]
url = "https://suno.mcp.acedata.cloud/mcp"
[mcp_servers.suno.headers]
Authorization = "Bearer 你的Token"

[mcp_servers.midjourney]
url = "https://midjourney.mcp.acedata.cloud/mcp"
[mcp_servers.midjourney.headers]
Authorization = "Bearer 你的Token"

[mcp_servers.flux]
url = "https://flux.mcp.acedata.cloud/mcp"
[mcp_servers.flux.headers]
Authorization = "Bearer 你的Token"

[mcp_servers.seedream]
url = "https://seedream.mcp.acedata.cloud/mcp"
[mcp_servers.seedream.headers]
Authorization = "Bearer 你的Token"

[mcp_servers.nanobanana]
url = "https://nanobanana.mcp.acedata.cloud/mcp"
[mcp_servers.nanobanana.headers]
Authorization = "Bearer 你的Token"

[mcp_servers.luma]
url = "https://luma.mcp.acedata.cloud/mcp"
[mcp_servers.luma.headers]
Authorization = "Bearer 你的Token"

[mcp_servers.sora]
url = "https://sora.mcp.acedata.cloud/mcp"
[mcp_servers.sora.headers]
Authorization = "Bearer 你的Token"

[mcp_servers.veo]
url = "https://veo.mcp.acedata.cloud/mcp"
[mcp_servers.veo.headers]
Authorization = "Bearer 你的Token"

[mcp_servers.seedance]
url = "https://seedance.mcp.acedata.cloud/mcp"
[mcp_servers.seedance.headers]
Authorization = "Bearer 你的Token"

[mcp_servers.serp]
url = "https://serp.mcp.acedata.cloud/mcp"
[mcp_servers.serp.headers]
Authorization = "Bearer 你的Token"

[mcp_servers.shorturl]
url = "https://shorturl.mcp.acedata.cloud/mcp"
[mcp_servers.shorturl.headers]
Authorization = "Bearer 你的Token"

替换 你的Token 后保存，下次启动 codex 时所有 MCP Server 自动加载。

第 3 步：试一试

配置完成后，重启编辑器 / CLI，让它重新加载 MCP Server。然后就可以这样用：

例 1（写完 PR 后生成 cover 图）：

用 Flux 生成一张 GitHub PR 封面，主题是”开源协作”，1280x640。

例 2（写技术博客时找资料）：

用 Serp 搜 “OpenAI Codex CLI tutorial 2026” 前 5 条最新文章。

例 3（demo 视频 BGM）：

用 Suno 写 45 秒平静钢琴曲做开发者教程 BGM。

计费与额度

按次扣费，不调用不花钱，无月费、无最低消费。
同一 Token 在所有 MCP Server 之间共享额度。
所有调用记录、剩余额度、消费明细可在控制台查看。
大用量需求可联系商务，享受批量价格。

常见问题

Q：可以只接入其中几个 MCP Server 吗？
A：当然，按需添加配置即可，没用到的就不加。

Q：有没有更便宜的接入方式？
A：直接调用 REST API 比 MCP 更便宜（少一层封装），但失去 MCP 在 LLM 工具调用上的便利。

Q：海外 / 跨境延迟问题？
A：所有 MCP Server 部署在香港，全球访问稳定；中国大陆直连无需代理。

Q：支持自托管吗？
A：MCP Server 全部开源在 GitHub，可自行部署。

产品推广 Claude.ai + Midjourney MCP：一句话调出 4 张高清概念图，亲测全流程

📘 完整指南：在 Claude.ai 网页版里用全部 11 个 AceData Cloud MCP →

想让 Claude 直接出图？不用切到 Discord，不用记 /imagine 命令，不用调任何参数。在 Claude.ai 聊天框里随手敲一句英文 prompt，Claude 自己会去调用 Midjourney，几十秒后把 2×2 网格图、放大、变体一并丢回来。

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

什么是 MCP？

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

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

从文字描述生成 Midjourney 2×2 网格图
放大（Upscale）任意一张到高分辨率
生成同主题的变体（Variations）
重新生成（Reroll）
局部修改（Vary Region / Inpaint）
缩放、扩图（Zoom Out / Pan）
翻译中文 prompt、补全 prompt
查询任务状态、获取历史结果

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

在 Claude.ai 网页版添加 Midjourney MCP

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

1. 打开 Connectors 设置

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

Claude.ai Customize Connectors

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

2. 添加 Midjourney MCP Server

点击 Add custom connector，在弹出对话框里填：

字段	值
Name	`Midjourney`（随便取）
URL	`https://midjourney.mcp.acedata.cloud/mcp`

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

3. OAuth 授权

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

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

授权完成后回到 Claude.ai，点开 Midjourney Connector，能看到 Imagine / Upscale / Variation / Reroll / Pan / Zoom / Vary Region / Translate / Get Task 等十多个工具：

Midjourney Connector 工具列表

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

实测：一句英文 Prompt 出图

下面是我真实跑出来的对话，提示词是英文（Midjourney 对英文 prompt 理解更稳定）：

Prompt: Use Midjourney to generate one image of a futuristic cyberpunk city skyline at night, neon lights reflecting on wet streets, cinematic, 16:9 aspect ratio.

Claude 收到后做的事情：

自动调用 imagine_midjourney，带上 prompt 和 --ar 16:9
拿到 task id，自己开始轮询 get_midjourney_task
约 1 分钟左右拿到 2×2 网格图（4 张候选），分辨率 2912×1632
把图片链接 + 文字总结一次性贴回聊天框，附带”要 upscale 哪张？要 variation 吗？”的后续提示

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

Claude.ai 中 Midjourney 生成结果

实际生成的 2×2 网格图（直接落到 platform.cdn.acedata.cloud，长期可用）：

Midjourney 2x2 网格图

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

常见问题

Q：为什么我点了 Always allow，新工具还是要确认？
A：Always allow 是按工具粒度记忆的。Imagine、Upscale、Variation、Get Task 是 4 个不同工具，第一次各确认一次即可。

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

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

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

产品推广 电影感，不再需要大团队：Veo 视频生成 API，把镜头语言交给 AI（含超多示例与图例）

想要一条“看起来就贵”的视频，以前意味着大量人力：分镜、拍摄、灯光、后期……时间长、成本高。Ace Data Cloud 的 Veo Videos API 让事情变得不同：

文生视频（text2video）：把你的镜头设想直接写成提示词；
图生视频（image2video）：用一张或多张参考图，生成自然衔接的动态；
1080p 升级（get_1080p）：对已生成视频再次升级清晰度；
多模型选择：veo2/veo2-fast/veo3/veo3-fast，在质量与速度间自由取舍。

关键链接

文档页：Veo Videos Generation API https://platform.acedata.cloud/documents/63e01dc3-eb21-499e-8049-3025c460058f
接口：POST https://api.acedata.cloud/veo/videos

可视化参数与界面示意

基本参数与模型选择：
自动生成代码视图：

一、案例合集（每个案例都含请求、返回与“可播放链接/字段”）

案例 1：文生视频（text2video）拍“旋转咖啡杯”的开场镜头

场景与镜头语言：主体白瓷咖啡杯、光滑大理石台面、清晨窗光、镜头缓慢 360° 围绕、把手处稍作停顿、节奏从容细腻。
输入（cURL）

curl -X POST 'https://api.acedata.cloud/veo/videos' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "action": "text2video",
    "model": "veo2",
    "prompt": "White ceramic coffee mug on glossy marble countertop with morning window light. Camera slowly rotates 360 degrees around the mug, pausing briefly at the handle."
  }'

输出（节选）

{
  "success": true,
  "task_id": "dd01fc69-e1f7-4b68-aa8c-463f6b748d11",
  "data": [
    {
      "id": "253eedc47f1c4eb2a370ed2312168f4b",
      "video_url": "https://platform.cdn.acedata.cloud/veo/dd01fc69-e1f7-4b68-aa8c-463f6b748d11.mp4",
      "created_at": "2025-07-25 16:07:43",
      "complete_at": "2025-07-25 16:10:28",
      "state": "succeeded"
    }
  ]
}

案例 2：图生视频（image2video）让静态海报“活起来”

用法：给现有 KV/海报做 5–8 秒的动态延展，用于短视频开场与社媒循环播放。
输入（Python，节选）

import requests
url = "https://api.acedata.cloud/veo/videos"
headers = {"accept": "application/json","authorization": "Bearer {token}","content-type": "application/json"}
payload = {
  "action": "image2video",
  "model": "veo2",
  "prompt": "Let it dance",
  "image_urls": ["https://cdn.acedata.cloud/7p1jhy.png"]
}
print(requests.post(url, json=payload, headers=headers).text)

输出（节选）

{
  "success": true,
  "task_id": "98e309f3-35bc-438d-8cb3-4015fc864b87",
  "data": [
    {
      "id": "59f12222b1fa4fbe9331ff2400ad1583",
      "video_url": "https://platform.cdn.acedata.cloud/veo/98e309f3-35bc-438d-8cb3-4015fc864b87.mp4",
      "state": "succeeded"
    }
  ]
}

表单填写与自动生成代码界面（示意）：

案例 3：1080p 升级（get_1080p）让“胜出版本”更清晰

背景：A/B 后选出表现最好的视频，升级到 1080p 用于投放或大屏播放。
查找 video_id（界面示意）：
输入（cURL）

curl -X POST 'https://api.acedata.cloud/veo/videos' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "action": "get_1080p",
    "model": "veo2",
    "video_id": "59f12222b1fa4fbe9331ff2400ad1583"
  }'

输出（节选）

{
  "success": true,
  "task_id": "47a51cfe-2e24-4aba-93b3-546c2dc52984",
  "data": [
    {
      "id": "59f12222b1fa4fbe9331ff2400ad1583",
      "video_url": "https://platform.cdn.acedata.cloud/veo/47a51cfe-2e24-4aba-93b3-546c2dc52984.mp4",
      "state": "succeeded"
    }
  ]
}

案例 4：品牌栏目片头模板化（多模型与参数切换）

做法：

文案模板：

1	"<brand keywords> opening sequence, logo reveal with dynamic light streaks, camera push-in then slow orbit, elegant, premium, cinematic lighting"

模型策略：veo2-fast 先快速验证、veo3/veo3-fast 出高质量版本；
比例适配：横版/竖版封面双版本，便于多渠道分发。

案例 5：产品短片（雾面玻璃手机 + 背景流光）

Prompt（可复用）：

1	"matte glass smartphone floating above a minimal pedestal, moody rim light, soft volumetric glow, background light trails sweeping left to right, 6-second loop, camera slow dolly-in, cinematic"

路径：先 text2video → 若出现理想关键帧，导出为首帧再试 image2video。

二、常见工作流（从灵感到成片）

写镜头语言：主体/光线/机位/运动/节奏；
生成多个版本做“眼缘筛选”与小额投放测试；
胜出版本做 1080p 升级；
素材落库：保存 video_url、model、prompt、created_at、complete_at 等字段；
形成“镜头模板库”，后续按主题套用。

三、提示词与参数技巧（更稳更像你想要的）

镜头：slow orbit、dolly-in、pan、tilt、rack focus、time-lapse；
光线：golden hour、studio lighting、rim light、soft glow、volumetric；
质感：matte、glossy、aluminium、velvet、ceramic；
节奏：slow/fast, loop, 3–6 seconds；
模型策略：veo2-fast 探索、veo3-fast 上量、veo3 上质。

四、开发者速通（3 步接入）

在文档页点击 Acquire 获取凭证（一般附带免费额度）。
调用 POST /veo/videos：传 action、model、prompt/image_urls/video_id；
关注返回：video_url 成品链接、created_at/complete_at 用于排期追踪。

五、典型落地场景

品牌与广告：开场片头、节日主题片、产品镜头；
媒体与创作者：栏目包装、Logo 动效、封面循环背景；
产品与 UI：App/网站/线下屏的高级动效背景。

六、合规与建议

版权与素材：确保参考图片/元素具有合法使用权限；
平台规范：遵守分发渠道的视频规范与内容政策；
成本优化：先用 fast 模型验证方向，成片再升质量与清晰度。

现在就把“看上去很贵”，变成“人人配得起”

Veo 文档页：https://platform.acedata.cloud/documents/63e01dc3-eb21-499e-8049-3025c460058f
接口：POST https://api.acedata.cloud/veo/videos

适合谁

品牌与广告：
- 做“带镜头”的产品短片，旋转、跟拍、推拉摇移都能准确描述；
- 节日与节点活动，快速形成有质感的主视觉视频。
媒体与创作者：
- 做栏目片头/片尾，用同一套镜头语言形成稳定识别；
- 以静帧作画，再生成动态，保持风格统一。
产品与 UI：
- 为 App/网站/线下屏制作高端动效背景，显著提升“第一观感”。

你的第一条电影感短片，这么写

提示词建议包含：主体 + 场景 + 光线 + 镜头运动 + 节奏

示例：

“白瓷咖啡杯放在光滑的大理石台面上，清晨的窗光洒入，镜头缓慢围绕杯身 360° 旋转，在把手处稍作停顿，节奏从容，质感细腻。”

这正是 Veo 擅长的表达方式：你说镜头，它就给你镜头。

工作流范式

文生视频：把镜头语言写清楚，一次生成多个版本；
图生视频：用首尾帧或关键画面，生成逻辑更清晰的动态；
升级 1080p：对“胜出版本”做高清升级，用于投放或大屏播放；
落库分发：把 video_url、created_at、model 等信息归档，形成复用资产。

接入流程

在 Ace Data Cloud 平台打开 Veo 文档页，点击 Acquire 获取凭证（一般附带免费额度）；
发起任务：设置 action（text2video/image2video/get_1080p）、选择 model，传入 prompt 或 image_urls；
结果回调：生成需要时间，建议配置 callback_url，自动接收 video_url 成品。

真实片段

一家咖啡品牌用 Veo 生成“旋杯”短片，上线首页与门店竖屏；同主题做四季版本（清晨/午后/雨夜/雪日），配合文案轮播，线下停留时长与线上点击率同步上升。

把看上去很贵，变成人人配得起

进入 Ace Data Cloud，开通 Veo API。写下你的第一条镜头指令，下一支高质感短片，从今天开始。

作者崔庆才发表于 2026-05-26 阅读次数：本文字数： 4.6k 阅读时长 ≈ 4 分钟

工作原理

5 分钟实操

第 1 步：进入 Subsite 管理

第 2 步：创建一个 Subsite

第 3 步：上传品牌资产

第 4 步：调整功能开关

第 5 步：把入口给客户

自定义域名

常见问题

相关链接

申请流程

基本使用

自定义搜索类型

自定义搜索资源所在国家

自定义搜索结果语言

自定义搜索结果时间范围

自定义搜索结果分页

获取 API Token

配置 OpenCode

全局：所有项目共用

项目级：仅当前项目生效

真实运行结果

典型场景

工具列表

相关链接

申请流程

基本使用

motion_type 支持值

计费说明

异步回调

申请流程

基本使用

错误处理

错误响应示例

结论

申请流程

基本使用

错误处理

错误响应示例

结论

为什么是 Pika

三类典型用法

工作流建议：轻量但高效

接入 3 步走

真实案例

现在就让你的内容动起来

接口概览

鉴权说明

查询参数

请求示例

cURL

Python

Node.js

响应示例（HTTP 200）

响应字段说明

错误处理

实用提示

相关接口

申请流程

模型说明

基本使用

图生视频

参考图引导

异步回调

查询任务结果

计费说明

错误处理

配置

使用示例

工具

相关链接

接口概览

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

请求体

请求示例

cURL

Python

Node.js

响应示例（HTTP 202）

响应字段说明

`motion_type` 支持值

支持的 `size` 取值

升级到旗舰模型 `nano-banana-pro`

图片质量参数 `quality`

图片大小尺寸参数 `size`

图片风格参数 `style`

图片链接的格式参数 `response_format`