开发者吐槽New API视频接口设计混乱，求优化方案
速览
有开发者在尝试接入Happy Horse时，发现New API的视频生成接口设计存在明显缺陷。主要问题包括Duration与Seconds语义重复，以及Image、Images和InputReference三套参考图输入方式并存且无法良好支持多类型参考图。由于该接口改动影响较大，开发者发帖征求社区意见及更好的实现方案。
AI 深度解读
背景
随着生成式 AI 应用的深入，视频生成领域正成为开发者关注的焦点。在当前的开源生态中，New API 作为一个提供 AI 能力的接口平台，试图接入 Happy Horse（一种视频生成或处理相关的开源项目/模型）以增强其视频处理能力。然而，这一集成过程并非一帆风顺。
开发者在尝试将 Happy Horse 接入 New API 的过程中发现，开源社区对此项目的关注度极低，GitHub 上仅有一个相关的 Pull Request（PR）且已被拒绝。面对社区支持的缺失，开发者不得不自行深入研究底层接口设计。在此过程中，开发者对 New API 现有的视频接口设计提出了尖锐的批评，认为其存在严重的语义冗余和结构混乱，难以满足复杂场景下的需求，因此发起讨论以寻求更优的设计方案或实现思路。
核心内容
开发者通过代码审查的方式，指出了 New API 视频任务提交接口（TaskSubmitReq）中存在的几个主要设计缺陷。该接口定义如下：
type TaskSubmitReq struct {
Prompt string `json:"prompt"`
Model string `json:"model,omitempty"`
Mode string `json:"mode,omitempty"`
Image string `json:"image,omitempty"`
Images []string `json:"images,omitempty"`
Size string `json:"size,omitempty"`
Duration int `json:"duration,omitempty"`
Seconds string `json:"seconds,omitempty"`
InputReference string `json:"input_reference,omitempty"`
Metadata map[string]interface{} `json:"metadata,omitempty"`
}
具体问题分析如下：
-
语义重复的参数设计： 接口中同时存在
Duration（类型为int）和Seconds（类型为string）。这两个字段在语义上均指向视频的时长，但类型不同且并存，造成了极大的混淆和不必要的冗余。开发者认为这种设计缺乏严谨性，增加了前端调用和后端解析的复杂度。 -
参考图输入逻辑混乱： 接口中同时定义了
Image（单张图片字符串）、Images（图片字符串数组）以及InputReference（输入引用字符串）。这三套机制并存，导致开发者无法清晰判断在何种场景下应使用哪个字段。特别是在视频生成任务中，往往需要多张不同类型的参考图（如姿态参考、风格参考等），当前的扁平化结构无法很好地支持这种多模态、多类型的引用需求。 -
扩展性不足： 面对复杂的视频输入类任务，当前的接口设计显得捉襟见肘。虽然开发者考虑过直接修改源码，但考虑到接口设计的整体一致性和向后兼容性，全面重构被认为是不合适的。因此，开发者希望探讨是否有更优雅的实现方式或替代方案，以解决当前接口在灵活性上的不足。
关键要点
- 社区支持薄弱：
Happy Horse项目在开源社区（GitHub）缺乏关注，唯一的 PR 被拒，迫使开发者自行解决集成问题。 - 接口设计存在严重冗余：
Duration和Seconds功能重叠，类型定义不一致，体现了设计上的随意性。 - 参考图机制缺乏统一标准：
Image、Images和InputReference三套输入方式并存，导致 API 使用歧义，无法有效支持复杂的多参考图场景。 - 难以满足复杂场景需求：现有设计无法灵活支持视频生成中常见的多类型、多张参考图输入需求。
- 重构风险与寻求共识：直接修改接口可能破坏兼容性，开发者倾向于通过社区讨论寻找更合理的架构建议或实现路径。
意义与影响
这一讨论揭示了当前部分 AI 基础设施在接口设计上的成熟度问题。New API 作为连接开发者与底层模型（如 Happy Horse）的桥梁，其接口的易用性和规范性直接影响开发者的体验和应用的上限。
- 对开发者的警示：在集成第三方 AI 服务时，开发者需警惕底层 API 设计的缺陷，这些缺陷可能导致后期维护成本高昂，甚至限制功能的扩展。
- 对 API 设计规范的反思：该案例凸显了 API 设计中“单一职责原则”和“语义一致性”的重要性。参数冗余和逻辑混乱不仅增加出错概率，也降低了代码的可读性和可维护性。
- 推动开源协作与标准建立：通过公开讨论此类设计缺陷，有助于社区形成更通用的视频生成 API 设计共识，推动类似
Happy Horse等开源项目与主流 API 平台的更好融合，最终促进整个 AI 应用生态的健康发展。