常见问题

API Key 可以放在前端吗？

不建议。API Key 应保存在服务端、环境变量或密钥管理工具中。前端页面、移动端包、公开仓库、截图和日志都不应出现真实 API Key。

Base URL 应该用哪个？

可以按访问场景选择：

域名	推荐场景
https://moonapix.com	主调用域名，推荐优先使用。
https://moonapi.yuezhuoxing.com	国内长请求备用线路。
https://api.yuezhuoxing.com	国内加速备用线路。

接口路径和鉴权方式保持一致。OpenAI-compatible 客户端的 Base URL 通常需要在所选域名后加 /v1。

为什么返回 401？

常见原因：

• 缺少 Authorization header。
• API Key 写错或已失效。
• 把 <MOONAPIX_API_KEY> 占位符当作真实密钥使用。
• 请求经过代理或网关时丢失了鉴权 header。

为什么返回 403？

通常表示当前账号没有开通对应模型或能力。请检查模型名是否正确，并确认账号权限。

为什么返回 429？

表示请求频率过高或超过当前账号限制。建议降低并发、增加重试间隔，并对异步任务使用合理轮询频率。

异步任务需要等多久？

不同能力耗时不同。图片、音频通常较快；视频、数字人和音乐任务可能需要更久。业务系统应支持任务处理中状态，并允许用户稍后刷新结果。

任务失败后可以重试吗？

可以，但建议先检查失败原因：

• 参数错误：修正请求后再提交。
• 素材不合规或不可访问：更换素材。
• 额度不足：补足额度后再提交。
• 临时异常：使用指数退避重试。

重试时建议创建新任务，并在业务系统中记录原任务 ID 和新任务 ID。

Webhook 丢了怎么办？

Webhook 不能作为唯一结果来源。你应保存任务 ID，并通过任务查询接口主动查询最终状态。

结果 URL 会一直有效吗？

不同能力的结果 URL 有不同有效期。建议任务成功后尽快读取并保存到你的业务系统。如果 URL 失效，可以再次查询任务，或按业务需要重新生成。

可以批量提交任务吗？

可以，但建议控制并发。批量任务应记录每个任务的模型、请求参数、业务订单 ID、状态和结果 URL。

如何确认旧接口是否已包含在新文档？

查看 接口目录 或 API Reference。当前 OpenAPI 已覆盖导出文件中的全部接口操作，并通过覆盖检查防止路径缺失。