Assets（アセット）

共通情報

• Base URL：https://api.routeapi.ai
• 認証：Authorization: Bearer $ROUTEAPI_KEY。sk- で始まる API Key を使用します（コンソールの API Keys ページで作成）。rat_ で始まる管理キーはモデルを呼び出せません。
• エラー形式：これらのエンドポイントで RouteAPI 自身が返すエラーは {"error": "..."} または {"error": "...", "code": "..."} です。共通の認証・レート制限ミドルウェアで拒否されたリクエストは、代わりに {"error": {"message": "...", "type": "error", "code": "..."}} を返すことがあります。上流のステータスコードと本文はそのまま透過されます。詳しくは後述の制限とエラーとよくあるエラーを参照してください。

アセット API は、Seedance 動画モデルが入力として利用できる参照素材（画像、動画、音声）を保存します。素材は一度追加し、上流のアセットサービスが処理を完了するのを待ってから、毎回同じ公開 URL を渡す代わりに、動画生成リクエスト内で asset://<asset_id> として参照できます。

これは管理用 API であり、生成用 API ではありません。RouteAPI はあなたの API Key で呼び出しを認証し、上流のアセットサービスへ転送して、上流のレスポンスを返します。これらのエンドポイントへの呼び出しはモデル使用量として課金されません。また OpenAI SDK の対象外であるため、SDK クライアントではなく素の HTTP を使用してください。

ボディはそのまま転送されます

RouteAPI はアセットのペイロードを再整形しません。以下に示すサイズ制限と特別な処理を 除き、リクエストボディとレスポンスボディはそのまま透過的に転送されるため、ここに示す フィールド集合が上流の契約です。レスポンスの正確なフィールド集合を固定のものと 見なさないでください。

ワークフロー

1. アセットグループを作成する — POST /v1/asset-groups。
2. アセットを追加する — そのグループに POST /v1/assets で、公開ダウンロード可能な URL を渡します。
3. アセットをポーリングする — GET /v1/assets/{assetID} でステータスが Active になるまで。処理は非同期です。
4. アセットを参照する — POST /v1/video/generations リクエストの metadata.content 内で asset://<asset_id> として参照します。詳しくはSeedance リクエストでアセットを使用するとSeedanceを参照してください。
5. 動画タスクを通常どおりポーリングする。アセットを使う動画リクエストは上流へ一度だけ送信され、再試行や別チャネルへのフェイルオーバーは行われません。

エンドポイント

メソッド	パス	用途	アセット空間を割り当てる
POST	/v1/asset-groups	アセットグループを作成する	はい
GET	/v1/asset-groups	グループを一覧する	いいえ
GET	/v1/asset-groups/{groupID}	単一のグループを取得する	いいえ
DELETE	/v1/asset-groups/{groupID}	グループを削除する	いいえ
PUT	/v1/asset-groups/{groupID}	グループの名前を変更する	いいえ
POST	/v1/assets	グループにアセットを追加する	はい
GET	/v1/assets	グループ内のアセットを一覧する	いいえ
GET	/v1/assets/{assetID}	単一のアセットを取得する（ポーリング用）	いいえ
DELETE	/v1/assets/{assetID}	アセットを削除する	いいえ
PUT	/v1/assets/{assetID}	アセットの名前を変更する	いいえ
POST	/v1/assets/verify-sessions	本人確認セッションを作成する	はい
GET	/v1/assets/verify-sessions/{sessionID}	本人確認セッションを取得する	いいえ

認証

標準のヘッダーでモデル API Key を送信します:

Authorization: Bearer sk-your-routeapi-key

Key は RouteAPI アカウントを識別します。アセットはアカウントごとに分離されます。同じアカウントのすべての API Key は同じグループ、アセット、本人確認セッションを参照でき、他のアカウントからは参照できません。Key が上流へ送信されることはありません。RouteAPI があなたの代わりに別の上流認証情報を使用します。

初回利用とアセットプールキー

各アカウントは 1 つの上流認証情報にバインドされ、アセットサービスはこれを使ってそのアカウントの素材を分離します。バインドは、アカウントが初めて作成系エンドポイントを呼び出したときに自動的に割り当てられます:

• POST /v1/asset-groups
• POST /v1/assets
• POST /v1/assets/verify-sessions

一度割り当てられると、そのバインディングはアカウントに対して永続的で、以降のすべての呼び出し（asset:// アセットを参照する動画リクエストを含む）で再利用されます。

読み取りと削除のエンドポイントは割り当てを行いません。バインディングが存在する前は:

呼び出し	レスポンス
GET /v1/asset-groups	200、空の一覧: {"total": 0, "asset_groups": []}
その他の GET または DELETE	404、{"error": "not found"}

つまり、空のグループ一覧は新しいアカウントにとって正常な結果であり、初回利用前に特定のアセットやグループで 404 が返るのは「このアカウントにはまだアセット空間がない」という意味で、「ID が間違っている」という意味ではありません。

グループから認証情報へのルーティングはサービス側の設定詳細です。所属グループにアセットチャネルが設定されていない場合、最初の作成系呼び出しは割り当てを行わずに 503 asset_pool_exhausted または 503 asset_pool_misconfigured で失敗します。後で再試行するか、解消しない場合はサポートに連絡してください。

故障したキーは使用されないままになる

上流があなたの認証情報を 401 で拒否した場合、RouteAPI はそのバインディングを 故障としてマークし、503 asset_key_unavailable を返します。管理者がバインディングを 復旧するまで、すべてのアセット呼び出し、およびアセットを参照するすべての動画 リクエストはこのコードを返し続けます。そのため、本番環境でこの経路に依存する前に、 事前にこの経路を検証してください。

アセットグループ

アセットグループを作成する

POST /v1/asset-groups

curl https://api.routeapi.ai/v1/asset-groups \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "product-refs",
    "description": "Reference material for product videos"
  }'

フィールド	型	必須	説明
name	string	はい	グループ名
description	string	いいえ	グループの説明

レスポンス:

{
  "asset_group_id": "local_group_2c8186e6d8b44ffa73b371677bfe4af2",
  "name": "product-refs",
  "project_name": "default",
  "status": "active"
}

asset_group_id は保存してください。アセットを追加するときに必要です。

アセットグループを一覧する

GET /v1/asset-groups

curl "https://api.routeapi.ai/v1/asset-groups?page=1&page_size=20" \
  -H "Authorization: Bearer $ROUTEAPI_KEY"

page や page_size などのページネーションパラメータはそのまま転送され、上流サービスのデフォルト値と 1 ページあたりの上限が適用されます。

{
  "total": 1,
  "asset_groups": [
    {
      "asset_group_id": "local_group_2c8186e6d8b44ffa73b371677bfe4af2",
      "group_type": "AIGC",
      "project_name": "default",
      "session_id": "",
      "status": "active",
      "created_at": 1792050332,
      "updated_at": 1792050332
    }
  ]
}

session_id は本人確認を通じて作成されたグループにのみ設定されます。本人確認済みのグループは group_type が LivenessFace で、通常のグループは AIGC です。

アセットグループを取得する

curl https://api.routeapi.ai/v1/asset-groups/local_group_2c8186e6d8b44ffa73b371677bfe4af2 \
  -H "Authorization: Bearer $ROUTEAPI_KEY"

上流の詳細レスポンスは status が空文字列で返る場合があります。グループが使用可能かどうかを判断する必要があるときは、一覧レスポンスまたは作成レスポンスの値を使用してください。

アセットグループを削除する

curl -X DELETE https://api.routeapi.ai/v1/asset-groups/local_group_2c8186e6d8b44ffa73b371677bfe4af2 \
  -H "Authorization: Bearer $ROUTEAPI_KEY"

{ "deleted": "local_group_2c8186e6d8b44ffa73b371677bfe4af2" }

削除は元に戻せません。

アセットグループの名前を変更する

curl -X PUT https://api.routeapi.ai/v1/asset-groups/local_group_2c8186e6d8b44ffa73b371677bfe4af2 \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "new_group_name"}'

{ "name": "new_group_name", "updated": "local_group_2c8186e6d8b44ffa73b371677bfe4af2" }

アセット

アセットを追加する

POST /v1/assets

1 リクエストにつき 1 アセットです。グループ、名前、そしてソース URL を 1 つだけ渡してください。

フィールド	型	必須	説明
asset_group_id	string	はい	アセットが属するグループ
asset_name	string	はい	検索にのみ使用される名前。生成には影響しません
image_url	string	3 つのうち 1 つ	画像の公開 URL
video_url	string	3 つのうち 1 つ	動画の公開 URL
audio_url	string	3 つのうち 1 つ	音声ファイルの公開 URL
asset_type	string	いいえ	Image、Video、Audio のいずれか。省略時は URL のフィールドから推定されます
description	string	いいえ	アセットの説明

image_url、video_url、audio_url のうち 1 つだけを渡してください。0 個または複数を渡すと上流サービスはリクエストを拒否します。URL は認証や追加のヘッダーなしで公開インターネットからダウンロード可能である必要があります。Base64 ペイロードや内部アドレスはサポートされておらず、URL は処理が完了するまで到達可能でなければなりません。

curl https://api.routeapi.ai/v1/assets \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "asset_group_id": "local_group_2c8186e6d8b44ffa73b371677bfe4af2",
    "asset_name": "product-front",
    "image_url": "https://cdn.example.com/product-front.jpg"
  }'

{
  "asset_id": "local_asset_25e4d0cb018fb5802bf4e466f99707d0",
  "asset_group_id": "local_group_2c8186e6d8b44ffa73b371677bfe4af2",
  "asset_name": "product-front",
  "asset_type": "Image",
  "asset_uri": "asset://local_asset_25e4d0cb018fb5802bf4e466f99707d0",
  "status": "Processing"
}

作成が成功したのはリクエストを受け付けたという意味であり、アセットが使用可能になったという意味ではありません。動画リクエストで使用するのは asset_uri の形式です。

アセットのステータス

ステータス	意味	次のステップ
Processing	取り込み中	ポーリングを続ける
Active	使用可能	動画リクエストで参照する
Failed	取り込み失敗	形式とサイズの要件を確認し、再度追加する

単一のアセットを取得する

このエンドポイントを 5〜10 秒間隔でポーリングし、全体のタイムアウトを設定してください。処理は通常数秒から数十秒かかります。動画アセットや混雑時はさらに長くかかります。

curl https://api.routeapi.ai/v1/assets/local_asset_25e4d0cb018fb5802bf4e466f99707d0 \
  -H "Authorization: Bearer $ROUTEAPI_KEY"

{
  "asset_id": "local_asset_25e4d0cb018fb5802bf4e466f99707d0",
  "asset_group_id": "local_group_2c8186e6d8b44ffa73b371677bfe4af2",
  "status": "Active",
  "asset_uri": "asset://local_asset_25e4d0cb018fb5802bf4e466f99707d0",
  "url": "https://..."
}

url は一時的な署名付きダウンロードアドレスです。保存せず、生成には asset_uri を使用してください。

アセットが存在しないか削除済みの場合、上流サービスは 404 を返します。例:

{ "details": "record not found", "error": "asset not found in database" }

アセットの一覧と削除

# List — asset_group_id is required
curl "https://api.routeapi.ai/v1/assets?asset_group_id=local_group_2c8186e6d8b44ffa73b371677bfe4af2" \
  -H "Authorization: Bearer $ROUTEAPI_KEY"

# Delete
curl -X DELETE https://api.routeapi.ai/v1/assets/local_asset_25e4d0cb018fb5802bf4e466f99707d0 \
  -H "Authorization: Bearer $ROUTEAPI_KEY"

{ "deleted": "local_asset_25e4d0cb018fb5802bf4e466f99707d0" }

アセットを削除すると、それを参照する新しい動画リクエストはすべて失敗します。

アセットの名前を変更する

curl -X PUT https://api.routeapi.ai/v1/assets/local_asset_25e4d0cb018fb5802bf4e466f99707d0 \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "new_asset_name"}'

{ "updated": "local_asset_25e4d0cb018fb5802bf4e466f99707d0" }

名前の変更後、アセットの詳細と一覧のレスポンスは新しい名前を返します。

本人確認セッション

実在の人物の顔を含む参照素材には、事前に本人の同意が必要です。本人確認セッションは、その人物の素材専用のグループを作成します。そこに追加されたアセットは顔の一貫性が検証されます。

セッションを作成する

POST /v1/assets/verify-sessions

ボディは空でも構いません（{} またはボディなし）。callback_url は受け付けられますが、リダイレクトには使用されません。

curl https://api.routeapi.ai/v1/assets/verify-sessions \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

{
  "session_id": "asset_sess_5e7860e76613dd51a4867bdcbea6076b",
  "status": "pending",
  "h5_link": "https://...one-time-link...",
  "callback_url": ""
}

h5_link は本人確認を受ける本人にのみ送信してください。ワンタイム認証情報を含み、本人確認ページへのアクセス権を与えます。公開ログ、スクリーンショット、グループチャットに載せないでください。

セッションを取得する

curl https://api.routeapi.ai/v1/assets/verify-sessions/asset_sess_5e7860e76613dd51a4867bdcbea6076b \
  -H "Authorization: Bearer $ROUTEAPI_KEY"

status	意味
pending	本人の操作待ち、または処理中
succeeded	本人確認成功。asset_group_id が設定されます
failed	本人確認失敗。error を確認してください

{
  "session_id": "asset_sess_a8af6fab34f694ada40c22521448f579",
  "status": "succeeded",
  "result_code": "",
  "error": "",
  "asset_group_id": "group-20261015202316-4t5jt",
  "project_name": "default",
  "created_at": 1792066965,
  "updated_at": 1792067203
}

あなたのサービスへ戻る webhook やリダイレクトはありません。本人のブラウザは上流が提供する結果ページで終了します。status が succeeded になるまで（通常は数分以内）セッションをポーリングし、その後、その人物の素材を返された asset_group_id に追加してください。result_code は現状常に空です。status を使用してください。error が verification expired のような failed セッションは作り直す必要があります。

Seedance リクエストでアセットを使用する

動画生成リクエストの metadata.content 内で、アセット API が返す asset_uri を使ってアセットを参照します:

curl https://api.routeapi.ai/v1/video/generations \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-0-fast-260128",
    "prompt": "The product in image 1 rotates slowly",
    "metadata": {
      "content": [
        { "type": "text", "text": "The product in image 1 rotates slowly" },
        {
          "type": "image_url",
          "image_url": { "url": "asset://local_asset_25e4d0cb018fb5802bf4e466f99707d0" },
          "role": "reference_image"
        }
      ],
      "duration": 4,
      "resolution": "480p",
      "ratio": "1:1"
    }
  }'

GET /v1/models から動画生成をサポートする Seedance モデル ID を使用してください。詳しくはモデルを参照してください。metadata.content の role とモデル固有の制限を含む Seedance のリクエスト形式は、Seedanceに記載されています。

アセットサービスの契約に由来するルール:

• type/role の組み合わせはアセットの種類と一致する必要があります。image_url は reference_image、video_url は reference_video、audio_url は reference_audio と組み合わせます。
• 参照できるのは Active のアセットのみです。
• プロンプトでは素材を序数（「image 1」「video 1」）で参照し、序数は content の順序で各種類ごとに数えます。プロンプトにアセット ID を書かないでください。
• 実在の人物の素材は本人確認済みのグループに由来する必要があります。そうでない場合、上流がリクエストを拒否したりタスクを失敗させたりする可能性があります。

RouteAPI は asset:// で始まる JSON 文字列値（大文字小文字を区別しない）を探すことで参照を検出します。そのようなリクエストはあなたのアセットチャネルに固定され、一度だけ送信され、再試行やチャネルフェイルオーバーは行われません。次の場合はリクエストがローカルで拒否されます:

ステータス	コード	原因
400	asset_key_required	ボディが asset:// を参照しているが、アカウントにはまだアセット空間がない。先にグループとアセットを作成してください
400	asset_remix_conflict	アセットではないタスクの remix が asset:// アセットを参照しようとしている
400	asset_channel_conflict	API Key があなたのアセットチャネルではない特定のチャネルに固定されている
400	asset_model_unsupported	モデルがあなたのアセットチャネルでサポートされていない
503	asset_key_unavailable	アカウントにバインドされた上流認証情報が故障または無効になっている

これらのエラーはタスクエラーの形式 {"code": ..., "message": ..., "data": ...} を使用します。

制限とエラー

• リクエストボディ — POST と PUT のボディは 1 MiB の上限で読み取られます。それを超えると、上流へ何も送信される前に 413 が返されます。素材自体はボディ経由でアップロードされることはありません。URL を渡してください。
• ボディの形式 — 空でない POST または PUT のボディは JSON オブジェクトである必要があります。配列、裸の文字列、null、不正な JSON は上流サービスに到達せず 400 を返します。GET と DELETE のボディは無視されます。
• 名前変更のボディ — PUT ボディには空でない文字列フィールド name（キーは小文字）が必要です。name がない、空、または文字列でない場合は、上流サービスに到達せず 400 を返します。
• レスポンスボディ — 上流のレスポンスが 10 MiB を超える場合、または読み取りに失敗した場合は 502 を返します。
• タイムアウト — 上流呼び出しには固定の 60 秒タイムアウトがあり、期限切れは 502 として報告されます。
• project_name — POST または PUT のボディに存在する場合、このフィールドは転送前に削除されます（大文字小文字を問わず）。
• 所有権エラー — 上流が所有権の拒否（“you do not own” / “access denied”）で 403 を返した場合、RouteAPI は代わりに 404 {"error": "not found"} を返すため、リソースは禁止されているのではなく存在しないように見えます。
• 上流認証情報の故障 — 上流の 401 は 503 asset_key_unavailable になり、アカウントのバインディングを故障としてマークします（上記参照）。上流の 402、またはボディが課金問題のように読める上流エラーは 503 asset_service_unavailable になります。

その他の上流ステータスコードとボディは、上流のバリデーションエラーを含め、そのまま透過的に返されます。RouteAPI 自身のエラーは次の 3 つの形式のいずれかを使用します:

{ "error": "not found" }

{ "error": "<message>", "code": "asset_pool_busy" }

{
  "error": {
    "message": "token.invalid (request id: ...)",
    "type": "error",
    "code": ""
  }
}

3 つ目の形式は共通の認証とレート制限のミドルウェアに由来するため、error が文字列かオブジェクトかを確認してください。ローカルの message 文言は現状中国語です。最初の 2 つの形式では、メッセージではなく HTTP ステータスと code フィールドで分岐してください。

ステータス	コード	意味	対処
400	—	ボディが JSON オブジェクトでない、または上流がパラメータを拒否した	リクエストを修正する。そのまま再試行しない
401	—	API Key が欠落、無効、または削除済み	Authorization を確認する
404	—	不明なアセット、グループ、セッション。またはこのアカウントにはまだアセット空間がない	ID を確認する。新しいアカウントなら先にグループを作成する
413	—	リクエストボディが 1 MiB を超えている	インラインデータではなく URL を送信する
429	—	レート制限に達した	ポーリングの間隔を空けて後で再試行する
500	asset_pool_internal_error	RouteAPI が自身のアセット状態を読み書きできなかった	後で再試行する
500	—	RouteAPI がアカウントのアセット状態を読み取る際に失敗した	後で再試行する
502	—	上流に到達できない、タイムアウトした、または読み取れない/過大なレスポンスを返した	後で再試行する
503	asset_key_unavailable	アカウントの上流認証情報が故障または無効になっている	サポートに連絡する。再試行しても解決しない
503	asset_pool_exhausted	所属グループにアセットチャネルがない、または割り当て可能な認証情報がない	後で再試行するか、サポートに連絡する
503	asset_pool_busy	認証情報は存在するが、現在どれも割り当てられない	後で再試行する
503	asset_pool_misconfigured	所属グループが複数のアセットチャネルにマッピングされている	サポートに連絡する
503	asset_channel_unavailable	アセットチャネル自体が無効または設定ミスがある	後で再試行するか、サポートに連絡する
503	asset_service_unavailable	上流アカウントの残高不足、またはハード障害	後で再試行するか、サポートに連絡する

アセット呼び出しにモデル費用はかかりませんが、プラットフォームのモデルリクエストレート制限が有効な場合、他の /v1 リクエストと同様に制限にカウントされます。一般的なエラーモデルについてはエラーとデバッグを、これらのアセットを消費する動画生成がどのように課金されるかについてはモデル価格を参照してください。

次のステップ

• 動画生成タスクの作成 — すべての動画モデルが共有するリクエスト形式。
• Seedance — Seedance のリクエスト形式と metadata.content の role。
• モデル — サポートされている動画モデル ID を探す。
• エラーとデバッグ — ステータスコードと調査の順序。