# RunningHub Sora2 使用指南 **版本：** v2.1.0 **更新时间：** 2025-10-20 --- ## 📋 模型列表 系统已预配置以下RunningHub Sora2模型（共12个）： ### 文生视频模型（webappId: 1973555977595301890） | 模型名称 | 说明 | 时长 | 分辨率 | 积分消耗 | |---------|------|------|--------|---------| | `rh_sora2_text_portrait` | 竖屏视频 | 10秒 | 704x1280 | 160 | | `rh_sora2_text_landscape` | 横屏视频 | 10秒 | 1280x704 | 160 | | `rh_sora2_text_portrait_hd` | 高清竖屏 | 10秒 | 1024x1792 | 420 | | `rh_sora2_text_landscape_hd` | 高清横屏 | 10秒 | 1792x1024 | 420 | | `rh_sora2_text_portrait_15s` | 竖屏视频（长） | 15秒 | 704x1280 | 260 | | `rh_sora2_text_landscape_15s` | 横屏视频（长） | 15秒 | 1280x704 | 260 | ### 图生视频模型（webappId: 1973555366057390081） | 模型名称 | 说明 | 时长 | 分辨率 | 积分消耗 | |---------|------|------|--------|---------| | `rh_sora2_img_portrait` | 竖屏视频 | 10秒 | 704x1280 | 180 | | `rh_sora2_img_landscape` | 横屏视频 | 10秒 | 1280x704 | 180 | | `rh_sora2_img_portrait_hd` | 高清竖屏 | 10秒 | 1024x1792 | 480 | | `rh_sora2_img_landscape_hd` | 高清横屏 | 10秒 | 1792x1024 | 480 | | `rh_sora2_img_portrait_15s` | 竖屏视频（长） | 15秒 | 704x1280 | 280 | | `rh_sora2_img_landscape_15s` | 横屏视频（长） | 15秒 | 1280x704 | 280 | --- ## 🚀 使用示例 ### 1. 文生视频（Text to Video） 只需要提供 `prompt`，系统会自动选择横竖屏和时长。 ```bash curl -X POST "http://localhost:8081/user/ai/tasks/submit" \ -H "Authorization: Bearer YOUR_JWT_OR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "modelName": "rh_sora2_text_portrait", "prompt": "第一镜（0–3秒）静谧晨光\n窗外的城市尚在沉睡，镜头推向一只放在床头的 Apple Watch。屏幕亮起的瞬间，柔和的光映照出主人的脸庞，他睁开眼，呼吸与心率同步闪烁。\n第二镜（3–7秒）节奏苏醒\n主角在晨跑，步伐稳健。手表屏幕显示心率曲线与路线图，汗水顺着手臂滑落。阳光从高楼间洒下，镜头追随腕间的微光与动作的力量。\n第三镜（7–10秒）自我回归\n跑步结束，他停在桥上深吸一口气，城市的天际线在他背后延伸。镜头慢慢拉远，Apple Watch的屏幕定格在闪烁的数字上，文字浮现：掌控每一秒的呼吸。" }' ``` **实际发送到RunningHub的请求：** ```json { "webappId": "1973555977595301890", "apiKey": "5c44cef12da3470e9f24da70c63787dc", "nodeInfoList": [ { "nodeId": "1", "fieldName": "prompt", "fieldValue": "第一镜（0–3秒）静谧晨光...", "description": "输入文本" }, { "nodeId": "1", "fieldName": "model", "fieldValue": "portrait", "fieldData": "[{\"name\":\"portrait\",...}]", "description": "横竖模式" }, { "nodeId": "1", "fieldName": "duration_seconds", "fieldValue": "10", "fieldData": "[[10, 15], {\"default\": 10}]", "description": "时长（秒）" } ] } ``` --- ### 2. 图生视频（Image to Video） 需要提供 `imageUrl` 或 `imageBase64`，以及可选的 `prompt`。 #### 方式1：使用图片URL（推荐） ```bash curl -X POST "http://localhost:8081/user/ai/tasks/submit" \ -H "Authorization: Bearer YOUR_JWT_OR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "modelName": "rh_sora2_img_landscape", "prompt": "镜头一（0s–3s）从空中俯拍，镜头缓缓向下俯冲穿越云层，紫蓝色霓虹反射在摩天大楼玻璃幕墙上...", "imageUrl": "https://example.com/my-reference-image.jpg" }' ``` #### 方式2：使用图片Base64 ```bash curl -X POST "http://localhost:8081/user/ai/tasks/submit" \ -H "Authorization: Bearer YOUR_JWT_OR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "modelName": "rh_sora2_img_portrait_hd", "prompt": "让这个场景动起来，添加生动的细节", "imageBase64": "data:image/jpeg;base64,/9j/4AAQSkZJRg..." }' ``` **实际发送到RunningHub的请求：** ```json { "webappId": "1973555366057390081", "apiKey": "5c44cef12da3470e9f24da70c63787dc", "nodeInfoList": [ { "nodeId": "2", "fieldName": "image", "fieldValue": "https://example.com/my-reference-image.jpg", "description": "上传图像（不支持真人做图像的输入）" }, { "nodeId": "1", "fieldName": "prompt", "fieldValue": "镜头一（0s–3s）从空中俯拍...", "description": "输入文本" }, { "nodeId": "1", "fieldName": "model", "fieldValue": "landscape", "fieldData": "[{\"name\":\"portrait\",...}]", "description": "横竖模式" }, { "nodeId": "1", "fieldName": "duration_seconds", "fieldValue": "10", "fieldData": "[[10, 15], {\"default\": 10}]", "description": "时长（秒）" } ] } ``` --- ## 🔧 关键实现细节 ### 1. 自动任务类型识别 系统根据 `providerConfig.taskType` 自动识别任务类型： ```java // points_config表中的配置示例 { "webappId": "1973555366057390081", "taskType": "image2video", // 或 "text2video" "model": "landscape", "duration": 10 } ``` ### 2. 图片参数处理 - **优先级**：`imageUrl` > `imageBase64` - **支持格式**： - 完整URL：`https://example.com/image.jpg` - RunningHub文件名：`825b8cb2f5603b068704ef435df77d570f081be814a40f652f080b8d4bc6ba03.png` - Base64编码：`data:image/jpeg;base64,/9j/4AAQSkZJRg...` ```java // RunningHubProviderImpl中的逻辑 if (isImage2Video) { String imageValue = request.getImageUrl(); if (imageValue == null || imageValue.trim().isEmpty()) { imageValue = request.getImageBase64(); } // 添加到nodeInfoList nodeInfoList.add(RunningHubNodeInfo.builder() .nodeId("2") .fieldName("image") .fieldValue(imageValue) // 支持完整URL .description("上传图像（不支持真人做图像的输入）") .build()); } ``` ### 3. 节点顺序 系统按照RunningHub要求的顺序构建节点： **文生视频：** 1. prompt节点（nodeId="1"） 2. model节点（nodeId="1"） 3. duration_seconds节点（nodeId="1"） **图生视频：** 1. image节点（nodeId="2"） 2. prompt节点（nodeId="1"，可选） 3. model节点（nodeId="1"） 4. duration_seconds节点（nodeId="1"） --- ## 📊 任务流程 ### 文生视频流程 ``` 用户提交 ↓ 提取prompt ↓ 读取points_config配置 taskType="text2video" webappId="1973555977595301890" ↓ 构建nodeInfoList: - prompt节点 - model节点 - duration节点 ↓ 调用RunningHub API ↓ 获得taskId status='processing' ↓ 5秒轮询一次 ↓ 检测到SUCCESS ↓ 获取视频URL status='completed' ``` ### 图生视频流程 ``` 用户提交 ↓ 提取prompt + imageUrl ↓ 读取points_config配置 taskType="image2video" webappId="1973555366057390081" ↓ 构建nodeInfoList: - image节点（完整URL） - prompt节点 - model节点 - duration节点 ↓ 调用RunningHub API ↓ 获得taskId status='processing' ↓ 5秒轮询一次 ↓ 检测到SUCCESS ↓ 获取视频URL status='completed' ``` --- ## ⚠️ 注意事项 ### 1. 图片要求 - **图生视频模型不支持真人图像作为输入** - 建议使用风景、物体、场景类图片 - 支持完整的HTTP/HTTPS URL，无需预先上传到RunningHub ### 2. Prompt建议 - **文生视频**：详细描述镜头、场景、动作、时间节点 - **图生视频**：描述如何让图片"动起来"，添加什么动态效果 ### 3. 处理时间 - 文生视频：约2-5分钟 - 图生视频：约2-5分钟（取决于服务器负载） ### 4. 积分消耗 - 任务提交时立即扣除积分（冻结） - 任务成功：确认消耗积分 - 任务失败：自动退还积分 --- ## 🧪 测试步骤 ### 测试1：文生视频（竖屏10秒） ```bash # 1. 提交任务 TASK_RESPONSE=$(curl -X POST "http://localhost:8081/user/ai/tasks/submit" \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "modelName": "rh_sora2_text_portrait", "prompt": "一个人在海边奔跑，镜头从远到近" }') echo $TASK_RESPONSE # 2. 提取taskNo TASK_NO=$(echo $TASK_RESPONSE | jq -r '.data.taskNo') # 3. 等待2-5分钟后查询 curl "http://localhost:8081/user/ai/tasks/$TASK_NO" \ -H "Authorization: Bearer YOUR_TOKEN" ``` ### 测试2：图生视频（横屏高清） ```bash # 1. 提交任务 curl -X POST "http://localhost:8081/user/ai/tasks/submit" \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "modelName": "rh_sora2_img_landscape_hd", "prompt": "镜头缓缓向下俯冲穿越云层，紫蓝色霓虹反射在摩天大楼玻璃幕墙上", "imageUrl": "https://example.com/city-skyline.jpg" }' # 2. 查看日志确认图片URL正确传递 tail -f logs/application.log | grep "RunningHub Provider" ``` --- ## 📝 数据库配置 所有模型配置已通过 `V5__add_provider_support.sql` 自动创建： ```sql -- 查看所有RunningHub模型 SELECT model_name, description, points_cost, provider_config FROM points_config WHERE provider_type = 'runninghub' ORDER BY points_cost; -- 查看某个模型的配置 SELECT provider_config FROM points_config WHERE model_name = 'rh_sora2_img_landscape'; -- 结果示例： { "webappId": "1973555366057390081", "taskType": "image2video", "model": "landscape", "duration": 10 } ``` --- ## 🔍 故障排查 ### 问题1：图生视频任务失败 **错误信息：** "图生视频任务必须提供imageUrl或imageBase64" **解决方案：** - 确认请求中包含 `imageUrl` 或 `imageBase64` 字段 - 检查图片URL是否可访问 - 确认使用的是图生视频模型（包含 `_img_` 的模型名） ### 问题2：任务一直处于processing状态 **可能原因：** - RunningHub服务器负载高 - 网络连接问题 - 任务确实在处理中 **解决方案：** ```bash # 1. 查看轮询日志 tail -f logs/application.log | grep "RunningHub轮询" # 2. 检查数据库中的provider_task_id SELECT task_no, provider_task_id, status, update_time FROM ai_task WHERE task_no = 'YOUR_TASK_NO'; # 3. 手动查询RunningHub状态（仅用于调试） curl -X POST "https://www.runninghub.cn/task/openapi/status" \ -H "Content-Type: application/json" \ -d '{ "apiKey": "YOUR_API_KEY", "taskId": "PROVIDER_TASK_ID" }' ``` --- ## 📊 性能监控 ```sql -- 查看RunningHub任务统计 SELECT status, COUNT(*) as count, AVG(TIMESTAMPDIFF(SECOND, start_time, complete_time)) as avg_seconds FROM ai_task WHERE provider_type = 'runninghub' AND create_time > DATE_SUB(NOW(), INTERVAL 1 DAY) GROUP BY status; -- 查看最近的失败任务 SELECT task_no, model_name, error_message, create_time FROM ai_task WHERE provider_type = 'runninghub' AND status = 'failed' ORDER BY create_time DESC LIMIT 10; ``` --- **RunningHub Sora2集成完成！** 🎉 系统现已支持文生视频和图生视频两种模式，共12个预配置模型可供使用！