把工作台的引擎,
直接接进你自己的系统。
一套 REST API,产出和工作台完全一致的商品主图、详情页图组、营销海报与短视频。密钥鉴权,JSON 进 JSON 出,积分消耗按模式固定——接进 ERP、刊登工具或独立站后台,成本能提前算清楚。
- 6 个接口
- Bearer 密钥鉴权
- 60 次 / 分钟
- 与工作台共用积分
发起一次生成
POST /v1/generations传入模式、目标平台和提示词,接口会立刻返回一个排队中的任务,不会卡住你的调用线程。之后轮询任务状态(或申请开通回调)即可拿到产出。
# 发起一次主图生成:模式 + 目标平台 + 提示词
curl -X POST https://api.tukaopu.cn/v1/generations \
-H "Authorization: Bearer $MERIDIAN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"mode": "main-image",
"platform": "amazon",
"prompt": "Stainless steel water bottle on warm stone, soft morning light",
"ratio": "1:1",
"language": "en",
"variants": 4
}'// 接口立即返回一个排队中的任务,不会阻塞你的下单流程
const res = await fetch("https://api.tukaopu.cn/v1/generations", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.MERIDIAN_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
mode: "main-image", // 模式:main-image | listing | poster | video
platform: "amazon", // 目标平台,决定构图与安全区
prompt: "Stainless steel water bottle on warm stone, soft morning light",
ratio: "1:1", // 比例:1:1 | 4:5 | 3:4 | 9:16 | 16:9
language: "en", // 图上文案语种
variants: 4, // 出图方案数
}),
});
const { task } = await res.json();
console.log(task.id, task.status); // "tsk_8f2c1a91", "queued"{
"task": {
"id": "tsk_8f2c1a91",
"status": "queued",
"mode": "main-image",
"platform": "amazon",
"credits_cost": 24,
"created_at": "2026-07-21T14:02:11.000Z"
}
}轮询拿结果
GET /v1/tasks/:id任务状态依次流转:queued 排队中 → running 生成中 → succeeded 已完成(失败为 failed,取消为 canceled)。多数任务 12–25 秒完成,每 1–2 秒轮询一次足够。任务失败时积分自动退回余额。
# 用任务 id 查询进度与产出
curl https://api.tukaopu.cn/v1/tasks/tsk_8f2c1a91 \
-H "Authorization: Bearer $MERIDIAN_API_KEY"// 每 1–2 秒轮询一次即可,多数任务 12–25 秒完成
const res = await fetch(
`https://api.tukaopu.cn/v1/tasks/${task.id}`,
{ headers: { Authorization: `Bearer ${process.env.MERIDIAN_API_KEY}` } }
);
const { task: updated } = await res.json();
if (updated.status === "succeeded") {
for (const output of updated.outputs) {
console.log(output.url); // 带签名的下载地址,24 小时内有效
}
}{
"task": {
"id": "tsk_8f2c1a91",
"status": "succeeded",
"progress": 100,
"outputs": [
{
"id": "out_2b7e04",
"url": "https://cdn.tukaopu.cn/outputs/tsk_8f2c1a91/0.png",
"width": 1200,
"height": 1200
}
],
"finished_at": "2026-07-21T14:02:34.000Z"
}
}11 个精修工具,一个接口全覆盖
把工具标识拼在路径上就能调用:background-removal 抠图换背景、upscale 高清放大、enhance 画质增强、outpaint 智能扩图、inpaint 局部重绘、translate 图片翻译、layer-split 图层拆分、text-recognition 文字识别,以及 video-subtitle-erase 视频去字幕、video-upscale 视频高清、video-translate 视频翻译。统一 8 积分一次,返回结构与生成接口一致。
# 调用单个 AI 工具:抠图换背景,统一 8 积分
curl -X POST https://api.tukaopu.cn/v1/tools/background-removal \
-H "Authorization: Bearer $MERIDIAN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"asset_id": "ast_51c9d0",
"background": "white"
}'鉴权、限流与计费
Bearer 密钥鉴权
每个请求在 Authorization 头里带上控制台创建的密钥。密钥完整值只在创建时显示一次,请存进环境变量,切勿写进前端代码或提交到代码仓库。
限流规则
单个密钥每分钟 60 次请求,允许短时突发。超限返回 429,响应头 Retry-After 会告诉你还要等多少秒,按提示退避重试即可。
积分与计费
接口调用和工作台共用同一份积分余额:生成按模式扣 24–120 积分,工具统一 8 积分。余额不足会在开始干活前返回 402,不会产生半截任务。
幂等与重试
POST 请求可带 Idempotency-Key 头,网络超时后用同一个 key 重试不会重复扣积分,返回的仍是第一次创建的那个任务。
回调通知
不想轮询可以申请开通回调:任务完成后我们把完整任务对象 POST 到你指定的地址,并附带签名头供你校验来源。
数据与留存
产出的下载地址带签名,默认 24 小时内有效,过期可重新获取。上传的素材只用于为你生成结果,不会用于训练模型或提供给其他用户。
全部就这六个接口
v1 版本的完整能力:生成、工具、账户状态。没有别的概念要学,半小时能跑通全流程。
| 方法 | 接口路径 | 说明 | 消耗 |
|---|---|---|---|
| POST | /v1/generations | 按提示词发起一次生成:商品主图、详情页图组、营销海报或短视频。 | 24–120 积分 |
| GET | /v1/tasks/{id} | 查询单个任务的状态、进度,完成后返回全部产出。 | 免费 |
| GET | /v1/tasks | 按时间倒序列出你的历史任务,支持按状态与模式筛选。 | 免费 |
| POST | /v1/tools/{slug} | 对单张图片或单段视频调用一个 AI 工具:抠图、放大、扩图、翻译等。 | 8 积分 |
| GET | /v1/outputs/{id} | 获取某个产出的签名下载地址、尺寸信息与来源任务。 | 免费 |
| GET | /v1/account | 查询当前积分余额、生效中的套餐,以及密钥的限流状态。 | 免费 |
所有响应均为 JSON。错误响应统一为 { "error": { "code", "message" } },message 为中文说明,可直接透传给你的运营同事看。
出错时会返回什么
HTTP 状态码与业务错误码一一对应,照着处理即可,不需要解析文案。
- 400
- 参数校验不通过,比如模式、平台或比例不在允许的取值范围内
- invalid_request
- 401
- 密钥缺失、格式错误或已被吊销,请检查 Authorization 头
- unauthorized
- 402
- 积分余额不足,任务未创建也未扣费;兑换卡密补足后重试即可
- insufficient_credits
- 404
- 任务、产出或工具标识不存在,也可能是它不属于当前密钥所在账号
- not_found
- 429
- 触发限流,请按响应头 Retry-After 指定的秒数退避后重试
- rate_limited
- 500 / 503
- 服务端异常或生成集群繁忙,已扣的积分会自动退回,建议指数退避重试
- server_error
接口版本一旦发布即保持向后兼容;新增字段不视为破坏性变更,请在解析响应时忽略未知字段。若确需破坏性调整,我们会启用新的版本前缀,并提前至少 90 天邮件通知在用的密钥所有者。
创建一把密钥,十分钟跑通全流程
在控制台自助创建密钥,照着上面的示例发第一个请求,几十秒后就能拿到可以直接上架的图。
接口调用与工作台共用积分余额,积分可在发卡平台购买卡密后回站内兑换。
