开发者

API 文档

用 API Key 在你自己的服务器上调用牛来AI智能体的生成能力：提交图片、视频、数字人等任务，查询进度，下载结果。API 和网页共用一个账户，按同样的价格扣积分。

创建 API Key 充值积分

接口地址: https://niulaiai.top/api/v1
认证: Authorization: Bearer sk-…
格式: JSON（UTF-8）

简介与计费

所有接口都在 https://niulaiai.top/api/v1 下。生成是异步的：提交后马上返回任务，生成在后台进行；你的程序轮询任务状态，完成后下载结果文件。

1
报价
用 POST /credits/quote 算出要花多少积分，不扣费。
2
提交
用 POST /batches 提交任务，扣积分并进入队列。
3
轮询
用 GET /batches/{id} 每 3–5 秒查一次状态。
4
下载
从 results[].asset.url 下载生成的文件。

约定

请求体是 JSON 的接口，请带 Content-Type: application/json。
时间都是 UTC 的 ISO 8601 字符串，例如 2026-10-15T08:30:12.418Z。任务、素材等 ID 都是 UUID。

认证

每个请求都用 API Key 认证。Key 代表你的账户、可以花你的积分，请像密码一样保管。

创建 Key

在网站登录后打开「API Key」页面，填一个名称后创建。每个账号最多同时有 10 个有效的 Key。
完整的 Key（sk- 开头）只在创建时显示一次，服务器只保存它的哈希。没保存下来的话，撤销后重新创建一个。
撤销后立即失效，之后用它发起的请求返回 401。

发送请求

在请求头里带上 Key：

请求头

Authorization: Bearer sk-你的Key

必须是 Bearer（B 大写）加一个空格，再接完整的 Key，前后不要有多余空格，否则会被当作未登录，返回 401。

试一下：查询积分余额

curl -s "https://niulaiai.top/api/v1/usage/summary" \
  -H "Authorization: Bearer sk-你的Key"

权限

Key 可以调用本文列出的全部接口，和你在网页上登录后的权限一样，生成会消耗账户积分。
为了安全，Key 不能调用账号设置接口（/api/v1/me/…，例如绑定手机号、创建或撤销 Key）和管理后台接口，这些请求返回 403 forbidden。这些操作请在网页上登录后进行。

快速开始

用 curl 和 jq 走一遍完整流程：报价 → 提交一个生成 2 张图片的任务 → 轮询到完成 → 下载图片。在同一个终端里按顺序执行，前面设置的变量后面会接着用。

0. 准备

设置站点地址和 Key

export BASE="https://niulaiai.top"
export API_KEY="sk-你的Key"

示例用到 curl 和 jq（macOS：brew install jq；Ubuntu：sudo apt install jq）。

1. 报价

请求

BODY='{
  "tool_slug": "image-generation",
  "prompt": "白色陶瓷咖啡杯放在原木桌上，清晨自然光，商业摄影",
  "params": { "ratio": "1:1", "resolution": "2K", "count": 2 }
}'

curl -s "$BASE/api/v1/credits/quote" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d "$BODY"

响应 200

{
  "credits": 24,
  "breakdown": [{ "label": "LC Image 2.5 Pro · 2K × 2", "credits": 24 }],
  "balance": 1060.5,
  "sufficient": true
}

credits 是这次要花的积分；sufficient 为 false 表示余额不够，这时提交会返回 402。这里没传 model_key，用的是图片创作的默认模型。

2. 提交任务

请求

RES=$(curl -s "$BASE/api/v1/batches" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d "$BODY")
BATCH_ID=$(echo "$RES" | jq -r '.id // empty')
if [ -z "$BATCH_ID" ]; then echo "提交失败：$(echo "$RES" | jq -r '.message')"; fi

echo "$RES" | jq '{id, status, creditsCharged, results: [.results[] | {index, status}]}'

响应 201（节选）

{
  "id": "5f0c8a3e-2b7d-4c19-8e6a-1d4b7f9a2c60",
  "status": "queued",
  "creditsCharged": 24,
  "results": [
    { "index": 0, "status": "queued" },
    { "index": 1, "status": "queued" }
  ]
}

返回 201 和任务对象，积分已经扣除。2 张图片是同一个任务里的 2 个结果（），各自生成、各自计费，哪张失败就退哪张的积分。

接口参考

除「可用模型」外，所有接口都要带 API Key。路径里的 {id} 换成实际的 ID。上传素材的 3 个接口见上传素材。

报价

POST/api/v1/credits/quote

计算一次提交要花多少积分，不扣费、不创建任务。请求体和提交任务完全相同，参数不合法时返回的错误也相同，可以用来提前校验参数。

响应字段

credits number: 这次提交要扣的积分
breakdown array: 明细，每项 { label, credits }，例如「模型 · 分辨率 × 张数」
balance number: 当前可用积分（订阅积分 + 充值积分）

工具与参数

用 tool_slug 选择工具，params 传参数，references 传参考素材。参数不满足要求时，报价和提交都会返回错误，所以可以先用报价接口试参数。

工具一览

video-generation AI 视频 · 可选视频模型: 文字或参考素材生成视频，见视频创作。
image-generation AI 图片 · 可选图片模型: 文字或参考图生成图片，见图片创作。
image-edit 图片精修 · 可选图片模型: 精修一张图：references 放 1–5 张图片（图1 是要修的图），prompt 写修改要求；params 可传 resolution、format、ratio（同图片创作）。

上传素材

参考图片、视频、音频要先上传成为素材，提交任务时再用 references[].asset_id 引用。上传分 3 步：申请上传地址 → 把文件 PUT 到这个地址 → 确认上传。

支持的文件

图片 最大 30 MB: PNG、JPEG、WebP、GIF（image/png、image/jpeg、image/webp、image/gif）。不支持 SVG、HEIC 等格式
视频 最大 1 GB: video/ 开头的常见格式，例如 mp4（video/mp4）、mov（video/quicktime）
音频 最大 100 MB: audio/ 开头的常见格式，例如 mp3（audio/mpeg）、wav（audio/wav）、m4a（audio/mp4）

第 1 步：申请上传地址

POST/api/v1/assets/upload-policy

请求体

错误码

出错时返回 4xx 或 5xx 状态码和下面格式的 JSON。message 是可以直接展示给用户的中文说明（部分字段格式错误是英文），code 供程序判断，detail 是附加信息，没有时为 null。

402 积分不足

{
  "message": "积分不足：需要 24 积分，当前可用 10.5 积分",
  "code": "insufficient_credits",
  "detail": { "need": 24, "have": 10.5 }
}

400 bad_request: 请求不合法：请求体不是 JSON、分页游标无效，或参数不满足工具的要求（例如「请输入图片内容」「请上传一个视频」），具体原因见 message。
400 unknown_tool: tool_slug 不存在。
400 no_model: 这个工具暂时没有可用的模型。
400 invalid_model: model_key 不能用于这个工具（拼写错误、已下线，或给不选模型的工具传了 model_key）。
400 model_unavailable: 模型服务暂未配置，暂时不能使用。
400 invalid_skill

最佳实践

先报价再提交。报价不扣费，sufficient 为 false 时不要提交；也可以用它在提交前校验参数。
每 3–5 秒轮询一次。图片一般几十秒，视频一般 1–3 分钟，开启超级编导多等约半分钟。给轮询设一个上限，不要无限循环；单个结果超过 4 小时没完成会自动失败并退回积分。
多个任务一起查。用 GET /api/v1/batches?ids=… 一次最多查 50 个任务，不要每个任务单独轮询。
处理 402。积分不足时任务没有创建，提示用户到网站充值后再提交，不要自动重试。积分只能在网站上充值。
避免重复扣费。5 秒内完全相同的提交只算一次，超过 5 秒的重试会创建新任务、再扣一次积分。提交请求超时或断网时，先用 GET /api/v1/batches?limit=10 看任务是否已经创建（可以用 title 放你的订单号来辨认），再决定是否重试。要多张图片请用 count，不要并发提交多个相同请求。
503 和 5xx 稍后重试。service_unavailable 表示 AI 服务维护中，这次没有扣积分，过几分钟再试；查询类请求遇到 5xx 可以直接重试。
及时保存结果。任务完成后把文件下载到你自己的存储；删除任务会一起删除它生成的文件。
API Key 只放在服务器上。用环境变量或密钥管理服务保存，不要写进网页前端、App、小程序或代码仓库。浏览器里也调不通：接口不返回跨域（CORS）响应头，带其他网站 Origin 的写请求会被拒绝。Key 泄露后立即在「」页面撤销并换新；不同程序用不同的 Key，方便单独撤销。

积分是数字，可能带小数，例如 2.7。

results

请求

for i in $(seq 1 150); do   # 每 4 秒查一次，最多等 10 分钟
  BATCH=$(curl -s "$BASE/api/v1/batches/$BATCH_ID" -H "Authorization: Bearer $API_KEY")
  STATUS=$(echo "$BATCH" | jq -r '.status')
  echo "$(date +%T) $STATUS"
  case "$STATUS" in completed|partial|failed|canceled) break ;; esac
  sleep 4
done

请求

echo "$BATCH" | jq -r '.results[] | select(.status == "completed") | .asset.url' |
while read -r URL; do
  case "$URL" in /*) URL="$BASE$URL" ;; esac   # 以 / 开头的是本站地址
  curl -sL -O "$URL"
done

# 失败的结果和原因
echo "$BATCH" | jq -r '.results[] | select(.status == "failed") | "\(.index) \(.error)"'

请求

curl -s "$BASE/api/v1/credits/quote" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tool_slug": "image-generation",
    "prompt": "白色陶瓷咖啡杯放在原木桌上，清晨自然光，商业摄影",
    "params": { "ratio": "1:1", "resolution": "2K", "count": 2 }
  }'

提交任务

POST/api/v1/batches

校验参数，按报价扣除积分并创建任务，立即返回；生成在后台进行。

请求体

tool_slug string · 必填: 工具标识，见工具一览。
model_key string: 模型，取可用模型返回的 key。不传时用这个工具的默认模型。只有图片、视频类工具可以选模型，其他工具不要传。
prompt string: 提示词，最多 12000 字。是否必填取决于工具。
params object: 工具参数，见工具与参数。没传的字段用默认值，不认识的字段会被忽略。
references array: 参考素材，最多 60 个，每项的字段见下表。素材要先上传，见上传素材。
skill_key string: 技能（网页上的「技能」，例如商品白底图）。从 GET /api/v1/tools/{tool_slug}/skill-packs 返回的 skills[].key 获取；技能需要的素材用 references[].slot 对应它的 slots[].name。不用技能就不传。
title string: 任务标题，最多 80 字，不传时取提示词的前 40 字。可以放你自己的订单号，方便对账。

references[] 每项

asset_id string · 必填: 素材 ID：确认上传完成的素材，或之前生成的结果。必须属于你的账号。
slot string: 素材的用途名，最多 40 字。数字人的形象素材必须填「形象」；用技能时填技能要求的名称。图片创作会把它写进参考图说明，例如「图1（模特）」。
label string: 显示名，最多 40 字。不传时按类型编号：图片1、视频1、音频1…
role string: 视频创作中图片的用法：first_frame（首帧）、last_frame（尾帧）、reference_image（参考图），不传时按模型默认。另有 reference_video、reference_audio 两个值，但视频和音频按类型处理，一般不用传。

防重复提交：5 秒内用同一账号提交完全相同的请求体，会直接返回第一次创建的任务，不会重复扣费。如果第一次提交失败了（例如积分不足），可以马上重试。

返回 201 和任务对象（字段见查询任务）。常见错误：400 参数不满足工具的要求（message 会说明原因）、402 积分不足、404 引用的素材不存在或未确认上传、422 字段格式不对、503 AI 服务维护中（没有扣积分）。

请求

curl -s "$BASE/api/v1/batches" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tool_slug": "image-generation",
    "prompt": "白色陶瓷咖啡杯放在原木桌上，清晨自然光，商业摄影",
    "params": { "ratio": "1:1", "resolution": "2K", "count": 2 }
  }'

响应 201

{
  "id": "5f0c8a3e-2b7d-4c19-8e6a-1d4b7f9a2c60",
  "toolSlug": "image-generation",
  "taskType": "image_generation",
  "status": "queued",
  "title": "白色陶瓷咖啡杯放在原木桌上，清晨自然光，商业摄影",
  "prompt": "白色陶瓷咖啡杯放在原木桌上，清晨自然光，商业摄影",
  "params": {
    "ratio": "1:1",
    "resolution": "2K",
    "quality": "高",
    "format": "PNG",
    "count": 2
  },
  "skillKey": null,
  "modelKey": "image.lc-2.5-pro",
  "modelLabel": "LC Image 2.5 Pro",
  "references": [],
  "creditsCharged": 24,
  "creditsRefunded": 0,
  "tags": [],
  "favorite": false,
  "errorMessage": null,
  "canvasId": null,
  "canvasNodeId": null,
  "conversationId": null,
  "createdAt": "2026-10-15T08:30:12.418Z",
  "finishedAt": null,
  "results": [
    {
      "id": "fda6bac3-6371-4b6c-9de7-013c5a492cf8",
      "index": 0,
      "status": "queued",
      "phase": null,
      "error": null,
      "asset": null,
      "text": null,
      "json": null,
      "finalPrompt": null,
      "startedAt": null,
      "finishedAt": null,
      "etaSeconds": 30
    },
    {
      "id": "d6202845-11f7-4de5-989b-b212068f4f87",
      "index": 1,
      "status": "queued",
      "phase": null,
      "error": null,
      "asset": null,
      "text": null,
      "json": null,
      "finalPrompt": null,
      "startedAt": null,
      "finishedAt": null,
      "etaSeconds": 30
    }
  ]
}

查询任务

GET/api/v1/batches/{id}

返回任务的最新状态和结果。任务不存在或不属于你的账号时返回 404。

任务对象

id string: 任务 ID
toolSlug string: 工具标识
taskType string: 任务类型，例如 image_generation、video_generation、video_director
status string: queued 排队中、processing 生成中；completed 全部成功、partial 部分成功、failed 失败（没有一个成功）、canceled 全部取消。后四种表示任务已结束，不会再变。
title / prompt string: 任务标题和提示词
params object: 校验后的参数，补全了默认值
skillKey / modelKey / modelLabel string | null: 使用的技能、模型标识和模型名称
references array: 引用的素材，每项 { assetId, kind, label, slot, url, posterUrl }
creditsCharged number: 提交时扣除的积分
creditsRefunded number: 已退回的积分（失败、取消的部分）
errorMessage string | null: 失败或部分失败时的原因
tags / favorite array / boolean: 网页上的标签和收藏
canvasId / canvasNodeId / conversationId null: 网页画布和对话使用，API 提交的任务为 null
createdAt / finishedAt string | null: 创建时间、结束时间（未结束为 null）
results array: 结果列表，每张图片、每条视频各一项，按 index 排序，字段见下表

results[] 每项

id / index string / number: 结果 ID 和序号（从 0 开始）
status string: 未结束：queued、submitted、processing；已结束：completed、failed、canceled
error string | null: 失败或取消的原因，例如「已取消」「生成超时，积分已退回」
asset object | null: 生成的文件（素材对象，字段见素材列表），完成前为 null。常用：url 文件地址、posterUrl 视频封面、mimeType、、、

请求

curl -s "$BASE/api/v1/batches/$BATCH_ID" \
  -H "Authorization: Bearer $API_KEY"

响应 200

{
  "id": "5f0c8a3e-2b7d-4c19-8e6a-1d4b7f9a2c60",
  "toolSlug": "image-generation",
  "taskType": "image_generation",
  "status": "completed",
  "title": "白色陶瓷咖啡杯放在原木桌上，清晨自然光，商业摄影",
  "prompt": "白色陶瓷咖啡杯放在原木桌上，清晨自然光，商业摄影",
  "params": {
    "ratio": "1:1",
    "resolution": "2K",
    "quality": "高",
    "format": "PNG",
    "count": 2
  },
  "skillKey": null,
  "modelKey": "image.lc-2.5-pro",
  "modelLabel": "LC Image 2.5 Pro",
  "references": [],
  "creditsCharged": 24,
  "creditsRefunded": 0,
  "tags": [],
  "favorite": false,
  "errorMessage": null,
  "canvasId": null,
  "canvasNodeId": null,
  "conversationId": null,
  "createdAt": "2026-10-15T08:30:12.418Z",
  "finishedAt": "2026-10-15T08:30:44.931Z",
  "results": [
    {
      "id": "fda6bac3-6371-4b6c-9de7-013c5a492cf8",
      "index": 0,
      "status": "completed",
      "phase": null,
      "error": null,
      "asset": {
        "id": "13f39598-0863-4f77-9617-b32b624061ef",
        "kind": "image",
        "source": "generated",
        "url": "https://niulai-files.tos-cn-beijing.volces.com/users/1b065788-482c-4786-b879-0a5cd871f3c6/generated/92fc0136-3f6a-4077-b800-4420ddb33e6b.png",
        "posterUrl": null,
        "fileName": "白色陶瓷咖啡杯放在原木桌上，清晨自然光，商业摄影.png",
        "mimeType": "image/png",
        "sizeBytes": 6127430,
        "width": 2048,
        "height": 2048,
        "durationMs": null,
        "toolSlug": "image-generation",
        "batchId": "5f0c8a3e-2b7d-4c19-8e6a-1d4b7f9a2c60",
        "groupId": null,
        "saved": false,
        "createdAt": "2026-10-15T08:30:41.209Z"
      },
      "text": null,
      "json": null,
      "finalPrompt": null,
      "startedAt": "2026-10-15T08:30:13.052Z",
      "finishedAt": "2026-10-15T08:30:41.337Z",
      "etaSeconds": 30
    },
    {
      "id": "d6202845-11f7-4de5-989b-b212068f4f87",
      "index": 1,
      "status": "completed",
      "phase": null,
      "error": null,
      "asset": {
        "id": "94a5cc88-1f61-4295-9710-93d00f4180d9",
        "kind": "image",
        "source": "generated",
        "url": "https://niulai-files.tos-cn-beijing.volces.com/users/1b065788-482c-4786-b879-0a5cd871f3c6/generated/9bda1b73-0857-447f-b0e7-a23afcb619d6.png",
        "posterUrl": null,
        "fileName": "白色陶瓷咖啡杯放在原木桌上，清晨自然光，商业摄影.png",
        "mimeType": "image/png",
        "sizeBytes": 5893217,
        "width": 2048,
        "height": 2048,
        "durationMs": null,
        "toolSlug": "image-generation",
        "batchId": "5f0c8a3e-2b7d-4c19-8e6a-1d4b7f9a2c60",
        "groupId": null,
        "saved": false,
        "createdAt": "2026-10-15T08:30:44.771Z"
      },
      "text": null,
      "json": null,
      "finalPrompt": null,
      "startedAt": "2026-10-15T08:30:13.067Z",
      "finishedAt": "2026-10-15T08:30:44.905Z",
      "etaSeconds": 30
    }
  ]
}

任务列表与批量查询

GET/api/v1/batches

按创建时间从新到旧列出任务。同时轮询多个任务时，用 ids 一次查回来，不要逐个请求。

查询参数

ids string: 逗号分隔的任务 ID，最多 50 个，格式不对的会被忽略；只返回其中属于你的任务
limit number: 每页数量，默认 20，最大 50。用 ids 时不用传，会返回全部指定的任务（最多 50 个）
cursor string: 上一页返回的 nextCursor
tool_slug string: 只看某个工具的任务；可以重复传多个
active true: 只看未结束的任务（queued、processing）

返回 { items, nextCursor }，items 中每项都是完整的任务对象。

请求

curl -s "$BASE/api/v1/batches?ids=5f0c8a3e-2b7d-4c19-8e6a-1d4b7f9a2c60,83f75cd9-e9b5-4f03-b569-4446a120bc76,6180e375-3ae6-4858-bcce-3a68b0c0b5a0" \
  -H "Authorization: Bearer $API_KEY"

响应 200（节选：只列出部分字段）

{
  "items": [
    {
      "id": "6180e375-3ae6-4858-bcce-3a68b0c0b5a0",
      "toolSlug": "video-generation",
      "status": "processing",
      "creditsCharged": 100,
      "results": [{ "index": 0, "status": "processing", "etaSeconds": 186 }]
    },
    {
      "id": "83f75cd9-e9b5-4f03-b569-4446a120bc76",
      "toolSlug": "image-generation",
      "status": "canceled",
      "creditsCharged": 48,
      "creditsRefunded": 48
    },
    {
      "id": "5f0c8a3e-2b7d-4c19-8e6a-1d4b7f9a2c60",
      "toolSlug": "image-generation",
      "status": "completed",
      "creditsCharged": 24,
      "creditsRefunded": 0
    }
  ],
  "nextCursor": null
}

取消任务

POST/api/v1/batches/{id}/cancel

取消还在排队、没有开始生成的结果，并退回它们的积分；已经开始生成的结果不能取消，会继续生成。返回取消后的任务对象。

全部结果都取消时，任务状态变为 canceled；只取消了一部分时，等其余结果结束后再确定任务状态（例如 partial）。
没有可以取消的结果时返回 409 conflict（「任务已开始生成，无法取消」）。

请求

curl -s -X POST "$BASE/api/v1/batches/$BATCH_ID/cancel" \
  -H "Authorization: Bearer $API_KEY"

响应 200（节选）

{
  "id": "83f75cd9-e9b5-4f03-b569-4446a120bc76",
  "status": "canceled",
  "creditsCharged": 48,
  "creditsRefunded": 48,
  "errorMessage": "已取消",
  "finishedAt": "2026-10-15T08:31:02.115Z",
  "results": [
    { "index": 0, "status": "canceled", "error": "已取消" },
    { "index": 1, "status": "canceled", "error": "已取消" },
    { "index": 2, "status": "canceled", "error": "已取消" },
    { "index": 3, "status": "canceled", "error": "已取消" }
  ]
}

删除任务

DELETE/api/v1/batches/{id}

删除任务。还有结果在生成时返回 409 conflict（「任务生成中，完成后才能删除」）；只剩排队中的结果时，会先取消并退回积分，再删除。画布上的任务在作品还没放进画布卡片时也返回 409 conflict，在网页上打开那个画布后再删除即可。

任务生成的文件会一起删除（在网页上保存到「资产」的、画布卡片上还在用的除外），删除前请先下载需要的结果。

请求

curl -s -X DELETE "$BASE/api/v1/batches/$BATCH_ID" \
  -H "Authorization: Bearer $API_KEY"

响应 200

{ "ok": true }

可用模型

无需认证

GET/api/v1/model-routes/public

列出可以选择的模型。提交时把 key 作为 model_key 传入。

查询参数

tool_slug string: 只返回这个工具可用的模型，例如 image-generation、video-generation
kind string: 按模型类型过滤，例如 image、video

items[] 每项

key string: 模型标识，提交时作为 model_key
label / description string: 名称和介绍
isDefault boolean: 是否默认模型。不传 model_key 时用默认模型，没有默认模型时用列表里的第一个
capabilities object: 模型支持的参数：resolutions 分辨率、ratios 比例、duration 单段时长 { min, max, allowed? }（秒）、audio 能否生成声音、references 单次参考素材上限
pricing object: 计价：unit 为 image（按张）、second（按秒）或 call（按次）；rates 按分辨率的单价，rate 统一单价，amount 每次价格；discount 折扣系数（0.75 即 7.5 折）；min 单个结果的最低收费
available boolean: 为 false 时模型服务暂未配置，用它提交会返回 model_unavailable
kind / badge / discountLabel / logoUrl string | null: 模型类型和网页上的展示信息

请求

curl -s "$BASE/api/v1/model-routes/public?tool_slug=image-generation"

响应 200（本站当前数据）

{
  "items": [
    {
      "key": "image.lc-2.5-pro",
      "kind": "image",
      "label": "LC Image 2.5 Pro",
      "description": "细节更强，画面细节更好和更精准",
      "badge": null,
      "discountLabel": null,
      "logoUrl": null,
      "isDefault": true,
      "capabilities": {
        "ratios": ["auto", "16:9", "4:3", "1:1", "3:4", "9:16"],
        "references": { "image": 10 },
        "resolutions": ["1K", "2K"]
      },
      "pricing": { "unit": "image", "rates": { "1K": 6, "2K": 12 } },
      "available": true
    },
    {
      "key": "image.lc-2.5-fast",
      "kind": "image",
      "label": "LC Image 2.5 Fast",
      "description": "生成更快，适合日常高质量出图",
      "badge": null,
      "discountLabel": null,
      "logoUrl": null,
      "isDefault": false,
      "capabilities": {
        "ratios": ["auto", "16:9", "4:3", "1:1", "3:4", "9:16"],
        "references": { "image": 10 },
        "resolutions": ["1K", "2K"]
      },
      "pricing": { "unit": "image", "rates": { "1K": 2.7, "2K": 2.7 } },
      "available": true
    }
  ]
}

素材列表

GET/api/v1/assets

列出你的素材：确认上传完成的文件和生成的结果，已删除的不返回。查询单个素材用 GET /api/v1/assets/{id}，返回一个素材对象。

查询参数

kind string: image、video 或 audio；可以重复传多个
source string: upload（上传的）或 generated（生成的）
q string: 按文件名搜索
limit number: 每页数量，默认 30，最大 100
cursor string: 上一页返回的 nextCursor

素材对象

id string: 素材 ID，提交任务时作为 references[].asset_id
kind / source string: image、video、audio；upload 或 generated
url string: 文件地址，可以直接下载，不需要 Key。以 / 开头时拼上 https://niulaiai.top
posterUrl string | null: 视频的封面图
fileName / mimeType / sizeBytes string / string / number: 文件名、类型、大小（字节）
width / height / durationMs number | null: 宽、高（像素），视频和音频的时长（毫秒）

请求

curl -s "$BASE/api/v1/assets?kind=image&source=upload&limit=20" \
  -H "Authorization: Bearer $API_KEY"

响应 200

{
  "items": [
    {
      "id": "26fc9c02-c74e-4623-9d7b-1417422d0a65",
      "kind": "image",
      "source": "upload",
      "url": "https://niulai-files.tos-cn-beijing.volces.com/users/1b065788-482c-4786-b879-0a5cd871f3c6/assets/d564e15f-d558-4381-b0f7-451d10f0ee33.png",
      "posterUrl": null,
      "fileName": "product.png",
      "mimeType": "image/png",
      "sizeBytes": 482133,
      "width": 1200,
      "height": 1600,
      "durationMs": null,
      "toolSlug": null,
      "batchId": null,
      "groupId": null,
      "saved": true,
      "createdAt": "2026-10-15T08:40:03.214Z"
    }
  ],
  "nextCursor": null
}

积分余额

GET/api/v1/usage/summary

响应字段

balance object: subscription 订阅积分、recharge 充值积分、total 合计可用
subscription object | null: 当前订阅：name、creditsPerPeriod 每期发放的积分、currentPeriodEnd 本期结束时间、endsAt 订阅到期时间；没有订阅时为 null
queuedSubscription object | null: 当前订阅期间又买的另一个套餐，当前订阅到期后开始：name、startsAt 开始时间；没有时为 null
consumedThisMonth number: 本月（北京时间）消耗的积分，已减去退款
consumedTotal number: 累计消耗的积分，已减去退款

请求

curl -s "$BASE/api/v1/usage/summary" \
  -H "Authorization: Bearer $API_KEY"

响应 200

{
  "balance": { "subscription": 296, "recharge": 740.5, "total": 1036.5 },
  "subscription": {
    "name": "专业版",
    "creditsPerPeriod": 1100,
    "currentPeriodEnd": "2026-11-01T16:00:00.000Z",
    "endsAt": "2026-11-01T16:00:00.000Z"
  },
  "queuedSubscription": null,
  "consumedThisMonth": 410.4,
  "consumedTotal": 2239.7
}

积分流水

GET/api/v1/usage/ledger

查询参数

type string: 只看某一类：CONSUME 消耗、REFUND 退款、RECHARGE 积分充值、SUBSCRIPTION_GRANT 订阅发放、EXPIRE 积分失效、CARD_REDEEM 充值卡兑换入账、ADMIN_ADJUST 系统调整、INVITE_REWARD 邀请奖励、SIGNUP_BONUS 注册赠送
tool_slug string: 只看某个工具的流水
limit number: 每页数量，默认 20，最大 100
cursor string: 上一页返回的 nextCursor

items[] 每项

type string: 流水类型，取值同上
bucket string: SUBSCRIPTION（订阅积分）或 RECHARGE（充值积分）。一次扣费可能分成这两类各一条
amount number: 积分变动，正数为入账，负数为扣除
balanceAfter number: 这条记录之后，该类积分（bucket）的余额
toolSlug / batchId string | null: 相关的工具和任务
note string | null: 说明，扣费时是报价明细
id / createdAt string: 流水 ID 和时间

请求

curl -s "$BASE/api/v1/usage/ledger?type=CONSUME&limit=20" \
  -H "Authorization: Bearer $API_KEY"

响应 200

{
  "items": [
    {
      "id": "0271e09c-1bf6-494c-9ba4-2e40db9ebf72",
      "type": "CONSUME",
      "bucket": "SUBSCRIPTION",
      "amount": -24,
      "balanceAfter": 296,
      "toolSlug": "image-generation",
      "batchId": "5f0c8a3e-2b7d-4c19-8e6a-1d4b7f9a2c60",
      "note": "LC Image 2.5 Pro · 2K × 2",
      "createdAt": "2026-10-15T08:30:12.431Z"
    }
  ],
  "nextCursor": null
}

poster-layers

请求体示例

{
  "tool_slug": "image-generation",
  "model_key": "image.lc-2.5-pro",
  "prompt": "白色陶瓷咖啡杯放在原木桌上，清晨自然光，商业摄影",
  "params": { "ratio": "1:1", "resolution": "2K", "count": 2 }
}

请求体示例：首帧图生成 10 秒视频

{
  "tool_slug": "video-generation",
  "model_key": "video.seedance-2.0-mini",
  "prompt": "镜头缓慢推近，女生拿起保温杯喝一口，对着镜头微笑说：早上一杯，暖一整天",
  "params": {
    "ratio": "9:16",
    "resolution": "720p",
    "duration": 10,
    "audio": true,
    "subtitles": true
  },
  "references": [
    {
      "asset_id": "26fc9c02-c74e-4623-9d7b-1417422d0a65",
      "role": "first_frame"
    }
  ]
}

请求体示例：照片 + 文字口播

{
  "tool_slug": "digital-human",
  "params": {
    "resolution": "720p",
    "tts": {
      "text": "这款保温杯是 316 不锈钢内胆，保温 12 小时，今天下单再送杯套。",
      "voice": "zh_female_vv_uranus_bigtts",
      "speed": 1
    }
  },
  "references": [
    { "asset_id": "1b3c2b33-2a30-4951-94ac-b9f408b7204b", "slot": "形象" }
  ]
}

请求体示例：擦除右上角水印

{
  "tool_slug": "video-watermark-remove",
  "params": { "regions": [{ "x1": 70, "y1": 2, "x2": 98, "y2": 9 }] },
  "references": [{ "asset_id": "feaf1464-4cc0-4cb1-92e7-50f4fed11d6c" }]
}

请求体示例：大模型版增强到 1080p

{
  "tool_slug": "video-quality-enhance",
  "params": {
    "version": "generative",
    "resolution": "1080p",
    "scene": "aigc",
    "fps": "none"
  },
  "references": [{ "asset_id": "feaf1464-4cc0-4cb1-92e7-50f4fed11d6c" }]
}

file_name

请求

FILE=product.png
SIZE=$(wc -c < "$FILE" | tr -d ' ')
POLICY=$(curl -s "$BASE/api/v1/assets/upload-policy" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d "$(jq -n --arg name "$FILE" --argjson size "$SIZE" '{file_name: $name, mime_type: "image/png", size_bytes: $size}')")
ASSET_ID=$(echo "$POLICY" | jq -r '.assetId')
UPLOAD_URL=$(echo "$POLICY" | jq -r '.upload.url')
case "$UPLOAD_URL" in /*) UPLOAD_URL="$BASE$UPLOAD_URL" ;; esac

响应 200

{
  "assetId": "26fc9c02-c74e-4623-9d7b-1417422d0a65",
  "upload": {
    "method": "PUT",
    "url": "https://bucket.example.com/users/1b065788-482c-4786-b879-0a5cd871f3c6/assets/d564e15f-d558-4381-b0f7-451d10f0ee33.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=…&X-Amz-Date=20261015T084003Z&X-Amz-Expires=900&X-Amz-Signature=…&X-Amz-SignedHeaders=content-length%3Bcontent-type%3Bhost",
    "headers": { "Content-Type": "image/png" },
    "expiresAt": "2026-10-15T08:55:03.000Z"
  }
}

第 2 步：上传文件

用 PUT 把文件原样（二进制，不是表单）发到 upload.url，带上 upload.headers 里的请求头。这一步不用带 API Key，返回 200 即成功。

请求

curl -sS -X PUT "$UPLOAD_URL" \
  -H "Content-Type: image/png" \
  --data-binary @"$FILE"

第 3 步：确认上传

POST/api/v1/assets/complete

请求体

asset_id string · 必填: 第 1 步返回的 assetId

服务器确认文件已经到达，读出尺寸和时长（视频还会截一张封面），返回素材对象（字段见素材列表）。对已经确认过的素材再调用，会直接返回该素材。

400 upload_incomplete：还没收到文件，确认第 2 步成功后再调用。
413 file_too_large：实际文件超过上限，这个素材已被删除。
400 invalid_media：视频或音频无法解析，这个素材已被删除，请检查格式后重新上传。
503 probe_unavailable：服务器暂时读不到文件，稍后重试这一步即可。
没有确认的上传会在 24 小时后自动清理。

请求

curl -s "$BASE/api/v1/assets/complete" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"asset_id\": \"$ASSET_ID\"}"

响应 200

{
  "id": "26fc9c02-c74e-4623-9d7b-1417422d0a65",
  "kind": "image",
  "source": "upload",
  "url": "https://niulai-files.tos-cn-beijing.volces.com/users/1b065788-482c-4786-b879-0a5cd871f3c6/assets/d564e15f-d558-4381-b0f7-451d10f0ee33.png",
  "posterUrl": null,
  "fileName": "product.png",
  "mimeType": "image/png",
  "sizeBytes": 482133,
  "width": 1200,
  "height": 1600,
  "durationMs": null,
  "toolSlug": null,
  "batchId": null,
  "groupId": null,
  "saved": true,
  "createdAt": "2026-10-15T08:40:03.214Z"
}

请求体示例

{
  "tool_slug": "image-generation",
  "prompt": "把图1中的商品放在大理石台面上，柔和侧光，高级感电商主图",
  "params": { "ratio": "3:4", "resolution": "2K" },
  "references": [{ "asset_id": "26fc9c02-c74e-4623-9d7b-1417422d0a65" }]
}

422 字段格式不对

{
  "message": "Invalid uuid",
  "code": "validation_error",
  "detail": {
    "fields": [
      { "field": "references.0.asset_id", "message": "Invalid uuid" }
    ]
  }
}

width

height

durationMs

简介与计费

约定

认证

创建 Key

发送请求

权限

快速开始

0. 准备

1. 报价

2. 提交任务

接口参考

响应字段

工具与参数

工具一览

上传素材

支持的文件

请求体

错误码

最佳实践

计费

3. 轮询到完成

4. 下载结果

请求体

references[] 每项

任务对象

results[] 每项

查询参数

查询参数

items[] 每项

查询参数

素材对象

响应字段

查询参数

items[] 每项

图片创作 · image-generation

本站当前可用的模型

params

视频创作 · video-generation

本站当前可用的模型

params

数字人 · digital-human

params

去水印 · 字幕擦除 · 画质增强

去水印、字幕擦除的 params

画质增强的 params

响应字段

第 2 步：上传文件

请求体

在任务中使用