Pilio API Documentation

鉴权

Base URL

https://pilio.ai

Content-Type

application/json

认证方式

Authorization: Bearer <API Key> 或 X-API-Key: <API Key>

Send your API key with every request:

Authorization: Bearer pilio_sk_your_key_here
# or
X-API-Key: pilio_sk_your_key_here

`X-API-Key` is also accepted for compatibility. API keys are permanent until you revoke them in your account.

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"

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 接入提示

响应外壳

所有成功响应都包在 code、message、data 中；业务字段位于 data。

{
  "code": 200,
  "message": "success",
  "data": { ... }
}

文件上传与下载

{
  "files": [
    {
      "nanoid": "V1StGXR8_Z5jdHi6B-myT",
      "name": "reference.png",
      "type": "png",
      "size": 1024
    }
  ],
  "upload_mode": "simple",
  "storage_intent": "temporary"
}

{
  "parts": [
    { "part_number": 1, "etag": ""etag-from-upload-response"" }
  ]
}

任务查询

All creation endpoints return immediately with a task ID.

{
  "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` until the task reaches `Succeeded` or `Failed`, then read result files from `result_url`.

无请求体。

无请求体。

公共结构

错误处理

失败响应仍使用同一层响应外壳。AI 生成代码时应优先判断 code !== 200，再读取 message 和 data；不要通过自然语言 message 推断业务状态。

{
  "code": 1402,
  "message": "Invalid token",
  "data": null
}

OpenAPI 文件

如果你只需要把接口导入 API 测试工具，直接下载上面的 OpenAPI JSON 即可。页面正文用于快速阅读，OpenAPI 文件用于测试、调试和作为生成代码的结构化真源。

SDK

Pilio 目前不维护官方 SDK。现在大量接入代码会由 AI 生成，官方维护多语言 SDK 反而容易滞后；推荐把 OpenAPI JSON 作为真源，按项目语言生成类型、请求方法，或让 AI 直接基于接口描述写薄封装。