> ## Documentation Index
> Fetch the complete documentation index at: https://docs.crazyrouter.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 图片上传说明

> 上传本地图片并获取 48 小时临时公网 URL，用于图生图、图生视频和识图接口

> 更新日期：2026-06-06

Crazyrouter 提供临时公网图片上传接口，用于把本地参考图转换成模型可访问的公网 URL。它适合 Kling、Veo、Seedance、Runway、Luma、MiniMax、Nano Banana Pro、Doubao Seedream 等需要 `image_url`、`image_urls`、`image_list`、`images` 或 `image_input` 的接口。

<Note>
  临时图片默认保存 48 小时，到期自动清理。存储期内不单独按天收费；当前按用户上传额度和速率限制防滥用。
</Note>

## 接口概览

| 场景          | 接口                               |
| ----------- | -------------------------------- |
| 本地文件上传      | `POST /v1/files/uploads`         |
| Base64 图片上传 | `POST /v1/files/uploads/base64`  |
| 远程图片转存      | `POST /v1/files/uploads/url`     |
| 预签名直传 R2    | `POST /v1/files/uploads/presign` |

通用限制：

| 项目     | 当前规则                                                          |
| ------ | ------------------------------------------------------------- |
| 鉴权     | `Authorization: Bearer YOUR_API_KEY`                          |
| 支持格式   | `image/png`、`image/jpeg`、`image/webp`、`image/gif`             |
| 单文件大小  | 20MB                                                          |
| 用户上传额度 | 200MB / 24 小时滚动窗口                                             |
| 默认有效期  | 48 小时                                                         |
| 返回 URL | `https://media.crazyrouter.com/task-artifacts/tmp-inputs/...` |

## 本地文件上传

```bash cURL theme={null}
curl -X POST https://api.crazyrouter.com/v1/files/uploads \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@./reference.png" \
  -F "purpose=model_input"
```

返回示例：

```json theme={null}
{
  "id": "file_e5bbce820b5941409682a9c5e9ba79f1",
  "url": "https://media.crazyrouter.com/task-artifacts/tmp-inputs/2026/05/13/user-1/file_e5bbce820b5941409682a9c5e9ba79f1.png",
  "mime_type": "image/png",
  "size": 2025,
  "expires_at": "2026-05-16T04:41:35.0131789Z"
}
```

## Base64 上传

```bash cURL theme={null}
curl -X POST https://api.crazyrouter.com/v1/files/uploads/base64 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "data": "data:image/png;base64,iVBORw0KGgoAAA...",
    "filename": "reference.png",
    "purpose": "model_input"
  }'
```

## 远程 URL 转存

```bash cURL theme={null}
curl -X POST https://api.crazyrouter.com/v1/files/uploads/url \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "url": "https://example.com/reference.png",
    "filename": "reference.png",
    "purpose": "model_input"
  }'
```

远程 URL 必须是 Crazyrouter 服务端可访问的 `http` 或 `https` 图片地址。系统会做文件大小、MIME 类型和 SSRF 防护检查。

## 预签名直传 R2

高上传量场景可以先申请预签名上传 URL，然后由客户端直接把图片 `PUT` 到存储端点。这样图片二进制不会经过 Crazyrouter 应用服务器，适合每天大量图片上传的工作流。

第一步，申请直传 URL：

```bash cURL theme={null}
curl -X POST https://api.crazyrouter.com/v1/files/uploads/presign \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "filename": "reference.jpg",
    "content_type": "image/jpeg",
    "size": 12345,
    "purpose": "model_input"
  }'
```

返回示例：

```json theme={null}
{
  "id": "file_e5bbce820b5941409682a9c5e9ba79f1",
  "upload_url": "https://...r2.cloudflarestorage.com/...?...",
  "url": "https://media.crazyrouter.com/task-artifacts/tmp-inputs/2026/06/21/user-1/file_e5bbce820b5941409682a9c5e9ba79f1.jpg",
  "method": "PUT",
  "headers": {
    "Content-Type": "image/jpeg",
    "Content-Length": "12345"
  },
  "mime_type": "image/jpeg",
  "size": 12345,
  "expires_at": "2026-06-22T04:41:35Z",
  "upload_expires_at": "2026-06-21T04:56:35Z"
}
```

第二步，客户端直接上传到 `upload_url`：

```bash cURL theme={null}
curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: image/jpeg" \
  -H "Content-Length: 12345" \
  --data-binary @./reference.jpg
```

上传完成后，把返回里的 `url` 作为模型请求中的图片 URL。

<Warning>
  `upload_url` 是短期有效的写入地址，默认约 15 分钟内使用。`Content-Type` 和 `Content-Length` 必须与申请时一致；不要把 `upload_url` 传给模型，模型请求中应使用返回的 `url`。
</Warning>

## 实际案例：本地参考图用于 Kling 图生视频

第一步，上传本地参考图：

```bash cURL theme={null}
UPLOAD_RESPONSE=$(curl -sS -X POST https://api.crazyrouter.com/v1/files/uploads \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@./portrait.png" \
  -F "purpose=model_input")

IMAGE_URL=$(python -c "import json,sys; print(json.load(sys.stdin)['url'])" <<< "$UPLOAD_RESPONSE")
echo "$IMAGE_URL"
```

第二步，把返回的 `IMAGE_URL` 传给 Kling 图生视频：

```bash cURL theme={null}
curl -X POST https://api.crazyrouter.com/kling/v1/videos/image2video \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d "{
    \"model_name\": \"kling-v3\",
    \"prompt\": \"图片中的人物缓缓转头并微笑，镜头轻微推进，电影级光影\",
    \"image_urls\": [\"$IMAGE_URL\"],
    \"duration\": \"5\",
    \"mode\": \"std\"
  }"
```

提交成功后会返回任务 ID。通过 [Kling 任务查询](/video/kling/query) 获取终态视频结果。

<Warning>
  临时 URL 不是永久素材库。请在任务提交前确保 URL 仍未过期，不要把它作为长期业务图片地址保存。
</Warning>