Appearance

1. 文档说明 ​

该文档主要用来说明 KaCha AI 相关能力的 API 接口。

2. 接口说明 ​

接口采用HTTP方式提供接口返回采用Json对象传递。

3. 通用说明 ​

3.1 关于API-KEY ​

所有的 API需要通过 API-KEY 进行鉴权。当前，请与商务对接人联系，获取分配给您的 API-KEY。请注意保管您的 API-KEY。 如果发现泄露，请立即联系我们，以获取新的 KEY，并及时作废已泄露的 KEY。

3.2 通用错误返回 ​

当接口请求处理出错时，接口会返回通用的错误返回格式

3.2.1 返回格式 ​

json
 {
  code: 0, // 返回的 code
  data: {},  // 成功时，包含结果数据对象
  msg: ""  // 失败时，返回失败的原因说明
  }

3.2.2 错误代码说明 ​

错误码说明
0成功
1001API-KEY无效
1002API-KEY已过期
1003请求参数错误
1004请求频率过高
1005请求超时
1006服务器内部错误

4. 详细接口 ​

4.1 发起图片任务 ​

发起任务请求。

4.1.1 请求URL ​

%domain%/saas/api/call

4.1.2 请求方式 ​

POST

4.1.3 是否需要鉴权 ​

是，API-KEY 鉴权，将开发者 API-KEY 放到请求的 Header 中： --header 'X-Api-Key: xxxx'

4.1.4 请求参数 ​

参数字段是否必选字段类型说明
func是string调用的功能类型，参考功能列表
source_img是string输入图片的URL
params是string与功能相关的其他参数，参考功能列表中的说明
callback否string需要回调结果时，填入回调的URL，回调的参数格式与结果查询的格式相同，参考结果查询的说明

4.1.5 请求参数 ​

功能标签说明
hair_change换发型，需要的参数见参数说明

4.1.6 换发(hair_change)参数说明 ​

功能标签是否必选字段类型说明
style_id是string目标发型/发色的编号，由训练生成。
  • 当前支持的模型 ID 列表 （请联系对接人咨询。）

4.1.7 返回结果 ​

错误返回请详见通用错误返回 正常返回字段如下：

返回字段字段类型说明
task_idstring任务ID
task_typestring对应输入的参数 func
statusinit提交任务时，一般为 0，其他值的含义： 0-未完成；1-已完成；2-已失败
json
{
  "code": 0,
  "data": {
      "id": 17,
      "created_at": "2024-09-05T17:10:41.114289106+08:00",
      "updated_at": "2024-09-05T17:10:41.114289106+08:00",
      "user_id": "1829431876063244288",
      "task_id": "1831620958831886336",
      "task_type": "hair_change",
      "status": 0,
      "callback_url": "",
      "result": null
  },
  "msg": "Success"
}

4.1.8 注意事项 ​

4.1.9 其他 ​

4.2 查询任务状态 ​

使用发起任务时返回的 task_id 查询结果

4.2.1 请求 URL ​

%domain%/saas/api/query

4.2.2 HTTP 请求方式 ​

POST

4.2.3 请求参数 ​

参数名类型是否必填说明
task_idstring是任务ID

4.2.4 返回结果 ​

错误返回请详见通用错误返回 正常返回字段如下：

参数名类型说明
task_idstring查询的 task_id
statusinit提交任务时，一般为 0，其他值的含义： 0-未完成；1-已完成；2-已失败
resultobject执行结果,status =1 时有值

范例： 以下是换发的结果：

json
{
    "code": 0,
     "data": {
        "id": 17,
        "created_at": "2024-09-05T17:10:41+08:00",
        "updated_at": "2024-09-05T17:10:50+08:00",
        "user_id": "1829431876063244288",
        "task_id": "1831620958831886336",
        "task_type": "hair_change",
        "status": 1,
        "callback_url": "",
        "result": {
            "hair_change": [
                "https://cdn.aistyle.me/nana/app/user/1829431876063244288/finish/1831620958831886336/saas_hair_change_01/xxx.jpg"
            ]
        }
    },
    "msg": "Success"
}

4.2.5 注意事项 ​

4.2.6 其他 ​

5 通用代码 ​

5.1 操作是否成功 ​

代码代码含义
0成功
非0失败,请看错误代码表

6 错误代码 ​

6.1 系统级错误代码 ​

代码详细描述
7通用错误，参考 msg 详情
403鉴权失败
4001当前功能不支持
4002请求体格式错误
4003没有足够的 credit 了
4004API key 无效
4005账户已被禁用
5000系统内部错误