本文档详细说明本API所有接口的统一返回格式、状态码含义及异常返回示例，便于开发者快速定位接口调用问题、解析返回数据。
一、统一返回格式
本API所有接口返回数据均采用JSON格式，无论请求成功或失败，返回结构保持一致，便于前端统一解析处理。
1.1 成功返回格式
{
"status": "SUCCESS", // 状态码（成功固定为 'SUCCESS'）
"message": "success", // 提示信息（成功默认返回success）
"data": { // 核心返回数据（不同接口结构不同，详见各接口文档）
// 具体接口返回的业务数据
}
}
1.2 失败返回格式
{
"status": "FAILED", // 失败状态码（失败固定为 'FAILED'）
"message": "参数错误", // 错误提示信息（详细说明错误原因）
"data": null // 失败时无有效数据，固定为null
}
二、HTTP状态码分类及说明
状态码遵循HTTP标准状态码规范，结合业务场景扩展部分自定义状态码，按类型分类如下，方便开发者快速识别错误类型。
| 状态码 | 说明 | 常见场景 |
|---|
| 200 | 请求成功 | 生成类接口请求成功、查询类接口查询成功 |
| 400 | 参数错误 | 参数为空、格式不符合要求、参数类型错误 |
| 401 | 未授权 | 未携带TT-API-KEY、TT-API-KEY错误或伪造 |
| 402 | 余额不足 | 账户余额不足 |
| 404 | 请求资源不存在 | 接口地址错误、请求的资源不存在 |
| 429 | 请求过于频繁 | 短时间内多次调用同一接口，超过接口限流阈值 |
| 499 | 队列不足 | 用户产品队列不足 |
| 500 | 系统错误 | 服务端代码异常、数据库异常、第三方服务调用失败 |
| 504 | 请求超时 | 响应超时，同步且耗时的接口建议使用 api.ttapi.org 域名 |
三、业务状态码分类及说明
业务状态码指请求响应JSON数据中的status字段，代表业务请求状态。
| 状态码 | 说明 |
|---|
PENDING_QUEUE | 任务正在队列中等待 |
ON_QUEUE | 任务正在处理中 |
SUCCESS | 任务成功完成 |
FAILED | 任务执行失败 |
四、常见返回示例
以下为高频场景的返回示例，开发者可参考该格式解析接口返回数据，排查异常问题。
4.1 成功示例（生成类接口）
{
"status": "SUCCESS",
"message": "success",
"data": {
"jobId": "b8bd3ff0-4349-4b71-8938-5e13aefa64fe"
}
}
4.2 成功示例（查询类接口）
{
"status": "SUCCESS",
"message": "",
"jobId": "8ddd973f-b5ff-4192-b418-b37fb65c65f3",
"data": {
"action": "imagine",
"jobId": "8ddd973f-b5ff-4192-b418-b37fb65c65f3",
"progress": "100",
"prompt": "一只可爱的猫咪",
"quota": "2",
"discordImage": "https://cdn.ttapi.io/midjourney/2025-11-14/20260307_024522_19cf9806e1c7438b.png",
"cdnImage": "https://cdn.ttapi.io/midjourney/2025-11-14/20260307_024522_19cf9806e1c7438b.png",
"width": 960,
"height": 1200,
"hookUrl": "https://webhook-test.com/40bb50795afa242aee8c837617cd72e9",
"components": [
"upsample1","upsample2","upsample3","upsample4","reroll","variation1","variation2","variation3","variation4"
],
"seed": null,
"images": [
"https://cdn.ttapi.io/midjourney/20260307/5c7261ec-7271-495d-a0f7-4dd395652a84tl.png",
"https://cdn.ttapi.io/midjourney/20260307/5c7261ec-7271-495d-a0f7-4dd395652a84tr.png",
"https://cdn.ttapi.io/midjourney/20260307/5c7261ec-7271-495d-a0f7-4dd395652a84bl.png",
"https://cdn.ttapi.io/midjourney/20260307/5c7261ec-7271-495d-a0f7-4dd395652a84br.png"
]
}
}
4.3 失败示例（参数错误）
{
"status": "FAILED",
"message": "[Invalid parameter] Invalid value for argument: `--v`:`8`",
"data": null
}
4.4 失败示例（TT-API-KEY 错误）
{
"status": "FAILED",
"message": "Wrong TT-API-KEY or email is not activated."
}
五、注意事项
-
状态码为400-499时，优先检查客户端请求参数、请求方法、token有效性，无需联系服务端。
-
状态码为500-599时，属于服务端异常，请先重试1-2次，若仍失败，联系技术支持。
-
生成类与查询类接口仅成功响应格式有差异，失败响应格式完全统一，前端可统一处理失败逻辑。
-
生成类接口返回的jobId可用于后续查询任务进度、获取最终结果，建议妥善保存。
