文件上传

上传图片、视频、音频文件并获取公开 URL,用于后续生成接口的素材引用。

重要变更: 为了更好的性能和成本控制,我们不再支持在生成接口中直接传入 base64 图片数据。请使用本接口上传文件,获取 URL 后再调用生成接口。

存储空间配额

每个用户的上传总空间按存储套餐独立计费,与 API 额度套餐无关:

套餐	存储空间	月费
Free	100 MB	免费
Standard	500 MB	$4.99/月
Pro	1 GB	$9.99/月
Ultra	5 GB	$24.99/月

存储套餐为 Stripe 月度自动续费订阅。空间不足时上传将返回 413 storage_quota_exceeded。

查看当前用量:GET /api/v1/storage/status;购买或升级存储套餐:POST /api/v1/storage/checkout,详见控制台 → 存储管理。

为什么需要先上传文件?

性能优化 — base64 编码使数据膨胀 33%,先上传可显著减少请求体大小
复用文件 — 上传一次,URL 可多次使用,无需重复传输
统一管理 — 图片、视频、音频统一入口,一个接口搞定

使用流程

客户端                  CokeAPI                 存储
  │                       │                      │
  │  POST /v1/uploads     │                      │
  │  (上传文件)           │                      │
  │ ─────────────────────>│                      │
  │                       │   保存文件            │
  │                       │ ────────────────────>│
  │                       │   返回存储路径        │
  │                       │ <────────────────────│
  │   返回文件 URL         │                      │
  │ <─────────────────────│                      │
  │                       │                      │
  │  POST /v1/images/edits (使用文件 URL)         │
  │ ─────────────────────>│                      │

鉴权

使用 API Key 进行认证,与其他 /v1 接口一致:

Authorization: Bearer sk-xxxxxxxx

获取 API Key:访问控制台 → API Key 管理。

调用示例

curl https://cokeapi.com/v1/uploads \
  -H "Authorization: Bearer sk-xxxxxxxx" \
  -F file=@photo.jpg

import httpx

# 1. 上传图片
with open("photo.jpg", "rb") as f:
    r = httpx.post(
        "https://cokeapi.com/v1/uploads",
        headers={"Authorization": "Bearer sk-xxxxxxxx"},
        files={"file": f},
    )
upload = r.json()
image_url = upload["url"]
print(f"文件 URL: {image_url}")

# 2. 在生成接口中使用
r = httpx.post(
    "https://cokeapi.com/v1/video/generations",
    headers={
        "Authorization": "Bearer sk-xxxxxxxx",
        "Content-Type": "application/json",
    },
    json={
        "model": "grok-video-3",
        "prompt": "镜头缓慢拉远,主体向左转头",
        "ref_image_url": image_url,
    },
)
print(r.json())

const KEY = process.env.COKEAPI_KEY;

// 1. 上传图片
const form = new FormData();
form.append("file", fs.createReadStream("photo.jpg"));

const upload = await fetch("https://cokeapi.com/v1/uploads", {
  method: "POST",
  headers: { Authorization: `Bearer ${KEY}` },
  body: form,
});
const { url: imageUrl } = await upload.json();
console.log(`文件 URL: ${imageUrl}`);

// 2. 在生成接口中使用
const gen = await fetch("https://cokeapi.com/v1/video/generations", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "grok-video-3",
    prompt: "镜头缓慢拉远,主体向左转头",
    ref_image_url: imageUrl,
  }),
});
console.log(await gen.json());

请求参数

参数	类型	必填	默认值	说明
file	file	是	—	上传的文件 (multipart/form-data)。无需指定文件类型,服务端自动通过内容嗅探 (magic bytes) 判定 MIME 类型并归类为 image / video / audio
purpose	string	否	generation	上传用途标记,可选

支持的文件格式与大小限制

类型	支持格式	单文件上限
图片	JPEG, PNG, WebP, GIF	10 MB
视频	MP4, WebM, MOV	100 MB
音频	MP3, WAV, OGG, FLAC, AAC, M4A	50 MB

响应

成功 (200)

{
  "id": "a1b2c3d4e5f6a1b2c3d4e5f6ab",
  "object": "file",
  "url": "https://cdn.cokeapi.com/uploads/2026/05/17/xxxxxxxx.jpg",
  "filename": "photo.jpg",
  "mime_type": "image/jpeg",
  "size": 89234,
  "purpose": "generation",
  "duration_ms": 438,
  "created": 1747468800
}

错误

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_request_error",
    "message": "unsupported file type: application/pdf; allowed: JPEG, PNG, WebP, GIF, MP4, WebM, MOV, MP3, WAV, OGG, FLAC, AAC, M4A"
  }
}

状态码	type	含义
400	`invalid_request_error`	缺少 file 字段 / 格式不支持 / 文件过大
401	`invalid_api_key`	API Key 无效
403	`scope_not_allowed`	API Key 无 image/video 权限
413	`storage_quota_exceeded`	存储空间已满,升级套餐可获取更多空间
429	`rate_limit_exceeded`	频率超限
502	`upstream_error`	存储服务异常

注意事项

上传的文件对所有持有 URL 的人公开,不要上传敏感内容。
文件永久保留,不会主动删除。但文件 URL 不保证永久有效,需要持久访问请下载到自有 OSS。
文件类型通过服务端内容嗅探判定,不信任客户端 Content-Type,伪造扩展名无法绕过校验。
上传接口与其他 /v1 接口共享 API Key 的 RPM 限流和每日配额。
响应中的 duration_ms 是服务端处理本次上传的总耗时;管理员可通过 GET /admin/api/v1/logs/uploads/{upload_id} 查询 sniff_mime / quota_check / storage_upload / db_create 等阶段日志。

上传历史查询

GET /v1/uploads 分页查询当前 API Key 所属用户的上传记录。

调用示例

curl "https://cokeapi.com/v1/uploads?page=1&page_size=20&kind=image" \
  -H "Authorization: Bearer sk-xxxxxxxx"

import httpx

r = httpx.get(
    "https://cokeapi.com/v1/uploads",
    headers={"Authorization": "Bearer sk-xxxxxxxx"},
    params={"page": 1, "page_size": 20, "kind": "image"},
)
data = r.json()
for item in data["data"]:
    print(f"{item['filename']} → {item['url']}")
print(f"共 {data['total']} 条")

const r = await fetch(
  "https://cokeapi.com/v1/uploads?page=1&page_size=20&kind=image",
  { headers: { Authorization: `Bearer ${process.env.COKEAPI_KEY}` } },
);
const data = await r.json();
data.data.forEach((f) => console.log(`${f.filename} → ${f.url}`));
console.log(`共 ${data.total} 条`);

请求参数

参数	类型	必填	默认值	说明
page	int	否	1	页码,从 1 开始
page_size	int	否	20	每页条数,最大 100
kind	string	否	—	按类型过滤:image / video / audio,留空返回全部

响应

{
  "object": "list",
  "data": [
    {
      "id": "a1b2c3d4e5f6a1b2c3d4e5f6ab",
      "object": "file",
      "url": "https://cdn.cokeapi.com/uploads/2026/05/17/xxxxxxxx.jpg",
      "filename": "photo.jpg",
      "mime_type": "image/jpeg",
      "size": 89234,
      "kind": "image",
      "purpose": "generation",
      "duration_ms": 438,
      "created": 1747468800
    }
  ],
  "total": 42,
  "page": 1,
  "page_size": 20,
  "storage_used": 5242880,
  "storage_limit": 104857600
}

字段	说明
`storage_used`	当前用户已用存储空间 (字节)
`storage_limit`	当前套餐存储上限 (字节),详见上方存储空间配额

本页目录