状态码与返回值

本文档详细说明本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可用于后续查询任务进度、获取最终结果，建议妥善保存。

开始使用

开发指南

常见问题

TTAPI集成指南

状态码与返回值

一、统一返回格式

1.1 成功返回格式

1.2 失败返回格式

二、HTTP状态码分类及说明

三、业务状态码分类及说明

四、常见返回示例

4.1 成功示例（生成类接口）

4.2 成功示例（查询类接口）

4.3 失败示例（参数错误）

4.4 失败示例（TT-API-KEY 错误）

五、注意事项

​一、统一返回格式

​1.1 成功返回格式

​1.2 失败返回格式

​二、HTTP状态码分类及说明

​三、业务状态码分类及说明

​四、常见返回示例

​4.1 成功示例（生成类接口）

​4.2 成功示例（查询类接口）

​4.3 失败示例（参数错误）

​4.4 失败示例（TT-API-KEY 错误）

​五、注意事项

一、统一返回格式

1.1 成功返回格式

1.2 失败返回格式

二、HTTP状态码分类及说明

三、业务状态码分类及说明

四、常见返回示例

4.1 成功示例（生成类接口）

4.2 成功示例（查询类接口）

4.3 失败示例（参数错误）

4.4 失败示例（TT-API-KEY 错误）

五、注意事项