メディアアップロード

動画生成と画像編集はどちらもメディア素材を扱います — 参照画像、参照動画と音声、ソース画像、マスクです。それらの送り方のルールはただ 1 つです：

• 素材がすでに公開インターネット上にある場合（あなたの CDN / オブジェクトストレージ） — その http(s) URL を直接渡すだけで、アップロードのオーバーヘッドはゼロです。動画の参照素材のみ。
• 素材がローカルにある場合 — まず presigned direct-to-R2 アップロードでアップロードし、返された upload_id を参照します。これはローカルファイルにとって唯一の経路であり、画像編集（ソースとマスク）にとっても唯一の経路です。

エンドポイントは POST https://api.alltoken.ai/v1/uploads/presign（複数形の uploads）です。アカウントサービスの /upload/presign と混同しないでください。後者はサイト内アバターなどの用途で、画像 MIME タイプのみを受け付けます。

ファイルが当社のゲートウェイを通過することはありません。一度きりの直接アップロード URL を取得し、生のバイトをオブジェクトストレージへ直接 PUT し、タスク作成時に返された upload_id を参照します。ゲートウェイが運ぶのは数十バイトの ID だけです。同じ仕組みが動画の参照素材と画像編集の両方に使われ、異なるのは purpose とそれを参照するフィールドだけです。

ステップ 1 — 直接アップロード URL をリクエストする：

ボディ：purpose（許可される MIME とサイズを決定 — 下記参照）、content_type（ファイルの MIME、小文字）、content_length（正確なバイト数）、content_md5、checksum_sha256。

レスポンスは upload_id（upl_ で始まる）、upload_url（presigned PUT の宛先）、required_headers（ステップ 2 でそのまま再送）、expires_in（URL の有効期間、300 秒）、claim_expires_at（upload_id の有効期間、2 時間）、max_content_length を返します。

ステップ 2 — 生のバイトを upload_url へ PUTし、required_headers 内のすべてのヘッダーを正確に再送します。ボディは生のファイルバイトです — base64 でも multipart でもありません：

ステップ 3 — upload_id を参照してタスクを作成します。動画は content[].upload_id に入れ、画像編集は image_upload_id / mask_upload_id のトップレベルフィールドを使います。ゲートウェイはバイト数と ETag を検証し、オブジェクトをそのタスク専用の恒久領域へ移し、上流からアクセス可能なアドレスとして提出します — すべてあなたには透過的で、あなたは 202 + task_id を受け取るだけです。

覚えておくべき 3 つのルール：

• 1 つの項目内で upload_id と URL フィールドは相互排他です — 両方を埋めると 400 upload_url_conflict を返します。
• presign とタスク作成は同じ API Key を使う必要があります — 所有権は（ユーザー + API Key + purpose）として検証され、Key を切り替えると 404 upload_not_found を返します。
• purpose は実際の用途と一致している必要があり、一致しない場合も 404 upload_not_found になります。

リクエストとレスポンスの完全なフィールド表は 画像 API と 動画 API のリファレンスにあります。

各 purpose は、許可される MIME タイプと 1 ファイルあたりのサイズ上限を固定します。

マスクが image/jpeg を拒否するのは、alpha チャンネルで「どこを変更するか」を表現する必要があり、jpeg には透明度がないためです。

つまり：URL を取得したらすぐにアップロードしてください。ただしその後、生成リクエストを組み立てて送信するまでに 2 時間の猶予があります。

upload_id はちょうど 1 つのタスクにバインドされ、再利用すると 409 upload_already_used を返します。これは意図的な設計です — 1 素材、1 タスク、1 請求。タスク作成に失敗した場合、一時オブジェクトは自動的に回収されます。

通常の「アップロードしてすぐ使う」ペースでこれらに達することはありません。大量の画像編集バッチでは日次上限に注意してください：25 MiB × 約 80 ファイルで 2 GiB に達します。

presign 段階：

バインド段階（タスク作成時）：