接入 API

认证方式

所有 API 请求（除公开接口外）需要在 HTTP Header 中携带 app-key 进行身份认证：

app-key: your_app_key_here

分销商用户还需额外携带 x-code 头：

x-code: your_distributor_code

请求格式

Content-Type: application/json

字符编码: UTF-8

Base URL: https://api.jieshuo.cn

所有请求路径以 /v1 为前缀，例如：

POST $API_HOST/v1/tasks/tts
GET  $API_HOST/v1/tasks/{task_id}

统一响应格式

成功响应

{
  "code": 10000,
  "message": "Success",
  "data": {
    // 业务数据
  }
}

分页响应

{
  "code": 10000,
  "message": "Success",
  "data": {
    "items": [],
    "total": 100,
    "page": 1,
    "page_size": 20
  }
}

错误响应

{
  "code": 10009,
  "message": "余额不足",
  "error_code": "INSUFFICIENT_BALANCE",
  "details": {
    "required": 150.0,
    "available": 50.0
  }
}

错误码表

认证与授权（10001-10006, 10018-10019）

错误码	error_code	说明	HTTP 状态码
10001	`FAILED`	通用失败	200
10002	`APP_KEY_EXPIRE`	app-key 已过期	401
10003	`SIGN_EXPIRE`	签名过期	401
10004	`INVALID_APP_KEY`	无效的 app-key	401
10005	`INVALID_SIGN`	无效的签名	401
10006	`INVALID_TIMESTAMP`	无效的时间戳	401
10018	`ACCOUNT_DISABLED`	账户已禁用	401
10019	`INVALID_DISTRIBUTOR_CODE`	无效的分销商码	401

资源不存在（10007, 10010-10017）

错误码	error_code	说明
10007	`NOT_FOUND`	通用资源不存在
10010	`TASK_NOT_FOUND`	任务不存在
10012	`TASK_TYPE_NOT_FOUND`	任务类型不存在
10015	`FILE_NOT_FOUND`	文件不存在
10016	`WORK_NOT_FOUND`	作品不存在
10017	`USER_NOT_FOUND`	用户不存在

业务校验（10008-10014, 10020-10021）

错误码	error_code	说明
10008	`INVALID_METHOD`	HTTP 方法不允许
10009	`INSUFFICIENT_BALANCE`	用户余额不足
10011	`TASK_CREATE_FAILED`	任务创建失败
10013	`INSUFFICIENT_BALANCE_KEY`	子密钥配额不足
10014	`VALIDATION_ERROR`	参数校验失败
10020	`FILE_VALIDATION_FAILED`	文件校验失败（格式/编码/一致性）
10021	`STORAGE_EXCEEDED`	存储空间不足

外部服务错误（40000-49999）

错误码	error_code	说明
40000	`GRADIO_TIMEOUT`	处理服务超时
40001	`SERVICE_UNAVAILABLE`	外部服务不可用
40002	`CALLBACK_FAILED`	回调通知失败

系统错误（50000-59999）

错误码	error_code	说明
50000	`UNAUTHORIZED`	授权失败（系统级）
50001	`DATABASE_ERROR`	数据库错误
50002	`SYSTEM_BUSY`	系统繁忙（请求频率过高）
50003	`SYSTEM_ERROR`	系统错误
50004	`CONFLICT`	数据冲突

可重试（60000）

错误码	error_code	说明
60000	`CAN_RETRY`	可重试，建议稍后再试

回调机制

回调通知

创建任务时传入 callback_url，任务完成或失败后平台会向该地址发送 HTTP POST 请求：

{
  "task_id": "task_xyz789",
  "status": 2,
  "status_name": "completed",
  "consumed_points": 7.2,
  "results": {
    // 任务结果数据
  }
}

回调认证

如需验证回调来源，可在创建任务时传入 callback_auth，平台会在回调请求中携带该认证信息。

回调重试

回调失败时，平台不会自动重试。建议通过主动轮询接口 GET /v1/tasks/{task_id} 作为兜底方案。

速率限制

建议单个 app-key 的请求频率不超过 10 次/秒

超过频率限制时返回 HTTP 429，响应中包含 retry_after 字段（单位：秒）

建议在客户端实现指数退避重试策略

认证方式#

请求格式#

统一响应格式#

成功响应#

分页响应#

错误响应#

错误码表#

认证与授权（10001-10006, 10018-10019）#

资源不存在（10007, 10010-10017）#

业务校验（10008-10014, 10020-10021）#

外部服务错误（40000-49999）#

系统错误（50000-59999）#

可重试（60000）#

回调机制#

回调通知#

回调认证#

回调重试#

速率限制#