Dokumentasi API Pilio
Gunakan API Key permanen untuk membuat tugas penghapusan watermark gambar asinkron dan tugas GPT Image 2. Panggilan API memakai ulang kredit Pilio yang sudah ada dan secara default mengonsumsi 3x biaya kredit dasar web.
公共基础
Pilio API 当前提供异步任务接口:创建任务后立即返回任务 ID,再通过任务查询接口轮询状态并读取结果。
Pilio API 异步任务流程
创建文件 -> 上传文件 -> 创建任务 -> 轮询结果 -> 下载文件
- 1
创建文件
POST/files/batch-create获取 file_id 和上传地址
- 2
上传文件
PUTupload_url文件内容直传预签名地址
- 3
创建任务
POST/v1/images/...传入 file_id,返回 task_id
- 4
轮询结果
GETstatus_url / result_url等待 Succeeded 或 Failed
- 5
下载文件
GETdownload_url下载临时签名结果文件
异步接口推荐流程:先准备文件 ID,再上传文件并创建任务,随后轮询状态和结果,最后下载输出文件。
所有创建接口都会立即返回 ID;任务完成后从 result_url 读取文件列表,再使用 download_url 下载结果。
鉴权
- Base URL
https://pilio.ai- Content-Type
application/json- 认证方式
Authorization: Bearer <API Key> 或 X-API-Key: <API Key>
Kirim API Key Anda pada setiap permintaan:
Authorization: Bearer pilio_sk_your_key_here
# or
X-API-Key: pilio_sk_your_key_here`X-API-Key` juga diterima untuk kompatibilitas. API Key berlaku permanen sampai Anda mencabutnya di akun.
5 分钟接入
这段流程按 AI agent 生成代码最容易出错的顺序写:先拿文件 ID,再上传对象,最后创建任务。可以直接复制给代码生成器作为集成约束。
# 1) 创建上传文件记录。这个示例固定选择单文件上传:upload_mode=simple
# 返回 data.items[0].id 和 data.items[0].upload_url
curl -X POST "https://pilio.ai/v1/files/batch-create" -H "Authorization: Bearer pilio_sk_your_key_here" -H "Content-Type: application/json" -d '{"files":[{"nanoid":"V1StGXR8_Z5jdHi6B-myT","name":"reference.png","type":"png","size":1024}],"upload_mode":"simple","storage_intent":"temporary"}'
# 2) 上传文件到预签名地址。注意:这里不要带 Pilio API Key
# 单文件 upload_url 上传完成后,直接进入第 3 步,不要调用 /v1/files/:id/complete
curl -X PUT "<upload_url>" -H "Content-Type: image/png" --data-binary @reference.png
# 3) 用文件 ID 创建任务
curl -X POST "https://pilio.ai/v1/images/remove-watermark" -H "Authorization: Bearer pilio_sk_your_key_here" -H "Content-Type: application/json" -d '{"image_file_id":"<file_id>","mode":"auto"}'
# 4) 轮询任务状态,直到 status 为 Succeeded 或 Failed
curl -H "Authorization: Bearer pilio_sk_your_key_here" "https://pilio.ai/v1/tasks/<task_id>/status"
# 5) 获取结果并下载 data.files[0].download_url
curl -H "Authorization: Bearer pilio_sk_your_key_here" "https://pilio.ai/v1/tasks/<task_id>/result"TypeScript 单文件上传示例
const API_BASE = "https://pilio.ai";
const apiKey = process.env.PILIO_API_KEY!;
async function pilioFetch(path: string, init: RequestInit = {}) {
const response = await fetch(API_BASE + path, {
...init,
headers: {
Authorization: `Bearer ${apiKey}`,
"Content-Type": "application/json",
...init.headers,
},
});
const payload = await response.json();
if (!response.ok || payload.code !== 200) {
throw new Error(payload.message || `Pilio API failed: ${payload.code}`);
}
return payload.data;
}
async function removeWatermark(file: File) {
const created = await pilioFetch("/v1/files/batch-create", {
method: "POST",
body: JSON.stringify({
files: [{
nanoid: crypto.randomUUID().replaceAll("-", "").slice(0, 21),
name: file.name,
type: file.name.split(".").pop()?.toLowerCase(),
size: file.size,
}],
upload_mode: "simple",
storage_intent: "temporary",
}),
});
const source = created.items[0];
if (source.upload_url) {
// 预签名地址不需要 Pilio API Key
await fetch(source.upload_url, {
method: "PUT",
headers: { "Content-Type": file.type || "application/octet-stream" },
body: file,
});
} else {
throw new Error("This sample only covers single upload_url uploads. Use upload_urls + complete for multipart files.");
}
const task = await pilioFetch("/v1/images/remove-watermark", {
method: "POST",
body: JSON.stringify({ image_file_id: source.id, mode: "auto" }),
});
while (true) {
await new Promise((resolve) => setTimeout(resolve, 2000));
const status = await pilioFetch(task.status_url);
if (status.status === "Failed") throw new Error(status.error_message || "Task failed");
if (status.status === "Succeeded") break;
}
const result = await pilioFetch(task.result_url);
return result.files?.[0]?.download_url || result.zip_file?.download_url;
}AI 接入提示
- 只把 Pilio API Key 发给
https://pilio.ai/v1/*;不要把 API Key 发给upload_url、upload_urls或download_url。 - 创建任务时传
items[].id,不要传nanoid、upload_id、upload_url。 - 以
batch-create返回字段决定上传路径:有upload_url就走单文件PUT,有upload_urls才走分片PUT+ complete。 - 单文件
upload_url上传完成后不要调用 complete;只有返回upload_urls的分片上传才调用/v1/files/:id/complete。 - 先等所有预签名
PUT请求成功,再创建任务;否则任务创建可能返回source_file_upload_not_completed。 - 轮询时以
Succeeded/Failed为终态;不要解析自然语言message判断任务状态。
响应外壳
所有成功响应都包在 code、message、data 中;业务字段位于 data。
{
"code": 200,
"message": "success",
"data": { ... }
}文件上传与下载
图片编辑和 PDF 去水印接口需要先拿到文件 ID。推荐流程是:创建文件记录 → PUT 预签名地址上传文件 → 用返回的文件 ID 创建任务 → 查询任务结果 → 下载输出文件。
upload_mode=simple固定选择单文件上传;返回upload_url时,直接把文件二进制用PUT上传到该地址,不需要再调用 complete。upload_mode=multipart固定选择分片上传;返回upload_urls时,按数组顺序分片PUT,收集每个分片响应头里的ETag后调用完成接口。upload_mode=auto由服务端按文件大小选择上传方式;客户端应以返回字段为准,而不是自己猜测是否分片。- 上传到预签名地址时不需要携带 Pilio API Key;只需要按对象存储要求设置文件内容和必要的
Content-Type。 - 任务成功后调用
result_url,从files[].download_url或zip_file.download_url获取临时下载地址。
主流程边界
batch-create只创建文件记录和上传地址,不代表文件内容已经上传完成。- 返回
upload_url:执行一次PUT,成功后直接用items[].id创建任务,不调用/v1/files/:id/complete。 - 返回
upload_urls:每个分片PUT成功后,必须调用/v1/files/:id/complete合并对象,再用items[].id创建任务。 - 创建任务时只传文件 ID,例如
image_file_id、image_file_ids或pdf_file_id;不要传nanoid、upload_url、upload_urls或upload_id。 - 上传地址过期或分片上传丢失时,重新调用
batch-create获取新的上传地址。
上传限制
| 字段 | 类型 | 必填 | 说明 / 可选值 |
|---|---|---|---|
单次创建文件数 | integer | 固定限制 | 最多 500 个文件。 |
单文件大小 | bytes | 固定限制 | 最大 2 GB。 |
分片阈值 | bytes | 固定规则 | upload_mode=auto 时,文件大于 5 MB 通常返回 upload_urls;simple 会固定尝试单文件上传。 |
上传地址有效期 | duration | 固定规则 | upload_url / upload_urls 约 2 小时有效,过期后重新 batch-create。 |
下载地址有效期 | duration | 固定规则 | download_url 约 24 小时有效,过期后重新查询 result_url 获取新地址。 |
/v1/files/batch-create
创建上传文件记录并返回预签名上传地址。根据 upload_mode 和文件大小返回单文件 upload_url 或分片 upload_urls。
请求示例
{
"files": [
{
"nanoid": "V1StGXR8_Z5jdHi6B-myT",
"name": "reference.png",
"type": "png",
"size": 1024
}
],
"upload_mode": "simple",
"storage_intent": "temporary"
}传入参数
| 字段 | 类型 | 必填 | 说明 / 可选值 |
|---|---|---|---|
files | SourceFile[] | 是 | 要创建上传凭证的文件列表,至少 1 个。 |
files[].nanoid | string | 是 | 客户端生成的 21 位 nanoid,用于把返回文件和本地文件对应起来。 |
files[].name | string | 是 | 原始文件名,最长 300 字符;后缀需与 type 匹配。 |
files[].type | enum | 是 | 文件扩展名类型,例如 jpg、jpeg、png、webp、pdf。 |
files[].size | integer | 否 | 文件大小,单位 byte;auto 模式会用它判断返回 upload_url 还是 upload_urls。 |
upload_mode | enum | 否 | auto、simple 或 multipart。simple 固定返回单文件 upload_url;multipart 固定返回 upload_urls;auto 由服务端按大小选择。 |
storage_intent | enum | 否 | 当前开发者 API 仅支持 temporary;图片编辑和 PDF 去水印输入应使用 temporary。 |
返回 data 字段
| 字段 | 类型 | 必填 | 说明 / 可选值 |
|---|---|---|---|
total | integer | 是 | 本次成功创建的文件数量。 |
items | File[] | 是 | 文件记录列表;用返回的 id 作为后续任务的 image_file_id、image_file_ids 或 pdf_file_id。 |
items[].id | string | 是 | 文件 ID。 |
items[].nanoid | string | 是 | 请求中的 nanoid,便于客户端配对。 |
items[].status | FileStatus | 是 | 初始为 Pending;必须先完成预签名 PUT 上传,再用文件 ID 创建任务。 |
items[].upload_url | string | 单文件时是 | 单文件 PUT 上传地址;直接把文件二进制 PUT 到该地址。使用这个字段时不需要调用 complete。 |
items[].upload_urls | string[] | 分片上传时是 | 分片 PUT 上传地址数组;按顺序上传每个分片,随后才调用 complete。 |
items[].upload_id | string | 分片上传时是 | 对象存储分片上传 ID,仅用于排查;完成接口只需要 parts。 |
/v1/files/:id/complete
完成大文件分片上传(可选)。只有 batch-create 返回 upload_urls 时才需要调用;返回 upload_url 的单文件上传不要调用。
请求示例
{
"parts": [
{ "part_number": 1, "etag": ""etag-from-upload-response"" }
]
}传入参数
| 字段 | 类型 | 必填 | 说明 / 可选值 |
|---|---|---|---|
id | string(path) | 分片上传时是 | 文件 ID,即 batch-create 返回的 items[].id;单文件 upload_url 上传不要调用此接口。 |
parts | CompletedPart[] | 分片上传时是 | 已成功上传的分片列表,必须从 1 开始连续。 |
parts[].part_number | integer | 分片上传时是 | 分片序号,从 1 开始。 |
parts[].etag | string | 分片上传时是 | 上传每个分片后对象存储返回的 ETag 响应头。 |
返回 data 字段
| 字段 | 类型 | 必填 | 说明 / 可选值 |
|---|---|---|---|
data | null/object | 否 | 完成成功即表示分片对象已合并;单文件 upload_url 上传不需要调用此接口。 |
下载结果文件
- 先轮询
GET /v1/tasks/:id/status,直到任务状态为Succeeded。 - 再调用
GET /v1/tasks/:id/result,读取返回的download_url。 download_url是对象存储临时签名地址,过期后重新查询 result 即可刷新。
任务查询
Semua endpoint pembuatan langsung mengembalikan ID tugas.
{
"code": 200,
"message": "success",
"data": {
"task_id": "2048...",
"status": "Processing",
"status_url": "/v1/tasks/2048.../status",
"result_url": "/v1/tasks/2048.../result",
"created_at": "2026-04-25T12:00:00Z"
}
}Poll `status_url` sampai tugas mencapai `Succeeded` atau `Failed`, lalu baca file hasil dari `result_url`.
/v1/tasks/:id/status
查询任务状态。:id 是创建接口返回的 task_id。
请求示例
无请求体。传入参数
| 字段 | 类型 | 必填 | 说明 / 可选值 |
|---|---|---|---|
id | string(path) | 是 | 任务 ID。 |
返回 data 字段
| 字段 | 类型 | 必填 | 说明 / 可选值 |
|---|---|---|---|
task_id | string | 是 | 任务 ID。 |
status | TaskStatus | 是 | Pending、Processing、Succeeded、Failed。 |
error_type | string | 否 | 失败分类,仅失败时通常存在。 |
error_message | string | 否 | 失败说明,仅失败时通常存在。 |
created_at | string(date-time) | 否 | 任务创建时间。 |
updated_at | string(date-time) | 否 | 最近更新时间。 |
result_url | string | 否 | 结果查询地址。 |
/v1/tasks/:id/result
查询任务结果。任务成功后会返回可下载文件。
请求示例
无请求体。传入参数
| 字段 | 类型 | 必填 | 说明 / 可选值 |
|---|---|---|---|
id | string(path) | 是 | 任务 ID。 |
返回 data 字段
| 字段 | 类型 | 必填 | 说明 / 可选值 |
|---|---|---|---|
task_id | string | 是 | 任务 ID。 |
status | TaskStatus | 是 | 如果还未 Succeeded,files 可能为空。 |
error_type | string | 否 | 失败分类。 |
error_message | string | 否 | 失败说明。 |
files | ResultFile[] | 否 | 单个或多个输出文件。 |
zip_file | ResultFile | 否 | 批量输出时可能提供 zip。 |
公共结构
TaskStatus 可选值
Pending已创建,等待 Worker 调度。Processing正在处理;客户端应继续轮询 status_url。Succeeded处理成功;可调用 result_url 获取结果文件。Failed处理失败;读取 error_type 和 error_message。ResultFile 字段
| 字段 | 类型 | 必填 | 说明 / 可选值 |
|---|---|---|---|
id | string | 是 | 文件 ID。 |
name | string | 否 | 文件名。 |
type | string | 否 | 文件类型。 |
size | integer | 否 | 文件大小,单位 byte。 |
download_url | string | 否 | 临时下载地址,仅成功结果会签发。 |
错误处理
失败响应仍使用同一层响应外壳。AI 生成代码时应优先判断 code !== 200,再读取 message 和 data;不要通过自然语言 message 推断业务状态。
{
"code": 1402,
"message": "Invalid token",
"data": null
}常见错误
| 字段 | 类型 | 必填 | 说明 / 可选值 |
|---|---|---|---|
1402 | Unauthorized | 常见 | API Key 缺失、无效或已撤销;检查 Authorization / X-API-Key。 |
1505 | Too many files | 上传 | 单次创建文件数量超过系统限制;拆分请求。 |
1510 | Multipart upload not found | 上传 | 分片上传不存在或已过期;重新创建上传文件并重传分片。 |
source_file_upload_not_completed | BadRequest | 任务创建 | 文件对象还没有上传完成;先完成 PUT,再创建任务。 |
quota_or_inflight_limit | Limit | 计费 | 积分不足、套餐限制或 Pending + Processing 在途任务超过 20。 |
轮询建议
- 初始每 2 秒查询一次
status_url;长任务可退避到 5 秒。 Succeeded和Failed是终态,进入终态后停止轮询。- 不要并发轮询同一个任务;客户端应保存
task_id,刷新页面后可继续查询。
资源
OpenAPI 文件
已提供独立的公开 API OpenAPI 文件,可下载后导入 Postman、Apifox、Insomnia、Bruno 等 API 测试工具,也可以交给 AI 读取接口结构。
下载 /developers/pilio-openapi.json如果你只需要把接口导入 API 测试工具,直接下载上面的 OpenAPI JSON 即可。页面正文用于快速阅读,OpenAPI 文件用于测试、调试和作为生成代码的结构化真源。
SDK
Pilio 已提供 JavaScript / TypeScript 官方 SDK 与 CLI;其它语言仍推荐把 OpenAPI JSON 作为真源,按项目语言生成类型、请求方法,或让 AI 直接基于接口描述写薄封装。
安装与使用
pilioai/pilio-js 包含 @pilio/sdk 类型化 SDK 和基于 SDK 构建的 @pilio/cli,适合 Node.js、脚本自动化和 CI 工作流。
pnpm add @pilio/sdk
pnpm dlx @pilio/cli --helpCLI 快速调用
# 临时运行 CLI
pnpm dlx @pilio/cli --help
# 使用环境变量里的 PILIO_API_KEY 创建任务
pnpm dlx @pilio/cli gpt-image-2 --prompt "A cinematic product photo" --aspect-ratio 3:2
pnpm dlx @pilio/cli nano-banana-2 --prompt "A clean product poster" --aspect-ratio 1:1 --resolution 1K
pnpm dlx @pilio/cli task wait <task_id>上传并创建任务
import { readFile } from "node:fs/promises";
import { PilioClient } from "@pilio/sdk";
const client = new PilioClient({
apiKey: process.env.PILIO_API_KEY!,
});
const image = await readFile("portrait.png");
const file = await client.files.upload({
name: "portrait.png",
type: "png",
data: new Blob([image]),
size: image.byteLength,
});
const task = await client.images.removeBackground({
image_file_id: file.id!,
});
const result = await client.tasks.wait(task.task_id);
console.log(result.files);常用生成工具
推荐接入方式
- 后端服务:让 AI 基于 OpenAPI JSON 生成一个很薄的 client,只封装鉴权、错误外壳、轮询和下载。
- 前端项目:优先生成 TypeScript 类型,再接入你已有的 fetch / axios / React Query 封装。
- 不建议直接依赖第三方生成器产出的厚 SDK 作为业务核心;保留薄封装更容易审查和修改。
Agent Skills
Pilio Agent Skills 提供面向 AI Agent 的小型技能包,用自然语言驱动 Developer API 工作流,并通过 @pilio/cli 执行。
安装技能包
pilioai/skills 提供 GPT Image 2、Nano Banana 2、抠图等技能包,支持 AI Agent 以自然语言调用 Pilio Developer API。
pnpm dlx skills add pilioai/skills --skill gpt-image-2
pnpm dlx skills add pilioai/skills --skill nano-banana-2
pnpm dlx skills add pilioai/skills --skill remove-background工具接口
GPT Image 2
/v1/images/gpt-image-2
创建 GPT Image 2 图片任务。可只传提示词生成图片,也可传 image_file_ids 作为参考图进行编辑或融合。
请求示例
{
"prompt": "A cinematic product photo of an orange perfume bottle",
"aspect_ratio": "3:2",
"output_count": 2,
"resolution": "2K"
}传入参数
| 字段 | 类型 | 必填 | 说明 / 可选值 |
|---|---|---|---|
prompt | string | 是 | 生成/编辑提示词,最长 32000 字符。 |
negative_prompt | string | 否 | 负向提示词,最长 32000 字符。 |
image_file_ids | string[] | 否 | 参考图片文件 ID;不传为文生图,传 1-16 个时作为参考图编辑/融合。支持 jpg、jpeg、png、webp。 |
aspect_ratio | enum | 无参考图时是;有参考图时否 | 1:1、3:2、2:3、3:4、4:3、4:5、5:4、16:9、9:16、21:9、auto。 |
output_count | integer | 否 | 输出张数,可选 1、2、4。 |
resolution | enum | 否 | 可选 1K、2K、4K;一般优先调这个。 |
quality | enum | 否 | 高级可选档位:auto、low、medium、high;默认 auto。会影响图片细节、算力投入和生成时间,不改变分辨率。 |
preprocess_mode | enum | 否 | 可选 off、auto。 |
返回 data 字段
| 字段 | 类型 | 必填 | 说明 / 可选值 |
|---|---|---|---|
task_id | string | 是 | 异步任务 ID。 |
status | TaskStatus | 是 | 初始通常为 Processing。 |
status_url | string | 是 | 任务状态查询地址。 |
result_url | string | 是 | 任务结果查询地址。 |
created_at | string(date-time) | 否 | 任务创建时间。 |
Nano Banana 2
/v1/images/nano-banana-2
创建 Nano Banana 2 图片任务。可只传提示词生成图片,也可传 image_file_ids 作为参考图进行编辑或融合。
请求示例
{
"prompt": "Turn these references into a clean product poster",
"image_file_ids": ["123456789", "123456790"],
"aspect_ratio": "16:9",
"resolution": "1K"
}传入参数
| 字段 | 类型 | 必填 | 说明 / 可选值 |
|---|---|---|---|
prompt | string | 是 | 生成/编辑提示词,最长 32000 字符。 |
negative_prompt | string | 否 | 负向提示词,最长 32000 字符。 |
image_file_ids | string[] | 否 | 参考图片文件 ID;不传为文生图,传 1-14 个时作为参考图编辑/融合。支持 jpg、jpeg、png、webp。 |
aspect_ratio | enum | 无参考图时是;有参考图时否 | 1:1、2:3、3:2、3:4、4:3、4:5、5:4、9:16、16:9、21:9、1:4、4:1、1:8、8:1。 |
output_count | integer | 否 | 输出张数,可选 1、2、4。 |
resolution | enum | 否 | 可选 0.5K、1K、2K、4K。 |
preprocess_mode | enum | 否 | 可选 off、auto。 |
返回 data 字段
| 字段 | 类型 | 必填 | 说明 / 可选值 |
|---|---|---|---|
task_id | string | 是 | 异步任务 ID。 |
status | TaskStatus | 是 | 初始通常为 Processing。 |
status_url | string | 是 | 任务状态查询地址。 |
result_url | string | 是 | 任务结果查询地址。 |
created_at | string(date-time) | 否 | 任务创建时间。 |
图片去水印
/v1/images/remove-watermark
创建图片去水印任务,支持自动识别或手动框选区域。
请求示例
{
"image_file_id": "123456789",
"mode": "manual",
"boxes": [{ "x1": 10, "y1": 15, "x2": 60, "y2": 70 }]
}传入参数
| 字段 | 类型 | 必填 | 说明 / 可选值 |
|---|---|---|---|
image_file_id | string | 是 | 待去水印图片文件 ID。 |
mode | enum | 否 | auto 自动识别;manual 手动框选。默认 auto。 |
boxes | Box[] | manual 时是 | 手动框选区域,1-5 个。坐标为图片宽高百分比。 |
boxes[].x1 | integer | manual 时是 | 左上角 X,0-100。 |
boxes[].y1 | integer | manual 时是 | 左上角 Y,0-100。 |
boxes[].x2 | integer | manual 时是 | 右下角 X,0-100。 |
boxes[].y2 | integer | manual 时是 | 右下角 Y,0-100。 |
返回 data 字段
| 字段 | 类型 | 必填 | 说明 / 可选值 |
|---|---|---|---|
task_id | string | 是 | 异步任务 ID。 |
status | TaskStatus | 是 | 初始通常为 Processing。 |
status_url | string | 是 | 任务状态查询地址。 |
result_url | string | 是 | 任务结果查询地址。 |
created_at | string(date-time) | 否 | 任务创建时间。 |
去水印说明
auto模式适合水印位置明显、希望自动识别处理的图片,不需要传boxes。manual模式适合你已知道水印区域的位置,需要传 1-5 个boxes。boxes坐标使用百分比而不是像素,范围为 0-100,便于不同分辨率图片复用同一标注方式。- 建议让
x1 < x2、y1 < y2,并让框选区域略大于水印本身,避免边缘残留。 - 接口创建的是异步任务;提交后继续调用
status_url和result_url获取处理结果。
抠图
/v1/images/remove-background
创建图片抠图任务,输出透明背景图片。
请求示例
{
"image_file_id": "123456789",
"industry_type": "portrait",
"quality_type": "original",
"trim_transparent_background": true
}传入参数
| 字段 | 类型 | 必填 | 说明 / 可选值 |
|---|---|---|---|
image_file_id | string | 是 | 待抠图图片文件 ID;支持 jpg、jpeg、png、webp、heic。 |
industry_type | enum | 否 | portrait、product、general 等;默认 portrait。 |
quality_type | enum | 否 | original 或 fast 等;默认 original。 |
trim_transparent_background | boolean | 否 | 是否裁切多余透明背景,默认 false。 |
返回 data 字段
| 字段 | 类型 | 必填 | 说明 / 可选值 |
|---|---|---|---|
task_id | string | 是 | 异步任务 ID。 |
status | TaskStatus | 是 | 初始通常为 Processing。 |
status_url | string | 是 | 任务状态查询地址。 |
result_url | string | 是 | 任务结果查询地址。 |
created_at | string(date-time) | 否 | 任务创建时间。 |
图片超分
/v1/images/upscale
创建图片超分任务,提升图片分辨率和清晰度。
请求示例
{
"image_file_id": "123456789",
"method": "ai_super_resolution",
"preset": "hd",
"type": "2X",
"enhance_face": true,
"enhance_quality": true
}传入参数
| 字段 | 类型 | 必填 | 说明 / 可选值 |
|---|---|---|---|
image_file_id | string | 是 | 待超分图片文件 ID;支持 heic、jpg、png、webp。 |
method | enum | 否 | ai_super_resolution、super_resolution、enhance;默认 ai_super_resolution。 |
preset | enum | 否 | auto 或 hd;默认 auto。 |
type | string | 否 | 超分倍率,默认 2X。 |
enhance_face | boolean | 否 | 是否增强人脸细节。 |
enhance_quality | boolean | 否 | 是否增强整体画质。 |
enhance_text | boolean | 否 | 是否增强文字清晰度。 |
返回 data 字段
| 字段 | 类型 | 必填 | 说明 / 可选值 |
|---|---|---|---|
task_id | string | 是 | 异步任务 ID。 |
status | TaskStatus | 是 | 初始通常为 Processing。 |
status_url | string | 是 | 任务状态查询地址。 |
result_url | string | 是 | 任务结果查询地址。 |
created_at | string(date-time) | 否 | 任务创建时间。 |
PDF 去水印
/v1/pdfs/remove-watermark
创建 PDF 去水印任务,支持结构化去水印和 AI 逐页重建。
请求示例
{
"pdf_file_id": "123456789",
"mode": "editable"
}传入参数
| 字段 | 类型 | 必填 | 说明 / 可选值 |
|---|---|---|---|
pdf_file_id | string | 是 | 待去水印 PDF 文件 ID。 |
mode | enum | 否 | editable 结构化去水印;ai 逐页图片重建。默认 editable。 |
返回 data 字段
| 字段 | 类型 | 必填 | 说明 / 可选值 |
|---|---|---|---|
task_id | string | 是 | 异步任务 ID。 |
status | TaskStatus | 是 | 初始通常为 Processing。 |
status_url | string | 是 | 任务状态查询地址。 |
result_url | string | 是 | 任务结果查询地址。 |
created_at | string(date-time) | 否 | 任务创建时间。 |
限制与计费
上传限制
| 字段 | 类型 | 必填 | 说明 / 可选值 |
|---|---|---|---|
单次创建文件数 | integer | 固定限制 | 最多 500 个文件。 |
单文件大小 | bytes | 固定限制 | 最大 2 GB。 |
分片阈值 | bytes | 固定规则 | upload_mode=auto 时,文件大于 5 MB 通常返回 upload_urls;simple 会固定尝试单文件上传。 |
上传地址有效期 | duration | 固定规则 | upload_url / upload_urls 约 2 小时有效,过期后重新 batch-create。 |
下载地址有效期 | duration | 固定规则 | download_url 约 24 小时有效,过期后重新查询 result_url 获取新地址。 |
- 大客户账号可能配置专属 API 倍率;实际扣费以服务端创建任务时的倍率快照为准。
- 图片去水印默认 API 价格:2 credits / 张。
- 抠图默认 API 价格:10 credits / 张。
- 图片超分默认 API 价格:6 credits / 张。
- PDF 去水印结构化模式默认 API 价格:4 credits / 文件。
- PDF 去水印 AI 模式默认 API 价格:2 credits / 页。
- GPT Image 2 无水印模式默认 API 价格:5.34 credits / 张输出图。
- Tidak ada ledger penggunaan API terpisah yang dibuat; catatan kredit tetap menjadi sumber kebenaran.
- Tugas web dan API berbagi pool berjalan yang sama: `Pending + Processing <= 20`.
- Versi pertama hanya mendukung API asinkron.
- 完整功能价格可查看 功能价格表。
- 图片编辑和 PDF 去水印接口需要传入文件 ID;如果你还没有文件 ID,请先调用
/v1/files/batch-create创建上传地址并完成文件上传。