VanceAI Open API documentation

API は VanceAI の処理エンジンを、小さく安定した REST エンドポイント群として公開します。ファイルまたは URL でジョブを送信し、完了をポーリングして結果をダウンロードします。画像と動画の両ツールは同じ /v1/jobs リソース配下にあり、選んだ tool がメディアタイプと処理内容を決めます。

すべての API リクエストの送信先：

https://cloud-vanceai.vanceai.com/api/v1

すべてのレスポンスは application/json です。すべてのリクエストは API キーで認証する必要があります — 認証を参照してください。

API は完全に非同期で、3 つのステップで構成されます：

POST /v1/jobs            → returns a job_id immediately (status: "queued")
GET  /v1/jobs/{id}       → poll until status is "succeeded" or "failed"
GET  /v1/jobs/{id}/result → fetch a fresh, never-expiring download link

POST はアップロードや処理中にブロックしません。リクエストを検証してジョブを予約し、数ミリ秒で job_id を返します。その後はバックグラウンドワーカーがアップロード・処理・結果を担うため、数ギガバイトの動画でも HTTP タイムアウトに達することなく処理できます。

• 認証 — API キーの取得と使用。
• クイックスタート — 数分で最初のジョブを実行。
• ジョブとライフサイクル — エンドポイントの完全リファレンス。

キーは次のような形式で、常に sk_live_ プレフィックスで始まります：

sk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

キーは VanceAI アカウントのダッシュボードで作成・無効化します。完全なキーは作成時に一度だけ表示されます — 安全な場所に保管してください。紛失した場合はキーを無効化して新規作成します。API キーの管理を参照してください。

すべてのリクエストで、キーを Authorization ヘッダーに bearer トークンとして送信します：

Authorization: Bearer sk_live_a1b2c3d4e5f6...

例えば、クレジット残高を確認するには：

curl https://cloud-vanceai.vanceai.com/api/v1/credits \
  -H "Authorization: Bearer sk_live_a1b2c3d4e5f6..."

キーが欠落・不正・無効化されている場合は、安定したエラーコードとともに 401 を返します：

{
  "error": {
    "code": "invalid_api_key",
    "message": "The API key provided is invalid or has been disabled.",
    "type": "auth"
  }
}

コードの全リストと処理方法はエラーを参照してください。

画像を tool とその config とともに multipart form data で送信します。ファイルを直接アップロード（最大 200 MB）するか、公開 image_url を渡せます。

curl https://cloud-vanceai.vanceai.com/api/v1/jobs \
  -H "Authorization: Bearer sk_live_..." \
  -F [email protected] \
  -F tool=upscale \
  -F 'config={"scale":4,"face_enhance":true}' \
  -F output_format=jpg

または JSON ボディで URL を送信します：

curl https://cloud-vanceai.vanceai.com/api/v1/jobs \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://example.com/photo.jpg",
    "tool": "upscale",
    "config": { "scale": 4, "face_enhance": true },
    "output_format": "jpg"
  }'

レスポンスは即座に job_id と queued ステータスを返します：

{
  "job_id": "job_3f2a9c...",
  "status": "queued",
  "tool": "upscale",
  "media": "image",
  "credits_estimated": 1.0,
  "credits_charged": 0,
  "created_at": "2026-06-11T08:30:00Z"
}

status が succeeded（または failed）になるまで GET /v1/jobs/{job_id} をポーリングします。画像なら約 2 秒間隔で十分です。

curl https://cloud-vanceai.vanceai.com/api/v1/jobs/job_3f2a9c... \
  -H "Authorization: Bearer sk_live_..."

{
  "job_id": "job_3f2a9c...",
  "status": "succeeded",
  "progress": 100,
  "tool": "upscale",
  "result_url": "https://.../preview?sign=...",
  "result": { "width": 4000, "height": 3000, "size": 2451234 },
  "error": null,
  "created_at": "2026-06-11T08:30:00Z",
  "finished_at": "2026-06-11T08:30:42Z"
}

ステップ 2 の result_url は署名付きリンクで、いずれ期限切れになります。期限切れにならないリンクには、必要時に再署名する result エンドポイントを呼び出します：

curl -L https://cloud-vanceai.vanceai.com/api/v1/jobs/job_3f2a9c.../result \
  -H "Authorization: Bearer sk_live_..." \
  -o upscaled.jpg

すべてのジョブは次のステータスを遷移します：

processing 中は phase フィールドで段階を絞り込めます：uploading → syncing → processing。数値の progress（0–100）は phase が processing になって初めて意味を持ち、アップロード／同期中は 0 のままです。大きな動画ではアップロード段階が数分かかることがあります — 「止まっているか」は progress ではなく phase で判断してください。

動画は 2 ステップでストレージへ直接アップロードします。バイトが API を経由しないため、数ギガバイトのファイルでもリクエストサイズに制限されません。まず POST /v1/uploads を呼び出して使い捨ての署名付きアップロード URL を取得し、そこへファイルを PUT します。画像はこの手順を省き、ジョブ作成時にインラインでアップロードします（下記参照）。動画の multipart 直接アップロードには対応していません。代替として source_url は引き続き利用できます。

リクエストパラメータ

例

curl https://cloud-vanceai.vanceai.com/api/v1/uploads \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "file_name": "clip.mp4",
    "file_size": 734003200,
    "content_type": "video/mp4"
  }'

レスポンス — 201 Created

{
  "upload_id": "upl_8f3b1c2a...",
  "put_url": "https://<bucket>.r2.cloudflarestorage.com/...&X-Amz-Signature=...",
  "expires_at": "2026-06-13T08:30:00Z",
  "max_bytes": 5261334937
}

put_url は 24 時間有効な署名付き URL です。認証ヘッダーなしで、ファイルだけを 1 回の PUT でアップロードします：

curl -X PUT --upload-file clip.mp4 \
  -H "Content-Type: video/mp4" \
  "https://<bucket>.r2.cloudflarestorage.com/...&X-Amz-Signature=..."

PUT が成功したら、ファイルの代わりに upload_id を渡してジョブを作成します — ジョブを作成するを参照。各 upload_id は 1 回限り使用できます。

curl https://cloud-vanceai.vanceai.com/api/v1/jobs \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "upload_id": "upl_8f3b1c2a...",
    "tool": "video_upscale",
    "config": { "scale": 2, "codec": "h264" }
  }'

{
  "job_id": "job_3f2a9c...",
  "status": "queued",
  "tool": "video_upscale",
  "media": "video",
  "credits_estimated": 0,
  "credits_charged": 0,
  "created_at": "2026-06-11T08:30:00Z"
}

メディアの指定方法はタイプによって異なります。画像：ファイルの直接アップロード（multipart）または公開 URL。動画：上記のアップロード手順で得た upload_id、または公開 source_url。tool がメディアタイプと処理を選択します。

リクエストパラメータ

冪等性

Idempotency-Key ヘッダーを渡すと、ジョブを重複させずに作成リクエストを安全に再試行できます。レート制限と冪等性を参照。

例

curl https://cloud-vanceai.vanceai.com/api/v1/jobs \
  -H "Authorization: Bearer sk_live_..." \
  -H "Idempotency-Key: a-unique-string" \
  -F [email protected] \
  -F tool=upscale \
  -F 'config={"scale":4,"face_enhance":true}'

レスポンス — 202 Accepted

{
  "job_id": "job_3f2a9c...",
  "status": "queued",
  "tool": "upscale",
  "media": "image",
  "credits_estimated": 1.0,
  "credits_charged": 0,
  "created_at": "2026-06-11T08:30:00Z"
}

レスポンスはクレジットが課金される前に返ります（credits_charged は 0）。credits_estimated は事前見積もりで、確定額はジョブが processing に達した時点で反映されます。クレジットと課金を参照。

ジョブの現在のステータスを返します。ジョブが終了ステータスに達するまでポーリングします。

レスポンス — 200（processing）

{
  "job_id": "job_3f2a9c...",
  "status": "processing",
  "phase": "uploading",
  "progress": 0,
  "tool": "video_upscale",
  "media": "video",
  "result_url": null,
  "result": null,
  "error": null,
  "created_at": "2026-06-11T08:30:00Z",
  "finished_at": null
}

レスポンス — 200（succeeded）

{
  "job_id": "job_3f2a9c...",
  "status": "succeeded",
  "progress": 100,
  "tool": "upscale",
  "result_url": "https://.../preview?sign=...",
  "result": { "width": 4000, "height": 3000, "size": 2451234 },
  "error": null,
  "created_at": "2026-06-11T08:30:00Z",
  "finished_at": "2026-06-11T08:30:42Z"
}

result の形は画像で { width, height, size }、動画で { width, height, duration, size, codec } です。result_url は署名付きリンクで期限切れになります — 恒久リンクには下記の result エンドポイントを使用してください。

新しく署名された結果 URL に（302）リダイレクトします — 呼び出すたびに再署名されるため、リンクは期限切れになりません。result_url をキャッシュするのではなく、出力をダウンロードする際は常にこれを使用してください。

curl -L https://cloud-vanceai.vanceai.com/api/v1/jobs/job_3f2a9c.../result \
  -H "Authorization: Bearer sk_live_..." \
  -o result.jpg

まだ queued または processing のジョブをキャンセルします。主に長時間の動画ジョブで有用です。予約済みクレジットは全額返還されます。

{ "job_id": "job_3f2a9c...", "status": "canceled" }

すでに succeeded・failed・canceled のジョブは 409 not_cancelable を返します。

ジョブレコードと関連する結果を削除します — プライバシーやコンプライアンス目的で処理済みアセットを整理するのに便利です。ジョブがまだ進行中の場合は、先にキャンセルされ（クレジットは返還され）ます。

{ "job_id": "job_3f2a9c...", "deleted": true }

• すでに削除済みのジョブを削除しても 200 { "deleted": true } を返します（冪等）。
• 削除できるのは自分のアカウントのジョブのみです。それ以外は 404 job_not_found を返します。

画像ツールは config オブジェクトを取ります。face_enhance オプション（真偽値）はほとんどのツールで任意です。リクエストに output_format を設定して jpg / png / webp を選びます。

{ "scale": 4, "face_enhance": true }

動画ツールはエンドツーエンドで処理されます（v1 にプレビュークリップモードはありません）。quality（high / medium / low）と codec（h264 / h265）のオプションは video_hdr と video_face_enhance にのみ適用されます。video_upscale では出力エンコードがアップスケールエンジンによって決定されるため、quality / codec は使用されません（指定しても効果はありません）。

{ "scale": 2 }

存在しないツール、または未提供のツール（動画の translate・colorize・subtitle は v1 にありません）を要求すると 400 unsupported_tool を返します。

ジョブのライフサイクルにおけるクレジットの流れ：

curl https://cloud-vanceai.vanceai.com/api/v1/credits \
  -H "Authorization: Bearer sk_live_..."

{ "balance": 999.8, "used": 234.2, "frozen": 12.5 }

クレジット量は小数です（一部の処理は 1 クレジット未満を消費します）。

各 API キーにはリクエストレート制限があります。超過すると、現在のウィンドウを示すヘッダーとともに 429 rate_limited を返します：

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1718093460

レスポンスには Retry-After ヘッダー（秒）が含まれることもあります — 再試行前にこれに従ってください。

1 つの動画ジョブが数分かかることがあるため、リクエストレートだけでは不十分です。アカウントが同時に進行（queued または processing）できるジョブ数にも上限があり、通常は画像より動画の方が小さく設定されます。

上限を超えて送信すると 429 concurrency_limit_exceeded を返します。進行中のジョブがいくつか完了するのを待ってから再試行してください。カウントはアカウント単位で集計されるため、複数キーに分散しても回避できません。

v1 に Webhook はないため GET /v1/jobs/{id} をポーリングします。API に過負荷をかけないために：

• 推奨間隔：画像は約 2 秒、動画は 5～10 秒。
• Retry-After ヘッダーがあれば従ってください — 次回ポーリングのヒントです。
• ジョブが終了ステータス（succeeded / failed / canceled）に達したらポーリングを停止します。

ネットワークの不調で POST /v1/jobs が成功したか不明になることがあります。安全に再試行するには、一意の Idempotency-Key ヘッダーを送信します：

curl https://cloud-vanceai.vanceai.com/api/v1/jobs \
  -H "Authorization: Bearer sk_live_..." \
  -H "Idempotency-Key: 8f3b1c2a-...-unique" \
  -F [email protected] \
  -F tool=upscale

• 同じキーを再送すると元のジョブが返ります — 重複ジョブも二重課金もありません。
• 論理的なリクエストごとに新しいキーを生成します（UUID が適しています）。
• 異なる tool や config で同じキーを再利用すると 409 idempotency_conflict を返します。

{
  "error": {
    "code": "insufficient_credits",
    "message": "Your account does not have enough credits for this operation.",
    "type": "billing"
  }
}

code は安定した文字列です — これで分岐します。message は人間可読で変わる可能性があります。type は大分類で、auth・billing・validation・processing・rate_limit・server のいずれかです。

リクエストが即座に拒否されると、対応する HTTP ステータスと error ボディが返ります：

ジョブが*非同期に*失敗した場合、GET /v1/jobs/{id} のポーリングは status: "failed" と error.code のコードを伴って HTTP 200 を返します。失敗ジョブで 5xx を期待しないでください — クエリ自体は成功しています。

ダッシュボードで新しいキーを作成し、識別しやすい名前（例：my-app-prod）を付けます。sk_live_ で始まる完全なシークレットは、作成直後に一度だけ表示されます。

ダッシュボードはキーを名前、ステータス、識別用の短いプレフィックス（例：sk_live_a1b2）、最終使用日時で一覧表示します。完全なシークレットは二度と表示されず、プレフィックスのみです。

キーの無効化は即座に有効になります — そのキーでの以降のリクエストは 401 invalid_api_key を返します。

• 無効化は恒久的です。再有効化はできません。代わりに新しいキーを作成してください。
• 管理できるのは自分のアカウントに属するキーのみです。

複数のアクティブキーを併用できるため、ローテーションはシームレスです：新しいキーを作成し、アプリを切り替え、トラフィックが移行したことを確認してから古いキーを無効化します。アプリや環境ごとに別のキーを使うと、漏洩時の影響範囲を限定できます。

最初の安定版には以下が含まれます：

• 画像・動画共通の統一ジョブ API — POST /v1/jobs、GET /v1/jobs/{id}、GET /v1/jobs/{id}/result、POST /v1/jobs/{id}/cancel、DELETE /v1/jobs/{id}、GET /v1/credits。
• 8 つの画像ツールと3 つの動画ツール（アップスケール、HDR、顔補正）。
• 大きいファイル：画像の直接アップロードは最大 200 MB、動画は二段階直接アップロード、任意のメディアは source_url 経由（SSRF 対策付き）。
• 事前クレジットチェックとバックグラウンドワーカーによる非同期処理。
• 失敗・キャンセル時に全額返還されるクレジット予約。
• 安定したエラーコード、Idempotency-Key 対応、キーごとのレート制限とアカウントごとの同時実行制限。
• 動画の二段階直接アップロード — POST /v1/uploads が署名付き URL を発行し、動画をストレージへ直接アップロード（1 回の PUT で最大約 4.9 GB）してリクエストサイズ制限を回避します。
• 正確な動画課金 — サーバーが ffprobe で解像度・長さ・フレームレートを計測し、出力解像度をエンジン上限に対して事前チェックします。