メインコンテンツへスキップ
POST
参照素材をアップロードすると、成功時に公開 URL が直接返ります。ポーリングは不要です。アップロードは無料ですが、アカウント残高は 0 より大きい必要があります。3 つのアップロード API はユーザー単位の枠を共有し、既定では 72 時間に合計 2000 ファイルまでです。
ドキュメントの Playground はファイルアップロードに対応していません。以下の cURL・Python・JavaScript 例を使用してください。JavaScript 例には、ファイルを選択済みの <input type="file"> が必要です。

認証

string
必須
有効で、無効化・期限切れでない APIMart API Key を Bearer <token> として指定します。アカウントが停止されておらず、残高が正である必要があります。Key 自体の利用枠を使い切っていてもアップロードできます。Key は API Key 管理 で取得できます。

リクエストパラメータ

file
必須
multipart/form-data の file フィールドに、ファイル名付きで 1 ファイルを送信します。JSON、base64 文字列、ファイル URL で置き換えないでください。他のフォームフィールドは無視され、複数の file を送信した場合は最初の 1 件のみ処理されます。対応形式: MP4 (.mp4), MOV (.mov), WebM (.webm)既定のファイルサイズ上限: 50MB。サイズ上限は設定により変更されます。実際の設定と上限超過エラーの値を確認してください。
cURL の --form、Python の files、JavaScript の FormData では、boundary を含む Content-Type をクライアントに生成させてください。手動で指定しないでください。

ファイル検証

形式は拡張子やクライアント指定の MIME 型ではなく、内容から判定します。内容は送信先 API の種類と一致する必要があります。拡張子の変更は形式変換にはならず、不一致は HTTP 400 になります。 動画のコンテナ構造を検証し、偽装ヘッダーや破損したコンテナを拒否します。対応形式は下表のみです。AVI や MKV などは名前を変えてもアップロードできません。

成功レスポンス

HTTP 200 でファイル情報を返します。url は JSON の最上位にあり、data によるラップや生成タスク ID はありません。
string
ファイルの公開 URL。生成 API の対応する参照素材パラメータに渡します。モデルごとに形式・サイズ・数量・時間の制限があるため、アップロード成功だけでは利用できる保証はありません。
string
元のファイル名。
string
ファイル内容からサーバーが検出した MIME 型。クライアントの申告値ではありません。
string
ファイル種別。この API は video を返します。
integer
実際のファイルサイズ(バイト)。
integer
アップロード時刻(Unix 秒)。
object
任意のアップロード枠情報。制限がある場合のフィールドは下表のとおりです。無制限や統計の一時取得不可の場合は構造が異なります。

共有枠とリクエスト制限

画像・動画・音声で同じユーザー枠を共有します。同一ユーザーの Key を増やしても枠は増えません。毎正時に期間が移動し、既定では直近約 71–72 時間の成功分を数えます。形式不正、サイズ超過、保存失敗はファイル枠を消費しません。 通常の制限付きレスポンスには X-Upload-Quota-Limit、X-Upload-Quota-Remaining、X-Upload-Quota-Reset が付き、それぞれ limit、remaining、reset_at に対応します。Reset は Unix 秒です。 無制限の場合は quota: {"unlimited": true} を返し、上記 3 ヘッダーは付きません。統計を一時取得できない場合、成功レスポンスでも quota を省略することがあります。欠落を 0 や無制限と解釈したり、それだけを理由に再アップロードしたりしないでください。 ファイル枠を使い切ると HTTP 429、error.type: rate_limit_exceeded、quota(remaining: 0)、Retry-After を返します。指定秒数待って再試行してください。別途、Key ごとに 60 秒間 1000 リクエストの制限があり、こちらは rate_limit_error です。

エラー処理

エラーは JSON 最上位の error オブジェクトです。HTTP ステータス、error.type / error.code、error.message を確認してください。

URL とファイルの保存

72 時間は既定の統計期間であり、ファイル保存期間の保証ではありません。保持期間はストレージのポリシーに従います。元ファイルを保管し、URL は早めに生成に使用してください。永続 URL とは限りません。

他のアップロード API