curl --request POST \
--url https://api.apimart.ai/v1/uploads/videos \
--header 'Authorization: Bearer <token>' \
--form 'file=@/path/to/reference.mp4'
import requests
with open("reference.mp4", "rb") as file:
response = requests.post(
"https://api.apimart.ai/v1/uploads/videos",
headers={"Authorization": "Bearer <token>"},
files={"file": file}
)
response.raise_for_status()
result = response.json()
print(result["url"])
const input = document.querySelector('input[type="file"]');
const file = input?.files?.[0];
if (!file) throw new Error("Select a file first");
const formData = new FormData();
formData.append("file", file, file.name);
const response = await fetch("https://api.apimart.ai/v1/uploads/videos", {
method: "POST",
headers: { Authorization: "Bearer <token>" },
body: formData
});
const result = await response.json();
if (!response.ok) {
throw new Error(result.error?.message ?? `HTTP ${response.status}`);
}
console.log(result.url);
{
"url": "https://cdn.example/uploads/reference.mp4",
"filename": "reference.mp4",
"content_type": "video/mp4",
"file_type": "video",
"bytes": 235680,
"created_at": 1793836800,
"quota": {
"limit": 2000,
"used": 124,
"remaining": 1876,
"window_hours": 72,
"reset_at": 1794063600
}
}
{
"error": {
"message": "insufficient balance: uploading files requires a positive account balance, please top up",
"type": "insufficient_user_quota"
}
}
{
"error": {
"message": "video file exceeds maximum 52428800 bytes (50MB)",
"type": "invalid_request_error"
}
}
{
"error": {
"message": "upload limit reached: each account can upload at most 2000 files per 72 hours",
"type": "rate_limit_exceeded",
"code": "rate_limit_exceeded",
"param": ""
},
"quota": {
"limit": 2000,
"used": 2000,
"remaining": 0,
"window_hours": 72,
"reset_at": 1794063600
}
}
アップロード管理
動画をアップロード
MP4・MOV・WebM をアップロードし、生成 API 用の公開 URL を取得します。既定の上限は 1 ファイル 50MB。
POST
/
v1
/
uploads
/
videos
curl --request POST \
--url https://api.apimart.ai/v1/uploads/videos \
--header 'Authorization: Bearer <token>' \
--form 'file=@/path/to/reference.mp4'
import requests
with open("reference.mp4", "rb") as file:
response = requests.post(
"https://api.apimart.ai/v1/uploads/videos",
headers={"Authorization": "Bearer <token>"},
files={"file": file}
)
response.raise_for_status()
result = response.json()
print(result["url"])
const input = document.querySelector('input[type="file"]');
const file = input?.files?.[0];
if (!file) throw new Error("Select a file first");
const formData = new FormData();
formData.append("file", file, file.name);
const response = await fetch("https://api.apimart.ai/v1/uploads/videos", {
method: "POST",
headers: { Authorization: "Bearer <token>" },
body: formData
});
const result = await response.json();
if (!response.ok) {
throw new Error(result.error?.message ?? `HTTP ${response.status}`);
}
console.log(result.url);
{
"url": "https://cdn.example/uploads/reference.mp4",
"filename": "reference.mp4",
"content_type": "video/mp4",
"file_type": "video",
"bytes": 235680,
"created_at": 1793836800,
"quota": {
"limit": 2000,
"used": 124,
"remaining": 1876,
"window_hours": 72,
"reset_at": 1794063600
}
}
{
"error": {
"message": "insufficient balance: uploading files requires a positive account balance, please top up",
"type": "insufficient_user_quota"
}
}
{
"error": {
"message": "video file exceeds maximum 52428800 bytes (50MB)",
"type": "invalid_request_error"
}
}
{
"error": {
"message": "upload limit reached: each account can upload at most 2000 files per 72 hours",
"type": "rate_limit_exceeded",
"code": "rate_limit_exceeded",
"param": ""
},
"quota": {
"limit": 2000,
"used": 2000,
"remaining": 0,
"window_hours": 72,
"reset_at": 1794063600
}
}
参照素材をアップロードすると、成功時に公開 URL が直接返ります。ポーリングは不要です。アップロードは無料ですが、アカウント残高は 0 より大きい必要があります。3 つのアップロード API はユーザー単位の枠を共有し、既定では 72 時間に合計 2000 ファイルまでです。
ドキュメントの Playground はファイルアップロードに対応していません。以下の cURL・Python・JavaScript 例を使用してください。JavaScript 例には、ファイルを選択済みの
<input type="file"> が必要です。curl --request POST \
--url https://api.apimart.ai/v1/uploads/videos \
--header 'Authorization: Bearer <token>' \
--form 'file=@/path/to/reference.mp4'
import requests
with open("reference.mp4", "rb") as file:
response = requests.post(
"https://api.apimart.ai/v1/uploads/videos",
headers={"Authorization": "Bearer <token>"},
files={"file": file}
)
response.raise_for_status()
result = response.json()
print(result["url"])
const input = document.querySelector('input[type="file"]');
const file = input?.files?.[0];
if (!file) throw new Error("Select a file first");
const formData = new FormData();
formData.append("file", file, file.name);
const response = await fetch("https://api.apimart.ai/v1/uploads/videos", {
method: "POST",
headers: { Authorization: "Bearer <token>" },
body: formData
});
const result = await response.json();
if (!response.ok) {
throw new Error(result.error?.message ?? `HTTP ${response.status}`);
}
console.log(result.url);
{
"url": "https://cdn.example/uploads/reference.mp4",
"filename": "reference.mp4",
"content_type": "video/mp4",
"file_type": "video",
"bytes": 235680,
"created_at": 1793836800,
"quota": {
"limit": 2000,
"used": 124,
"remaining": 1876,
"window_hours": 72,
"reset_at": 1794063600
}
}
{
"error": {
"message": "insufficient balance: uploading files requires a positive account balance, please top up",
"type": "insufficient_user_quota"
}
}
{
"error": {
"message": "video file exceeds maximum 52428800 bytes (50MB)",
"type": "invalid_request_error"
}
}
{
"error": {
"message": "upload limit reached: each account can upload at most 2000 files per 72 hours",
"type": "rate_limit_exceeded",
"code": "rate_limit_exceeded",
"param": ""
},
"quota": {
"limit": 2000,
"used": 2000,
"remaining": 0,
"window_hours": 72,
"reset_at": 1794063600
}
}
認証
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。サイズ上限は設定により変更されます。実際の設定と上限超過エラーの値を確認してください。--form、Python の files、JavaScript の FormData では、boundary を含む Content-Type をクライアントに生成させてください。手動で指定しないでください。
ファイル検証
形式は拡張子やクライアント指定の MIME 型ではなく、内容から判定します。内容は送信先 API の種類と一致する必要があります。拡張子の変更は形式変換にはならず、不一致は HTTP400 になります。
動画のコンテナ構造を検証し、偽装ヘッダーや破損したコンテナを拒否します。対応形式は下表のみです。AVI や MKV などは名前を変えてもアップロードできません。
| 形式 | 検出される MIME 型 |
|---|---|
| MP4 (.mp4) | video/mp4 |
| MOV (.mov) | video/quicktime |
| WebM (.webm) | video/webm |
成功レスポンス
HTTP200 でファイル情報を返します。url は JSON の最上位にあり、data によるラップや生成タスク ID はありません。
string
ファイルの公開 URL。生成 API の対応する参照素材パラメータに渡します。モデルごとに形式・サイズ・数量・時間の制限があるため、アップロード成功だけでは利用できる保証はありません。
string
元のファイル名。
string
ファイル内容からサーバーが検出した MIME 型。クライアントの申告値ではありません。
string
ファイル種別。この API は
video を返します。integer
実際のファイルサイズ(バイト)。
integer
アップロード時刻(Unix 秒)。
object
任意のアップロード枠情報。制限がある場合のフィールドは下表のとおりです。無制限や統計の一時取得不可の場合は構造が異なります。
| フィールド | 説明 |
|---|---|
quota.limit | ユーザーが期間内に成功させられるアップロード数の上限。既定の 2000 と異なる場合があります。 |
quota.used | 今回の成功分を含む、期間内の使用数。 |
quota.remaining | 現在追加でアップロードできるファイル数。 |
quota.window_hours | 統計期間の時間数。既定は 72。 |
quota.reset_at | 最も古い一群が期間外になる時刻(Unix 秒)。一部の枠が空く時刻であり、全枠が一度にリセットされるとは限りません。 |
共有枠とリクエスト制限
画像・動画・音声で同じユーザー枠を共有します。同一ユーザーの 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 を確認してください。
| HTTP | error.type | 原因と対応 |
|---|---|---|
| 400 | invalid_request_error | ファイル欠落、multipart 以外、空ファイル、種類不一致、非対応形式、内容破損。ファイルまたは送信先を修正してください。 |
| 401 / 403 | — | Key が無効・無効化済み、またはアカウント停止。認証とアカウント状態を確認してください。 |
| 402 | insufficient_user_quota | 残高が 0 以下、または Key の期限切れ。入金するか有効な Key を使用してください。無料アップロードでも利用条件を満たす必要があります。 |
| 413 | invalid_request_error | 種類別のサイズ上限超過。圧縮・縮小し、エラーにある現在の上限を確認してください。 |
| 429 | rate_limit_exceeded | ユーザー共有枠を使い切りました。quota と Retry-After を読み、枠が空くまで待ってください。 |
| 429 | rate_limit_error | Key のリクエスト頻度が高すぎます。頻度を下げ、間隔を空けて再試行してください。 |
| 503 | server_error | 動画・音声の同時アップロード過多、またはストレージの一時停止。後で再試行してください。 |
| 500 | server_error | ストレージへの保存失敗。後で再試行してください。 |