方舟素材托管

方舟素材托管端点在请求/响应形态上对齐火山方舟（Ark）OpenAPI，素材库本身由 宁享Token 托管，便于在调用方舟模型时直接复用已托管素材。

说明

• 托管语义：本端点使用火山方舟素材库 OpenAPI 的请求/响应形态，但素材库由本平台托管——请求参数按方舟原生 JSON 解析并落本平台库，响应由平台构造（非上游透传）。当前仅开放 CreateAssetGroup / CreateAsset 两个 Action。
• 鉴权：使用 宁享Token 的 API Key（Bearer Token）鉴权，由平台自动转换为方舟侧凭据，调用方无需自行管理方舟密钥。
• 按 client_key 隔离：代理在 宁享Token 侧按 API Key 隔离，不会跨 key 泄漏素材。

Base URL

/  （部署域名，例如 https://your-domain.com）

方舟素材托管

POST/api/ark/assets?Action={Action}

火山方舟素材库代理端点。Action 经 query 传入，请求体为方舟素材库原生 JSON，响应原样透传。

Bearer Token

请求头

Content-Type: application/json

请求参数（Query）

Query 参数

参数	类型	必填	默认值	描述
Action	string	是	-	方舟素材库操作名（火山原生 Action）。目标态：透传全量，如 CreateAsset / CreateAssetGroup / GetAsset / ListAssets / DeleteAsset 等；实测态（2026-09-30）：线上仅开放 CreateAssetGroup / CreateAsset，其余 Action 一律返回 400 InvalidAction

对齐火山方舟：Action 经 query string 传入（与火山 /?Action=X&Version=2024-01-01 同构），不是放在请求体里。请求体直接写方舟素材库的原生 JSON（原样透传）。

⚠️ 目标态 ≠ 实测态（2026-09-30 实测）

本页描述的是目标态（透传全量 Action）；线上实测态只有 CreateAssetGroup / CreateAsset 两个 Action 开放， 其余 Action 报 400 InvalidAction——/api/ark/assets 与 /v1/ark/asset 今天都由托管实现接管。

• 线上查素材请走 /api/assets/list，不要指望 /api/ark/assets?Action=ListAssets 能通。
• 报障前先自测线上行为，不要只读本文档或源码：文档、源码、线上三者可能不一致（源码可能已重构但尚未发布）。

请求体（方舟素材库原生 JSON）

直接传方舟对应 Action 的请求体，如 CreateAssetGroup：

{
  "Name": "我的素材组",
  "Description": "描述",
  "GroupType": "AIGC",
  "ProjectName": "default"
}

请求示例

curl -X POST "/api/ark/assets?Action=CreateAssetGroup" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "Name": "我的素材组",
    "Description": "描述",
    "GroupType": "AIGC",
    "ProjectName": "default"
  }'

import requests

resp = requests.post(
    "/api/ark/assets",
    params={"Action": "CreateAssetGroup"},
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "Name": "我的素材组",
        "Description": "描述",
        "GroupType": "AIGC",
        "ProjectName": "default",
    },
)
print(resp.json())

响应示例

成功响应

{
  "ResponseMetadata": {
    "RequestId": "nx-1735689600123",
    "Action": "CreateAssetGroup",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  },
  "Result": { "Id": "mg-20260930120000-abcde" }
}

Action=CreateAsset 时 Result 额外双返回两种引用形态：

{
  "ResponseMetadata": { "RequestId": "nx-1735689600123", "Action": "CreateAsset", "Version": "2024-01-01", "Service": "ark", "Region": "cn-beijing" },
  "Result": {
    "Id": "ma-20260930120000-abcde",
    "AssetId": "asset-20260930120000-abcde",
    "AssetUri": "asset://asset-20260930120000-abcde"
  }
}

视频生成请求的 content._url.url 请使用 AssetUri（即 asset://asset-…）。

错误响应

错误码是字符串码（火山 OpenAPI 形态），不是数字码；错误对象在 ResponseMetadata.Error 里：

{
  "ResponseMetadata": {
    "RequestId": "nx-1735689600123",
    "Action": "CreateAsset",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing",
    "Error": { "Code": "GroupNotFound", "Message": "素材组不存在：nxt-grp-xxx" }
  }
}

HTTP 状态	Error.Code	触发条件
400	InvalidAction	Action 不在本端点的开放面内（今天仅 CreateAssetGroup / CreateAsset）
400	MissingParameter	请求体非法，或必填字段缺失（建组缺 Name；建素材缺 URL / GroupId）
400	InvalidParameter	GroupType 非 AIGC（真人素材组须先完成活体认证，由系统自动创建）
403	AccessDenied	素材组不属于当前 API Key（ClientKey 不匹配，或组无主）
404	GroupNotFound	GroupId / GroupID 指向的素材组不存在
500	InternalError	落库失败（素材组或素材），可重试或联系管理员
502	UpstreamCreateGroupFailed	上游方舟侧创建素材组失败，Message 含上游原文
502	UpstreamCreateAssetFailed	上游方舟侧上传素材失败，Message 含上游原文
503	NoVideoModelAvailable	当前 Key 所在分组/用户无可用视频模型，无法托管素材组
503	NoAssetChannel	无可用素材渠道，或归属渠道未开放该素材操作（Message 含缺哪一项能力）

判定顺序是契约：先判 Action 合法性（400 InvalidAction），再判渠道能力（503 NoAssetChannel）—— 参数错误不会被降级成"服务不可用"，客户端不要对 400 做重试。

相关文档

• 素材库概览
• 素材管理
• 素材组管理