> ## 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.

# 画像アップロードガイド

> 画像をアップロードして一時的な公開 URL を取得し、画像入力対応 API で使用する方法

> 更新日: 2026-06-21

Crazyrouter は、モデルが読み取れる一時的な公開画像 URL を作成するためのアップロード API を提供しています。Vision、画像編集、画像から動画、ワークフロー連携などで利用できます。

<Note>
  一時画像はデフォルトで 48 時間保存され、その後自動的に削除されます。保存期間中のストレージは個別課金されませんが、ユーザー単位のアップロード容量とレート制限があります。
</Note>

## Endpoint Overview

| Scenario                   | Endpoint                         |
| -------------------------- | -------------------------------- |
| Local file upload          | `POST /v1/files/uploads`         |
| Base64 image upload        | `POST /v1/files/uploads/base64`  |
| Remote image rehosting     | `POST /v1/files/uploads/url`     |
| Presigned direct R2 upload | `POST /v1/files/uploads/presign` |

Common limits:

| Item               | Current rule                                                  |
| ------------------ | ------------------------------------------------------------- |
| Auth               | `Authorization: Bearer YOUR_API_KEY`                          |
| Supported formats  | `image/png`, `image/jpeg`, `image/webp`, `image/gif`          |
| Single file size   | 20MB                                                          |
| User upload quota  | 200MB / rolling 24-hour window                                |
| Default expiration | 48 hours                                                      |
| Returned URL       | `https://media.crazyrouter.com/task-artifacts/tmp-inputs/...` |

## Presigned Direct R2 Upload

大量アップロードのワークフローでは、まず presigned upload URL を取得し、クライアントからストレージへ直接 `PUT` できます。画像バイナリは Crazyrouter のアプリケーションサーバーを経由しません。

```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"
  }'
```

Example response:

```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"
}
```

Then upload directly:

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

アップロード完了後、モデルリクエストでは `upload_url` ではなく、返却された `url` を使用してください。

<Warning>
  `upload_url` は短時間だけ有効な書き込み用 URL です。`Content-Type` と `Content-Length` は presign リクエストと一致している必要があります。
</Warning>