{"doc":{"category_id":null,"content":"# 火山方舟素材库 API 接入与使用指南\n\n本网关深度兼容火山引擎火山方舟平台（Volcengine Ark）的素材库及素材资产管理能力。开发者可以直接通过网关代理的 `/api` 端点，调用火山原生的素材与素材组管理 API，实现素材资产的上传、查询、更新和删除。\n\n### 官方文档参考\n完整参数、限制与最新能力说明请参阅火山方舟官方文档：\n* [素材库官方文档](https://console.volcengine.com/ark/region:cn-beijing/docs/82379/2333565?lang=zh)\n\n---\n\n## 1. 基础请求信息\n\n为保障接入的高效与安全，所有素材 API 统一采用 `POST` 方式提交，并通过标准的 JSON 格式与网关通信。\n\n* **基准请求地址 (Base URL)**: `https://{{domain}}/api`\n* **请求方式 (HTTP Method)**: `POST`\n* **必填请求头部 (HTTP Headers)**:\n  * `Content-Type: application/json`\n  * `Authorization: Bearer sk-your_api_key_value_here` *(您的平台统一 API 密钥，请在后台令牌管理中生成)*\n\n---\n\n## 2. 公共请求参数 (Query String)\n\n进行素材操作时，必须在请求 URL 的 **Query 参数** 中透传以下控制参数：\n\n| 参数名 | 必填 | 类型 | 说明 |\n| :--- | :--- | :--- | :--- |\n| `Action` | 是 | `string` | 执行的具体资产操作，可选值见下方“核心 API 接口列表” |\n| `Version` | 否 | `string` | 接口版本号，默认为 `2024-01-01` |\n| `ns` | 否 | `string` | 插件命名空间，可选 `asset_manager`（国内版素材管理凭证，默认）或 `asset_manager_intl`（国际版素材管理凭证） |\n\n*完整请求 URL 格式示例*：\n`POST https://{{domain}}/api?Action=CreateAsset&Version=2024-01-01&ns=asset_manager`\n\n---\n\n## 3. 核心 API 接口列表\n\n### ① 注册/创建素材资产 (CreateAsset)\n用于将已存储在云存储（如火山 TOS）上的媒体文件 URL，向火山方舟注册为可用于视频生成等大模型的资产。\n* **URL Action**: `CreateAsset`\n* **请求体参数 (Request Body - JSON)**:\n```json\n{\n  \"AssetType\": \"video\", // 素材类型，必须为 \"image\" (图片) 或 \"video\" (视频)\n  \"URL\": \"https://your-tos-bucket.tos-cn-beijing.volces.com/path/video.mp4\", // 媒体文件的公网可公开直链 URL\n  \"Name\": \"我的背景视频素材\", // 素材展示名称 (限制在 100 字符内)\n  \"Description\": \"用于生成奇幻风格视频的参考底图素材\" // 可选，素材描述\n}\n```\n* **响应结果 (Response - JSON)**:\n```json\n{\n  \"ResponseMetadata\": {\n    \"RequestId\": \"20260714101500...\",\n    \"Action\": \"CreateAsset\",\n    \"Version\": \"2024-01-01\",\n    \"Service\": \"ark\",\n    \"Region\": \"cn-beijing\"\n  },\n  \"Result\": {\n    \"Id\": \"asset-20260714...\", // 火山方舟生成的全局唯一素材资产 ID\n    \"Status\": \"active\" // 状态: active (可用), processing (处理中), failed (失败)\n  }\n}\n```\n* **平台特有安全与数据库审计机制**:\n  1. **项目隔离隔离**: 网关在转发时，会自动注入或覆盖 `ProjectName` 为系统配置的项目，确保企业资源统一管辖。\n  2. **本地回填记录**: 素材创建成功后，网关会**自动在本地数据库建立归属关系**，使该素材归属于您的令牌账户。您可以在系统后台的「我的素材库」直接看到并管理它。\n\n---\n\n### ② 查询素材资产 (GetAsset)\n获取单个素材的详细处理状态与详细元数据。\n* **URL Action**: `GetAsset`\n* **请求体参数 (Request Body - JSON)**:\n```json\n{\n  \"Id\": \"asset-20260714...\" // 待查询的素材资产 ID\n}\n```\n* **特殊说明**: 网关实施了严格的数据隔离。非管理员（`admin`）角色仅能查询和调取自己创建的素材资产，否则将返回 `403 Forbidden` 错误。\n\n---\n\n### ③ 删除素材资产 (DeleteAsset)\n从火山方舟云端删除特定的素材资产，并同步清理网关本地的归属记录。\n* **URL Action**: `DeleteAsset`\n* **请求体参数 (Request Body - JSON)**:\n```json\n{\n  \"Id\": \"asset-20260714...\" // 待删除的素材资产 ID\n}\n```\n* **响应结果 (Response - JSON)**:\n```json\n{\n  \"ResponseMetadata\": {\n    \"RequestId\": \"20260714102000...\",\n    \"Action\": \"DeleteAsset\",\n    \"Version\": \"2024-01-01\",\n    \"Service\": \"ark\",\n    \"Region\": \"cn-beijing\"\n  },\n  \"Result\": {}\n}\n```\n* **特殊说明**: 同样受到用户级所有权验证保护。删除操作会同步彻底地移除网关数据库中的记录并调用火山引擎端执行释放。\n\n---\n\n### ④ 创建素材资产组 (CreateAssetGroup)\n火山视频生成模型（例如豆包 Seedance）进行“主体/角色/风格参考”多图生成时，需指定素材组 ID。您可以使用此接口将同类型的多个素材打组管理。\n* **URL Action**: `CreateAssetGroup`\n* **请求体参数 (Request Body - JSON)**:\n```json\n{\n  \"Name\": \"我的角色参考组\", // 素材组名称\n  \"Description\": \"用于存放特定人像生成的主体参考图片\" // 可选，描述\n}\n```\n* **响应结果 (Response - JSON)**:\n```json\n{\n  \"ResponseMetadata\": {\n    \"RequestId\": \"20260714103000...\",\n    \"Action\": \"CreateAssetGroup\",\n    \"Version\": \"2024-01-01\",\n    \"Service\": \"ark\",\n    \"Region\": \"cn-beijing\"\n  },\n  \"Result\": {\n    \"Id\": \"group-20260714...\" // 火山方舟生成的全局唯一素材资产组 ID\n  }\n}\n```\n* **说明**: 创建成功的素材组也会在网关本地进行用户归属校验，保证您只能操作自己创建的资产组。\n\n---\n\n### ⑤ 其他受支持的白名单接口\n网关透传并支持火山方舟素材库以下完整的操作：\n* `UpdateAsset` (更新素材名称/描述)\n* `ListAssets` (列出素材列表)\n* `GetAssetGroup` / `UpdateAssetGroup` / `DeleteAssetGroup` / `ListAssetGroups` (素材资产组的查询、修改、删除和列表获取)\n","created_at":"2026-07-20T03:33:18.915Z","id":27,"is_active":0,"is_dir":0,"is_preset":0,"parent_id":10,"slug":"volcengine-assets-guide","sort_order":30,"title":"关于火山素材库接口的接入和使用","translations":{"en":{"content":"# Volcengine Ark Material Library API Integration Guide\n\nThis gateway is deeply compatible with the material library and asset management capabilities of Volcengine Ark. Developers can directly invoke Volcengine's native material and asset group management APIs via the gateway's `/api` proxy endpoint, and also manage their uploaded assets securely with user-level isolation.\n\n### Official Documentation\nFor complete parameters, limits, and the latest capabilities, please refer to the Volcengine Ark official docs:\n* [Material Library Official Docs](https://console.volcengine.com/ark/region:cn-beijing/docs/82379/2333565?lang=zh)\n\n---\n\n## 1. Basic Request Information\n\nFor high efficiency and security, all material APIs are submitted via `POST` requests, communicating with the gateway using JSON format.\n\n* **Base URL**: `https://{{domain}}/api`\n* **HTTP Method**: `POST`\n* **Required HTTP Headers**:\n  * `Content-Type: application/json`\n  * `Authorization: Bearer sk-your_api_key_value_here` *(Your API key generated in the dashboard)*\n\n---\n\n## 2. Common Query Parameters\n\nWhen calling any Volcengine Ark asset API, specify the `Action` and `Version` in the query parameters of the URL:\n\n| Parameter | Required | Type | Description |\n| :--- | :--- | :--- | :--- |\n| `Action` | Yes | `string` | The asset action to perform (e.g., `CreateAsset`). See the core API list below. |\n| `Version` | No | `string` | The API version, defaults to `2024-01-01`. |\n| `ns` | No | `string` | Plugin namespace, options: `asset_manager` (domestic version, default) or `asset_manager_intl` (international version). |\n\n*Example Request URL*:\n`POST https://{{domain}}/api?Action=CreateAsset&Version=2024-01-01&ns=asset_manager`\n\n---\n\n## 3. Core API Endpoints\n\n### ① Register/Create Asset (CreateAsset)\nRegisters a media file URL stored in an object storage (e.g., TOS) as a Volcengine Ark asset.\n* **URL Action**: `CreateAsset`\n* **JSON Request Body**:\n```json\n{\n  \"AssetType\": \"video\", // Asset type: \"image\" or \"video\"\n  \"URL\": \"https://your-tos-bucket.tos-cn-beijing.volces.com/path/video.mp4\", // Publicly accessible URL of the file\n  \"Name\": \"test_video_asset\", // Asset name (up to 100 characters)\n  \"Description\": \"This is a background video asset\" // Optional, asset description\n}\n```\n* **JSON Response**:\n```json\n{\n  \"ResponseMetadata\": {\n    \"RequestId\": \"20260714101500...\",\n    \"Action\": \"CreateAsset\",\n    \"Version\": \"2024-01-01\",\n    \"Service\": \"ark\",\n    \"Region\": \"cn-beijing\"\n  },\n  \"Result\": {\n    \"Id\": \"asset-20260714...\", // Global unique asset ID generated by Volcengine\n    \"Status\": \"active\" // Status: active, processing, failed\n  }\n}\n```\n* **Gateway Enhancement & Security**:\n  1. **Project Override**: The gateway automatically overrides `ProjectName` with the system-configured project name to ensure unified asset management.\n  2. **Local Ownership Binding**: Upon successful creation, the gateway automatically binds the asset to your account in the local database. You can view and manage it on the \"My Assets\" page.\n\n---\n\n### ② Get Asset Info (GetAsset)\nRetrieves the detailed status and metadata of a single asset.\n* **URL Action**: `GetAsset`\n* **JSON Request Body**:\n```json\n{\n  \"Id\": \"asset-20260714...\" // The asset ID\n}\n```\n* **Notes**: The gateway enforces strict data isolation. Non-admin users can only query assets they created, otherwise a `403 Forbidden` error is returned.\n\n---\n\n### ③ Delete Asset (DeleteAsset)\nDeletes the asset from Volcengine Ark and removes the local database ownership record.\n* **URL Action**: `DeleteAsset`\n* **JSON Request Body**:\n```json\n{\n  \"Id\": \"asset-20260714...\" // The asset ID to delete\n}\n```\n* **JSON Response**:\n```json\n{\n  \"ResponseMetadata\": {\n    \"RequestId\": \"20260714102000...\",\n    \"Action\": \"DeleteAsset\",\n    \"Version\": \"2024-01-01\",\n    \"Service\": \"ark\",\n    \"Region\": \"cn-beijing\"\n  },\n  \"Result\": {}\n}\n```\n* **Notes**: Non-admins can only delete their own assets. The gateway verifies ownership, calls Volcengine Ark API to delete the cloud asset, and then clears the local record.\n\n---\n\n### ④ Create Asset Group (CreateAssetGroup)\nVolcengine video generation models (e.g. Seedance) support multi-image reference and subject reference. You can group assets of the same type together.\n* **URL Action**: `CreateAssetGroup`\n* **JSON Request Body**:\n```json\n{\n  \"Name\": \"My Reference Group\", // Group name\n  \"Description\": \"Reference portraits for video generation\" // Optional description\n}\n```\n* **JSON Response**:\n```json\n{\n  \"ResponseMetadata\": {\n    \"RequestId\": \"20260714103000...\",\n    \"Action\": \"CreateAssetGroup\",\n    \"Version\": \"2024-01-01\",\n    \"Service\": \"ark\",\n    \"Region\": \"cn-beijing\"\n  },\n  \"Result\": {\n    \"Id\": \"group-20260714...\" // Global unique asset group ID generated by Volcengine\n  }\n}\n```\n* **Notes**: Created asset groups are also isolated and bound to the creator's account.\n\n---\n\n### ⑤ Other Supported Actions\nThe gateway transparently proxies and supports the following Volcengine Ark asset actions:\n* `UpdateAsset` (Updates name/description of an asset)\n* `ListAssets` (Lists assets)\n* `GetAssetGroup` / `UpdateAssetGroup` / `DeleteAssetGroup` / `ListAssetGroups` (CRUD and listing of asset groups)\n","title":"Volcengine Material Library API Integration Guide"},"ja":{"content":"# Volcengine Ark 素材ライブラリ API 連携ガイド\n\nこのゲートウェイは、Volcengine Ark の素材ライブラリおよびアセット管理機能と深く互換性があります。開発者は、ゲートウェイの `/api` プロキシエンドポイントを介して、Volcengine のネイティブ素材およびアセットグループ管理 API を直接呼び出し、アセットのアップロード、照会、更新、削除を行うことができます。\n\n### 公式ドキュメント\nパラメータ仕様と最新機能については、Volcengine Ark 公式ドキュメントを参照してください：\n* [素材ライブラリ公式ドキュメント](https://console.volcengine.com/ark/region:cn-beijing/docs/82379/2333565?lang=zh)\n\n---\n\n## 1. 基本リクエスト情報 (Basic Request Information)\n\n効率性とセキュリティを確保するため、すべてのアセット API は `POST` リクエストを介して送信され、JSON 形式を使用してゲートウェイと通信します。\n\n* **Base URL**: `https://{{domain}}/api`\n* **HTTP Method**: `POST`\n* **必須 HTTP ヘッダー**:\n  * `Content-Type: application/json`\n  * `Authorization: Bearer sk-your_api_key_value_here` *(ダッシュボードで生成された API キー)*\n\n---\n\n## 2. 共通クエリパラメータ (Common Query Parameters)\n\nアセット API を呼び出すときは、URL のクエリパラメータで `Action` と `Version` を指定します：\n\n| パラメータ | 必須 | 型 | 説明 |\n| :--- | :--- | :--- | :--- |\n| `Action` | はい | `string` | 実行するアクション（例：`CreateAsset`）。以下のコア API リストを参照してください。 |\n| `Version` | いいえ | `string` | API バージョン。デフォルトは `2024-01-01`。 |\n| `ns` | いいえ | `string` | プラグインの名前空間。オプション：`asset_manager`（国内版、デフォルト）または `asset_manager_intl`（国際版）。 |\n\n*リクエスト URL の例*:\n`POST https://{{domain}}/api?Action=CreateAsset&Version=2024-01-01&ns=asset_manager`\n\n---\n\n## 3. コア API エンドポイント (Core API Endpoints)\n\n### ① アセットの登録/作成 (CreateAsset)\nオブジェクトストレージ (TOS など) に保存されているメディアファイルの URL を Volcengine Ark アセットとして登録します。\n* **URL Action**: `CreateAsset`\n* **JSON リクエストボディ**:\n```json\n{\n  \"AssetType\": \"video\", // アセットタイプ: \"image\" または \"video\"\n  \"URL\": \"https://your-tos-bucket.tos-cn-beijing.volces.com/path/video.mp4\", // 公開アクセス可能なファイルの URL\n  \"Name\": \"test_video_asset\", // アセット名（最大 100 文字）\n  \"Description\": \"This is a background video asset\" // オプション、アセットの説明\n}\n```\n* **JSON レスポンス**:\n```json\n{\n  \"ResponseMetadata\": {\n    \"RequestId\": \"20260714101500...\",\n    \"Action\": \"CreateAsset\",\n    \"Version\": \"2024-01-01\",\n    \"Service\": \"ark\",\n    \"Region\": \"cn-beijing\"\n  },\n  \"Result\": {\n    \"Id\": \"asset-20260714...\", // Volcengine によって生成された一意のアセット ID\n    \"Status\": \"active\" // ステータス: active, processing, failed\n  }\n}\n```\n* **ゲートウェイの強化とセキュリティ**:\n  1. **プロジェクトの上書き**: ゲートウェイは、アセット管理の統合を確保するため、`ProjectName` をシステム構成のプロジェクト名に自動的に上書きします。\n  2. **ローカル所有権のバインド**: 作成に成功すると、ゲートウェイはローカルデータベースでアセットをアカウントに自動的にバインドします。ダッシュボードの「マイアセット」ページで確認および管理できます。\n\n---\n\n### ② アセット情報の取得 (GetAsset)\n単一のアセットの詳細なステータスとメタデータを取得します。\n* **URL Action**: `GetAsset`\n* **JSON リクエストボディ**:\n```json\n{\n  \"Id\": \"asset-20260714...\" // アセット ID\n}\n```\n* **注意**: ゲートウェイは厳格なデータ分離を強制します。管理者以外のユーザーは自分が作成したアセットのみをクエリできます。それ以外の場合は `403 Forbidden` エラーが返されます。\n\n---\n\n### ③ アセットの削除 (DeleteAsset)\nVolcengine Ark からアセットを削除し、ローカルデータベースの所有権レコードを削除します。\n* **URL Action**: `DeleteAsset`\n* **JSON リクエストボディ**:\n```json\n{\n  \"Id\": \"asset-20260714...\" // 削除するアセットの ID\n}\n```\n* **JSON レスポンス**:\n```json\n{\n  \"ResponseMetadata\": {\n    \"RequestId\": \"20260714102000...\",\n    \"Action\": \"DeleteAsset\",\n    \"Version\": \"2024-01-01\",\n    \"Service\": \"ark\",\n    \"Region\": \"cn-beijing\"\n  },\n  \"Result\": {}\n}\n```\n* **注意**: 管理者以外のユーザーは、自分が所有するアセットのみを削除できます。ゲートウェイは所有権を確認し、Volcengine Ark API を呼び出してクラウド上のアセットを削除し、ローカルレコードをクリアします。\n\n---\n\n### ④ アセットグループの作成 (CreateAssetGroup)\nVolcengine の動画生成モデル (Seedance など) は、マルチ画像参照および主体参照をサポートしています。同じタイプのアセットをグループ化して管理できます。\n* **URL Action**: `CreateAssetGroup`\n* **JSON リクエストボディ**:\n```json\n{\n  \"Name\": \"My Reference Group\", // グループ名\n  \"Description\": \"Reference portraits for video generation\" // オプションの説明\n}\n```\n* **JSON レスポンス**:\n```json\n{\n  \"ResponseMetadata\": {\n    \"RequestId\": \"20260714103000...\",\n    \"Action\": \"CreateAssetGroup\",\n    \"Version\": \"2024-01-01\",\n    \"Service\": \"ark\",\n    \"Region\": \"cn-beijing\"\n  },\n  \"Result\": {\n    \"Id\": \"group-20260714...\" // Volcengine によって生成された一意のアセットグループ ID\n  }\n}\n```\n* **注意**: 作成されたアセットグループも隔離され、作成者のアカウントにバインドされます。\n\n---\n\n### ⑤ その他のサポートされているアクション\nゲートウェイは、以下の Volcengine Ark アセットアクションを透過的にプロキシし、サポートします：\n* `UpdateAsset` (アセットの名前/説明の更新)\n* `ListAssets` (アセットの一覧表示)\n* `GetAssetGroup` / `UpdateAssetGroup` / `DeleteAssetGroup` / `ListAssetGroups` (アセットグループの CRUD およびリスト表示)\n","title":"Volcengine Ark 素材ライブラリ API 連携ガイド"},"ko":{"content":"# Volcengine Ark Material Library API Integration Guide\n\nThis gateway is deeply compatible with the material library and asset management capabilities of Volcengine Ark. Developers can directly invoke Volcengine's native material and asset group management APIs via the gateway's `/api` proxy endpoint, and also manage their uploaded assets securely with user-level isolation.\n\n### Official Documentation\nFor complete parameters, limits, and the latest capabilities, please refer to the Volcengine Ark official docs:\n* [Material Library Official Docs](https://console.volcengine.com/ark/region:cn-beijing/docs/82379/2333565?lang=zh)\n\n---\n\n## 1. Basic Request Information\n\nFor high efficiency and security, all material APIs are submitted via `POST` requests, communicating with the gateway using JSON format.\n\n* **Base URL**: `https://{{domain}}/api`\n* **HTTP Method**: `POST`\n* **Required HTTP Headers**:\n  * `Content-Type: application/json`\n  * `Authorization: Bearer sk-your_api_key_value_here` *(Your API key generated in the dashboard)*\n\n---\n\n## 2. Common Query Parameters\n\nWhen calling any Volcengine Ark asset API, specify the `Action` and `Version` in the query parameters of the URL:\n\n| Parameter | Required | Type | Description |\n| :--- | :--- | :--- | :--- |\n| `Action` | Yes | `string` | The asset action to perform (e.g., `CreateAsset`). See the core API list below. |\n| `Version` | No | `string` | The API version, defaults to `2024-01-01`. |\n| `ns` | No | `string` | Plugin namespace, options: `asset_manager` (domestic version, default) or `asset_manager_intl` (international version). |\n\n*Example Request URL*:\n`POST https://{{domain}}/api?Action=CreateAsset&Version=2024-01-01&ns=asset_manager`\n\n---\n\n## 3. Core API Endpoints\n\n### ① Register/Create Asset (CreateAsset)\nRegisters a media file URL stored in an object storage (e.g., TOS) as a Volcengine Ark asset.\n* **URL Action**: `CreateAsset`\n* **JSON Request Body**:\n```json\n{\n  \"AssetType\": \"video\", // Asset type: \"image\" or \"video\"\n  \"URL\": \"https://your-tos-bucket.tos-cn-beijing.volces.com/path/video.mp4\", // Publicly accessible URL of the file\n  \"Name\": \"test_video_asset\", // Asset name (up to 100 characters)\n  \"Description\": \"This is a background video asset\" // Optional, asset description\n}\n```\n* **JSON Response**:\n```json\n{\n  \"ResponseMetadata\": {\n    \"RequestId\": \"20260714101500...\",\n    \"Action\": \"CreateAsset\",\n    \"Version\": \"2024-01-01\",\n    \"Service\": \"ark\",\n    \"Region\": \"cn-beijing\"\n  },\n  \"Result\": {\n    \"Id\": \"asset-20260714...\", // Global unique asset ID generated by Volcengine\n    \"Status\": \"active\" // Status: active, processing, failed\n  }\n}\n```\n* **Gateway Enhancement & Security**:\n  1. **Project Override**: The gateway automatically overrides `ProjectName` with the system-configured project name to ensure unified asset management.\n  2. **Local Ownership Binding**: Upon successful creation, the gateway automatically binds the asset to your account in the local database. You can view and manage it on the \"My Assets\" page.\n\n---\n\n### ② Get Asset Info (GetAsset)\nRetrieves the detailed status and metadata of a single asset.\n* **URL Action**: `GetAsset`\n* **JSON Request Body**:\n```json\n{\n  \"Id\": \"asset-20260714...\" // The asset ID\n}\n```\n* **Notes**: The gateway enforces strict data isolation. Non-admin users can only query assets they created, otherwise a `403 Forbidden` error is returned.\n\n---\n\n### ③ Delete Asset (DeleteAsset)\nDeletes the asset from Volcengine Ark and removes the local database ownership record.\n* **URL Action**: `DeleteAsset`\n* **JSON Request Body**:\n```json\n{\n  \"Id\": \"asset-20260714...\" // The asset ID to delete\n}\n```\n* **JSON Response**:\n```json\n{\n  \"ResponseMetadata\": {\n    \"RequestId\": \"20260714102000...\",\n    \"Action\": \"DeleteAsset\",\n    \"Version\": \"2024-01-01\",\n    \"Service\": \"ark\",\n    \"Region\": \"cn-beijing\"\n  },\n  \"Result\": {}\n}\n```\n* **Notes**: Non-admins can only delete their own assets. The gateway verifies ownership, calls Volcengine Ark API to delete the cloud asset, and then clears the local record.\n\n---\n\n### ④ Create Asset Group (CreateAssetGroup)\nVolcengine video generation models (e.g. Seedance) support multi-image reference and subject reference. You can group assets of the same type together.\n* **URL Action**: `CreateAssetGroup`\n* **JSON Request Body**:\n```json\n{\n  \"Name\": \"My Reference Group\", // Group name\n  \"Description\": \"Reference portraits for video generation\" // Optional description\n}\n```\n* **JSON Response**:\n```json\n{\n  \"ResponseMetadata\": {\n    \"RequestId\": \"20260714103000...\",\n    \"Action\": \"CreateAssetGroup\",\n    \"Version\": \"2024-01-01\",\n    \"Service\": \"ark\",\n    \"Region\": \"cn-beijing\"\n  },\n  \"Result\": {\n    \"Id\": \"group-20260714...\" // Global unique asset group ID generated by Volcengine\n  }\n}\n```\n* **Notes**: Created asset groups are also isolated and bound to the creator's account.\n\n---\n\n### ⑤ Other Supported Actions\nThe gateway transparently proxies and supports the following Volcengine Ark asset actions:\n* `UpdateAsset` (Updates name/description of an asset)\n* `ListAssets` (Lists assets)\n* `GetAssetGroup` / `UpdateAssetGroup` / `DeleteAssetGroup` / `ListAssetGroups` (CRUD and listing of asset groups)\n","title":"Volcengine Ark Material Library API Integration Guide"},"vi":{"content":"# Volcengine Ark Material Library API Integration Guide\n\nThis gateway is deeply compatible with the material library and asset management capabilities of Volcengine Ark. Developers can directly invoke Volcengine's native material and asset group management APIs via the gateway's `/api` proxy endpoint, and also manage their uploaded assets securely with user-level isolation.\n\n### Official Documentation\nFor complete parameters, limits, and the latest capabilities, please refer to the Volcengine Ark official docs:\n* [Material Library Official Docs](https://console.volcengine.com/ark/region:cn-beijing/docs/82379/2333565?lang=zh)\n\n---\n\n## 1. Basic Request Information\n\nFor high efficiency and security, all material APIs are submitted via `POST` requests, communicating with the gateway using JSON format.\n\n* **Base URL**: `https://{{domain}}/api`\n* **HTTP Method**: `POST`\n* **Required HTTP Headers**:\n  * `Content-Type: application/json`\n  * `Authorization: Bearer sk-your_api_key_value_here` *(Your API key generated in the dashboard)*\n\n---\n\n## 2. Common Query Parameters\n\nWhen calling any Volcengine Ark asset API, specify the `Action` and `Version` in the query parameters of the URL:\n\n| Parameter | Required | Type | Description |\n| :--- | :--- | :--- | :--- |\n| `Action` | Yes | `string` | The asset action to perform (e.g., `CreateAsset`). See the core API list below. |\n| `Version` | No | `string` | The API version, defaults to `2024-01-01`. |\n| `ns` | No | `string` | Plugin namespace, options: `asset_manager` (domestic version, default) or `asset_manager_intl` (international version). |\n\n*Example Request URL*:\n`POST https://{{domain}}/api?Action=CreateAsset&Version=2024-01-01&ns=asset_manager`\n\n---\n\n## 3. Core API Endpoints\n\n### ① Register/Create Asset (CreateAsset)\nRegisters a media file URL stored in an object storage (e.g., TOS) as a Volcengine Ark asset.\n* **URL Action**: `CreateAsset`\n* **JSON Request Body**:\n```json\n{\n  \"AssetType\": \"video\", // Asset type: \"image\" or \"video\"\n  \"URL\": \"https://your-tos-bucket.tos-cn-beijing.volces.com/path/video.mp4\", // Publicly accessible URL of the file\n  \"Name\": \"test_video_asset\", // Asset name (up to 100 characters)\n  \"Description\": \"This is a background video asset\" // Optional, asset description\n}\n```\n* **JSON Response**:\n```json\n{\n  \"ResponseMetadata\": {\n    \"RequestId\": \"20260714101500...\",\n    \"Action\": \"CreateAsset\",\n    \"Version\": \"2024-01-01\",\n    \"Service\": \"ark\",\n    \"Region\": \"cn-beijing\"\n  },\n  \"Result\": {\n    \"Id\": \"asset-20260714...\", // Global unique asset ID generated by Volcengine\n    \"Status\": \"active\" // Status: active, processing, failed\n  }\n}\n```\n* **Gateway Enhancement & Security**:\n  1. **Project Override**: The gateway automatically overrides `ProjectName` with the system-configured project name to ensure unified asset management.\n  2. **Local Ownership Binding**: Upon successful creation, the gateway automatically binds the asset to your account in the local database. You can view and manage it on the \"My Assets\" page.\n\n---\n\n### ② Get Asset Info (GetAsset)\nRetrieves the detailed status and metadata of a single asset.\n* **URL Action**: `GetAsset`\n* **JSON Request Body**:\n```json\n{\n  \"Id\": \"asset-20260714...\" // The asset ID\n}\n```\n* **Notes**: The gateway enforces strict data isolation. Non-admin users can only query assets they created, otherwise a `403 Forbidden` error is returned.\n\n---\n\n### ③ Delete Asset (DeleteAsset)\nDeletes the asset from Volcengine Ark and removes the local database ownership record.\n* **URL Action**: `DeleteAsset`\n* **JSON Request Body**:\n```json\n{\n  \"Id\": \"asset-20260714...\" // The asset ID to delete\n}\n```\n* **JSON Response**:\n```json\n{\n  \"ResponseMetadata\": {\n    \"RequestId\": \"20260714102000...\",\n    \"Action\": \"DeleteAsset\",\n    \"Version\": \"2024-01-01\",\n    \"Service\": \"ark\",\n    \"Region\": \"cn-beijing\"\n  },\n  \"Result\": {}\n}\n```\n* **Notes**: Non-admins can only delete their own assets. The gateway verifies ownership, calls Volcengine Ark API to delete the cloud asset, and then clears the local record.\n\n---\n\n### ④ Create Asset Group (CreateAssetGroup)\nVolcengine video generation models (e.g. Seedance) support multi-image reference and subject reference. You can group assets of the same type together.\n* **URL Action**: `CreateAssetGroup`\n* **JSON Request Body**:\n```json\n{\n  \"Name\": \"My Reference Group\", // Group name\n  \"Description\": \"Reference portraits for video generation\" // Optional description\n}\n```\n* **JSON Response**:\n```json\n{\n  \"ResponseMetadata\": {\n    \"RequestId\": \"20260714103000...\",\n    \"Action\": \"CreateAssetGroup\",\n    \"Version\": \"2024-01-01\",\n    \"Service\": \"ark\",\n    \"Region\": \"cn-beijing\"\n  },\n  \"Result\": {\n    \"Id\": \"group-20260714...\" // Global unique asset group ID generated by Volcengine\n  }\n}\n```\n* **Notes**: Created asset groups are also isolated and bound to the creator's account.\n\n---\n\n### ⑤ Other Supported Actions\nThe gateway transparently proxies and supports the following Volcengine Ark asset actions:\n* `UpdateAsset` (Updates name/description of an asset)\n* `ListAssets` (Lists assets)\n* `GetAssetGroup` / `UpdateAssetGroup` / `DeleteAssetGroup` / `ListAssetGroups` (CRUD and listing of asset groups)\n","title":"Volcengine Ark Material Library API Integration Guide"}},"updated_at":"2026-10-20T04:06:41.688Z"}}