# 上传源素材
> 上传图片 / 音频 / 视频，拿到可复用的 artifact_id。

需要源素材的能力（图生图、图生视频、声音克隆、参考音频生音乐等）接受三种引用方式，**artifact 最稳妥**：

| 形式 | 写法 | 适用 |
| --- | --- | --- |
| 上传产物 | `{ "type": "artifact", "artifact_id": "artifact_..." }` | 推荐；可复用、不受外链失效影响 |
| 公网 URL | `{ "type": "url", "url": "https://..." }` | 素材已有公网地址；平台会下载转存 |
| Data URI | `{ "type": "data_uri", "data": "data:image/png;base64,..." }` | 小文件（编码后 ≤256KB） |

## 上传

```http
POST /v1/uploads
```

`multipart/form-data`，单文件 ≤100MB：

```bash curl
curl "$BEATRA_BASE_URL/uploads" \
  -H "Authorization: Bearer $BEATRA_API_KEY" \
  -F "file=@sample.mp3" \
  -F "purpose=voice_clone_source"
```

`purpose` 可选：`media_input`（默认）· `reference_audio` · `voice_clone_source`。

支持的 MIME 类型：`image/png`、`image/jpeg`、`image/webp`、`image/gif`、`image/bmp`、`image/tiff`、
`audio/mpeg`、`audio/mp3`、`audio/wav`、`audio/x-wav`、`audio/mp4`、
`audio/x-m4a`、`audio/aac`、`audio/flac`、`audio/ogg`、`audio/webm`、
`video/mp4`、`video/webm` 和 `video/quicktime`。如果 multipart 客户端发送
`application/octet-stream`（上述 `curl` 示例可能如此），Beatra 会根据文件签名
识别具体类型。声明类型与内容不符或类型不受支持时，会在写入存储前返回
`422 invalid_media`。

返回 `201`：

```json
{
  "object": "upload",
  "artifact_id": "artifact_01JX...",
  "cdn_url": "https://cdn.beatra.ai/.../sample.mp3",
  "mime_type": "audio/mpeg",
  "media_type": "audio",
  "size_bytes": 2097152,
  "duration_ms": 131000,
  "checksum_sha256": "9f86d08..."
}
```

## 规则

- **秒传去重**：相同内容（按 `checksum_sha256`）重复上传返回 `201` 和已有的 `artifact_id`，不重复计存储；
- **超限**：>100MB 返回 `413 media_too_large`；更大文件的分片上传暂未开放；
- **类型校验**：只接受图片、音频和视频；`media_type` 不传时按已验证的 MIME 自动推断；类型不匹配或签名无效会在写入存储前返回 `422`；
- 生成任务的产物（`output` 里的 `artifact_id`）同样可以作为后续任务的输入。

完整参数与约束 → [接口定义](https://docs.beatra.ai/zh/docs/api-reference/operations/uploads/upload_v1_uploads_post)