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