# ソース素材のアップロード
> 画像 / 音声 / 動画をアップロードし、再利用可能な artifact_id を取得します。

ソース素材を必要とする機能（画像から画像、画像から動画、ボイスクローン、参照オーディオから音楽など）は 3 種類の参照方式を受け付けます。**artifact が最も確実**です：

| 形式 | 書き方 | 用途 |
| --- | --- | --- |
| アップロード済み素材 | `{ "type": "artifact", "artifact_id": "artifact_..." }` | 推奨。再利用でき、外部リンク切れの影響を受けない |
| 公開 URL | `{ "type": "url", "url": "https://..." }` | 素材にすでに公開 URL がある場合。プラットフォームがダウンロードして保存する |
| Data URI | `{ "type": "data_uri", "data": "data:image/png;base64,..." }` | 小さいファイル（エンコード後 ≤256KB） |

## アップロード

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

`multipart/form-data`、1 ファイル ≤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/ja/docs/api-reference/operations/uploads/upload_v1_uploads_post)