xiaoxia-saas/tests/render_compare/README_assets.md

测试素材创建工具

create_test_asset.py 是一个自动化测试辅助工具，用于快速创建 ready 状态的视频素材，跳过正常的上传和转码流程，直接指定已存在于 OSS 的文件来生成可用素材。

适用场景

• 渲染对比测试：快速创建测试素材用于生成任务
• 性能测试：批量创建素材模拟真实场景
• 开发调试：无需真实上传文件即可测试素材相关功能

前置条件

1. API 服务正在运行
2. 有有效的登录 token
3. 指定的 storage_key 对应的文件已存在于 OSS 中
4. 用户对指定项目有访问权限

使用方法

基本用法

# 设置环境变量（可选）
export API_BASE_URL=http://localhost:8000
export API_TOKEN=your_token_here

# 创建测试素材
python tests/render_compare/create_test_asset.py \
    --project-id proj_xxx \
    --name "测试素材-30s" \
    --storage-key "assets/test/sample_30s.mp4" \
    --duration 30 \
    --file-size 10485760

完整参数示例

python tests/render_compare/create_test_asset.py \
    --base-url http://localhost:8000 \
    --token eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... \
    --project-id proj_a1b2c3d4e5f6 \
    --name "1080p测试视频-60s" \
    --storage-key "test-assets/1080p_60fps_60s.mp4" \
    --duration 60 \
    --width 1920 \
    --height 1080 \
    --fps 60 \
    --mime-type "video/mp4" \
    --file-size 52428800 \
    --codec "h264" \
    --kind video

在脚本中捕获 asset_id

# 最后一行输出为 asset_id，方便脚本捕获
ASSET_ID=$(python tests/render_compare/create_test_asset.py \
    --project-id proj_xxx \
    --name "测试素材" \
    --storage-key "test/video.mp4" \
    2>&1 | tail -1)

echo "创建的素材 ID: $ASSET_ID"

参数说明

参数	环境变量	必填	默认值	说明
--base-url	API_BASE_URL	否	http://localhost:8000	API 服务地址
--token	API_TOKEN	是	-	登录认证 token
--project-id	-	是	-	项目 ID
--name	-	是	-	素材名称
--storage-key	-	是	-	OSS storage_key（文件需已存在）
--duration	-	否	30	视频时长（秒）
--width	-	否	1280	视频宽度
--height	-	否	720	视频高度
--fps	-	否	25	帧率
--mime-type	-	否	video/mp4	MIME 类型
--file-size	-	否	0	文件大小（字节）
--codec	-	否	-	视频编码
--kind	-	否	video	素材库类型 (video/voice/image)

API 调用流程

脚本会依次调用以下 API：

1. 确保默认素材库存在

POST /api/v1/asset-libraries/ensure-default
Content-Type: application/json
Authorization: Bearer {token}

{
  "project_id": "proj_xxx",
  "kind": "video"
}

• 如果项目下已有对应类型的素材库，直接返回第一个
• 如果不存在，自动创建默认名称的素材库

2. 创建素材

POST /api/v1/assets
Content-Type: application/json
Authorization: Bearer {token}

{
  "project_id": "proj_xxx",
  "library_id": "lib_xxx",
  "name": "测试素材",
  "storage_key": "assets/test/video.mp4",
  "mime_type": "video/mp4",
  "file_size": 10485760,
  "duration": 30,
  "width": 1280,
  "height": 720,
  "fps": 25,
  "status": "ready",
  "classification_status": "pending",
  "metadata": {}
}

关键点：

• status: "ready" 直接跳过转码流程，立即可用
• storage_key 必须对应 OSS 中真实存在的文件，否则播放会失败
• uploaded_by_user_id 由 API 自动设置为当前登录用户

输出说明

脚本输出分为三部分：

1. 参数回显：确认输入的参数是否正确
2. 执行日志：显示每一步的执行情况
3. 结果输出：
   • 素材详细信息（asset_id、状态、文件 URL 等）
   • 调用示例
   • 最后一行为纯 asset_id，方便脚本捕获

错误排查

常见错误

401 Unauthorized

• 检查 token 是否正确且未过期
• 确认 Authorization header 格式为 Bearer {token}

403 Forbidden

• 确认用户对该项目有访问权限
• 检查项目 ID 是否正确

404 Project not found

• 项目 ID 错误或项目不存在

422 Validation Error

• 检查参数格式是否正确
• 查看响应中的 detail 字段了解具体错误

调试技巧

脚本在 API 失败时会打印完整的响应内容，包括：

• HTTP 状态码
• 错误原因
• 响应 body 详情

如果遇到问题，请检查：

1. API 服务是否正常运行
2. base-url 是否正确（注意端口号）
3. token 是否有效
4. storage_key 对应的文件是否存在于 OSS

与渲染对比测试配合使用

# 1. 创建测试素材
ASSET_ID=$(python tests/render_compare/create_test_asset.py \
    --project-id proj_xxx \
    --name "渲染对比测试素材" \
    --storage-key "test-assets/base_1080p_30s.mp4" \
    --duration 30 --width 1920 --height 1080 \
    2>&1 | tail -1)

# 2. 使用该素材运行渲染对比测试
python tests/render_compare/runner.py \
    --project-id proj_xxx \
    --asset-id $ASSET_ID \
    --scenario quality_test

注意事项

1. storage_key 必须真实存在：脚本不会上传文件，只是创建数据库记录。如果 OSS 中没有对应文件，素材虽然状态是 ready，但无法正常播放。
2. 素材参数要准确：duration、width、height、fps 等参数应与实际文件一致，否则可能导致后续渲染或分析出现偏差。
3. 权限检查：确保 token 对应用户有项目的素材创建权限。
4. 清理测试数据：测试完成后记得清理不需要的测试素材，避免占用资源。