查询素材

查询素材的处理状态和详细信息。

重要：素材会不定期删除，请勿将素材接口作为长期存储服务。请保留原始文件，并在素材失效后重新上传。

接口信息

接口：GET https://api-ai.xku.com/ark/v1/assets/{asset_id}

请求参数

参数	说明	必填
asset_id	素材 ID	是

使用示例

curl https://api-ai.xku.com/ark/v1/assets/{asset_id} \
  -H "Authorization: Bearer YOUR_API_KEY"

响应参数

字段	类型	说明
Id	string	素材 ID
Name	string	素材名称
URL	string	审核完成后的素材地址
AssetType	string	素材类型：Image、Video、Audio
ProjectName	string	资源所属项目名称
Status	string	素材处理状态
Moderation	object	审核信息
Moderation.Strategy	string	审核策略
Error	object	失败信息
Error.Code	string	错误代码
Error.Message	string	错误信息
CreateTime	string	创建时间，UTC 时间
UpdateTime	string	更新时间，UTC 时间

素材状态说明

状态	含义	是否终态
Pending	处理中	否，需继续轮询
Active	处理成功，可正常使用	是
Failed	处理失败	是
Deleted	已删除	是

响应示例

处理成功

{
    "Id": "asset-20250101000000-0000",
    "Name": "测试图片",
    "URL": "https://api-ai.xku.com/assets/xxx.jpg",
    "AssetType": "Image",
    "ProjectName": "default",
    "Status": "Active",
    "Moderation": {
        "Strategy": "Default"
    },
    "Error": {
        "Code": "",
        "Message": ""
    },
    "CreateTime": "2025-01-01T00:00:00Z",
    "UpdateTime": "2025-01-01T00:00:05Z"
}

处理中

{
    "Id": "asset-20250101000000-0000",
    "Name": "测试图片",
    "URL": "",
    "AssetType": "Image",
    "ProjectName": "default",
    "Status": "Pending",
    "Moderation": {
        "Strategy": "Default"
    },
    "Error": {
        "Code": "",
        "Message": ""
    },
    "CreateTime": "2025-01-01T00:00:00Z",
    "UpdateTime": "2025-01-01T00:00:01Z"
}

处理失败

{
    "Id": "asset-20250101000000-0000",
    "Name": "测试图片",
    "URL": "",
    "AssetType": "Image",
    "ProjectName": "default",
    "Status": "Failed",
    "Moderation": {
        "Strategy": "Default"
    },
    "Error": {
        "Code": "InvalidURL",
        "Message": "无法访问素材 URL"
    },
    "CreateTime": "2025-01-01T00:00:00Z",
    "UpdateTime": "2025-01-01T00:00:05Z"
}

轮询示例

建议使用以下逻辑轮询素材状态：

import time
import requests

def wait_for_asset(asset_id, api_key, max_wait=300):
    """等待素材处理完成"""
    start_time = time.time()
    
    while time.time() - start_time < max_wait:
        response = requests.get(
            f"https://api-ai.xku.com/ark/v1/assets/{asset_id}",
            headers={"Authorization": f"Bearer {api_key}"}
        )
        asset = response.json()
        status = asset.get("Status")
        
        if status == "Active":
            return asset
        elif status in ("Failed", "Deleted"):
            raise Exception(f"素材处理失败: {asset.get('Error', {}).get('Message')}")
        
        time.sleep(2)  # 等待 2 秒后继续查询
    
    raise Exception("等待超时")

注意事项

1. 素材会不定期删除，请勿将素材接口作为长期存储服务
2. 素材审核通常在几秒到几十秒内完成
3. 如果素材 URL 无法访问，审核会失败
4. 建议使用 2-5 秒的轮询间隔
5. 素材状态变为 Active 后即可在视频生成任务中使用