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

# 將檔案上傳至 AceDataCloud 平台 CDN

> Platform 整合指南 - Ace Data Cloud

將本機檔案上傳至 AceDataCloud 平台 CDN，取得一個可公開存取的 URL（`https://cdn.acedata.cloud/xxxxxx.png` 風格），可立即在其他業務介面（如 Midjourney、Suno、Flux）的 `image_url`、`reference_url` 等參數中引用。

適用情境：

* 在呼叫 Midjourney `/midjourney/imagine` 前先將墊圖上傳至 CDN 取得 URL。
* 將上一步生成的影片快取起來作為下一步的輸入。
* 暫時代管使用者上傳的素材，避免自建 S3。

> ℹ️ 本介面屬於 **AceDataCloud 平台管理 API**，統一前綴 `https://platform.acedata.cloud/api/v1/`。

## 介面概覽

| 項目 | 內容 |
| - | - |
| 方法 | `POST` |
| URL | `https://platform.acedata.cloud/api/v1/files/` |
| 驗證 | ✅ 需要帳戶權杖 |
| Content-Type | `multipart/form-data`（**不是 JSON**） |

## 驗證說明（如何取得帳戶權杖）

請求標頭：

```http theme={null}
Authorization: Bearer ${PLATFORM_TOKEN}
```

取得方式：登入 [AceDataCloud 平台](https://platform.acedata.cloud) → [Account Token 控制台](https://platform.acedata.cloud/console/platform-tokens) → 點擊「建立」按鈕。詳見[管理 AceDataCloud 平台帳戶權杖](https://platform.acedata.cloud/documents/platform-token)。

## 請求主體（multipart/form-data）

| 欄位 | 類型 | 必填 | 說明 |
| - | - | - | - |
| `file` | file | ✅ | 二進位檔案串流。**單一檔案上限預設為 100 MB** |

## 請求範例

### cURL

```shell theme={null}
curl -X POST 'https://platform.acedata.cloud/api/v1/files/' \
  -H 'accept: application/json' \
  -H "authorization: Bearer ${PLATFORM_TOKEN}" \
  -F 'file=@./photo.jpg'
```

### Python

```python theme={null}
import os
import requests

PLATFORM_TOKEN = os.environ["PLATFORM_TOKEN"]

with open("photo.jpg", "rb") as f:
    resp = requests.post(
        "https://platform.acedata.cloud/api/v1/files/",
        headers={
            "accept": "application/json",
            "authorization": f"Bearer {PLATFORM_TOKEN}",
        },
        files={"file": ("photo.jpg", f, "image/jpeg")},
        timeout=60,
    )

data = resp.json()
print(f"✅ 上传成功：{data['file_url']}")
# 直接用于其他业务接口：
# requests.post("https://api.acedata.cloud/midjourney/imagine",
#     json={"prompt": "...", "image_urls": [data["file_url"]]}, ...)
```

### Node.js

```javascript theme={null}
const fs = require('fs')
const FormData = require('form-data')

const form = new FormData()
form.append('file', fs.createReadStream('./photo.jpg'))

const r = await fetch('https://platform.acedata.cloud/api/v1/files/', {
  method: 'POST',
  headers: {
    authorization: `Bearer ${process.env.PLATFORM_TOKEN}`,
    ...form.getHeaders(),
  },
  body: form,
})
const data = await r.json()
console.log('CDN URL:', data.file_url)
```

## 回應範例（HTTP 200）

```json theme={null}
{
  "file_url": "https://cdn.acedata.cloud/qrd7gw.jpg"
}
```

直接將 `file_url` 欄位拿到其他業務介面裡使用即可——CDN URL 目前可公開存取且無需驗證；不要將它視為永久封存的承諾。

## 回應欄位說明

| 欄位 | 類型 | 說明 |
| - | - | - |
| `file_url` | string | CDN 存取 URL |

## 錯誤處理

| HTTP | 回應範例 | 含義 |
| - | - | - |
| 400 | `{"error":"No file provided"}` | 未附上 `file` 欄位或欄位名稱不正確 |
| 401 | DRF 驗證錯誤回應 | 缺少或使用了無效帳戶權杖 |
| 413 | `{"error":"File too large","max_bytes":...}` | 檔案超過 100 MB（預設） |

## 實用提示

* **上傳圖片作為墊圖**：Midjourney `image_urls`、Flux `image_url`、Veo `reference_url` 都接受 CDN URL，**不**接受 base64。先使用本介面取得 URL 是常規操作。
* **不要上傳敏感資料**：回傳的 URL 可公開存取；保存期限以平台目前的儲存策略為準，長期封存請使用自己的物件儲存。
* **大量上傳**：控制並行數並為每次上傳設定逾時；吞吐量取決於檔案大小與網路環境。

## 相關介面

* [取得 AceDataCloud 平台服務清單](https://platform.acedata.cloud/documents/platform-service-list) — 找到接受 URL 輸入的業務服務
* [建立 AceDataCloud 平台 API 憑證](https://platform.acedata.cloud/documents/platform-credential-create) — 上傳後通常下一步是建立憑證呼叫業務介面


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.