所有用户侧 API 请求通过 Gateway 进入对应业务服务。客户端页面、管理后台和第三方集成应以实际部署的 Gateway 地址、已发布路由和授权范围为准，不直接访问内部服务端口。

当前 Gateway 路由主要服务于 FrameAI 自身客户端和服务间调用，并不等同于已对外发布的 Open API。面向第三方的认证、限流、Webhook、稳定版本与接口合同请以开放平台 API的规划文档为准；在平台正式发布前，不应使用内部路由、演示密钥或客户端页面中的示例地址进行外部集成。

基本要求

项目	约定
基础地址	使用部署的公共入口，例如 https://APP_DOMAIN/api。
认证	使用登录态或平台签发的授权凭证；不得把凭证写入前端源码。
内容类型	JSON 请求使用 application/json；文件上传按接口要求使用 multipart。
标识符	对项目、任务、订单等资源使用服务返回的 ID，不自行构造。
幂等性	支付、创建任务等具备副作用的请求应避免重复提交。

异步生成任务

生成类请求通常先创建任务，再通过任务查询或客户端任务抽屉获得状态。推荐调用方：

1. 提交前校验必填提示词、模型参数与参考素材。
2. 保存创建响应中的任务 ID。
3. 以合理间隔轮询状态，或通过平台支持的回调方式等待结果。
4. 成功后读取结果资源并保存到项目资产；失败后读取稳定错误信息，不要无限重试。

客户端中可见的演示端点包括视频生成任务提交、视频任务查询和渠道健康检查；实际可用路由以 Gateway 路由配置与部署版本为准。

错误处理

• 对用户展示可行动的业务错误，例如参数不完整、资源不存在、权限不足、渠道暂不可用。
• 后端日志记录请求上下文、任务 ID 和内部错误原因，但脱敏处理凭证和个人数据。
• 收到 401 或 403 时检查登录态或授权范围；收到 404 时检查 Gateway 路由与资源 ID；收到 5xx 时保留请求/任务 ID 后检查目标服务日志。

上一页服务边界与数据

下一页配置参考