文件上传 API

把本地图片（或其他允许类型的文件）上传到 Picklyone 云端存储，返回一个 key。这个 key 可以直接作为 image_key 传给 图片编辑 API 做图生图。

什么时候用：只有在需要用外部图片做「图生图 / 锚定图编辑」时才需要。纯文生图（/v1/images/generations）不需要先上传。

请求

POST /api/v1/upload

请求头

Authorization: Bearer pk_live_xxxxxxxxxxxxxxxx
Content-Type: multipart/form-data

也支持 x-api-key 头（Anthropic SDK 风格）。

请求体（multipart/form-data）

响应

{
  "success": true,
  "uploaded": [
    {
      "key": "files/USER_ID/UUID_anchor.jpg",
      "filename": "anchor.jpg",
      "mimeType": "image/jpeg",
      "size": 184320,
      "isImage": true
    }
  ]
}

如果部分文件失败，会附带 errors 数组说明原因。

限制

校验：除 MIME 白名单外，服务端会做文件头「魔数」校验（防止把 .exe 改成 .jpg 混过去）和扩展名双重验证。

安全策略

• 文件按账户隔离存储，跨用户无法访问
• 文件内容仅供你自己的 API 调用使用（例如 /v1/images/edits）
• API Key 认证时，会应用你设置的 IP 白名单（与 /v1/chat/completions 同策略）

cURL 示例

curl -X POST https://api.picklyone.com/api/v1/upload \
  -H "Authorization: Bearer pk_live_xxxxxxxxxxxxxxxx" \
  -F "files=@/path/to/anchor.jpg"

多个文件一次上传：

curl -X POST https://api.picklyone.com/api/v1/upload \
  -H "Authorization: Bearer pk_live_xxxxxxxxxxxxxxxx" \
  -F "files=@/path/to/a.jpg" \
  -F "files=@/path/to/b.png"

Python 示例

import requests

API_KEY = "pk_live_xxxxxxxxxxxxxxxx"
BASE = "https://api.picklyone.com"

with open("anchor.jpg", "rb") as f:
    res = requests.post(
        f"{BASE}/api/v1/upload",
        headers={"Authorization": f"Bearer {API_KEY}"},
        files={"files": f},
    ).json()

image_key = res["uploaded"][0]["key"]
print("image_key:", image_key)

Node.js 示例

import fs from "fs";

const API_KEY = "pk_live_xxxxxxxxxxxxxxxx";
const BASE = "https://api.picklyone.com";

const form = new FormData();
form.append("files", new Blob([fs.readFileSync("anchor.jpg")], { type: "image/jpeg" }), "anchor.jpg");

const res = await fetch(`${BASE}/api/v1/upload`, {
  method: "POST",
  headers: { Authorization: `Bearer ${API_KEY}` },
  body: form,
});

const { uploaded } = await res.json();
console.log("image_key:", uploaded[0].key);

错误码

下一步

拿到 key 之后，调 图片编辑 API 做图生图。