ソース素材のアップロード

画像 / 音声 / 動画をアップロードし、再利用可能な 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）

アップロード

POST /v1/uploads

multipart/form-data、1 ファイル ≤100MB：

curl "$BEATRA_BASE_URL/uploads" \
  -H "Authorization: Bearer $BEATRA_API_KEY" \
  -F "[email protected]" \
  -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 が返ります：

{
  "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）も、後続タスクの入力として使用できます

完全なパラメータと制約 → エンドポイント定義

ソース素材のアップロード

アップロード

ルール

On this page