接口调用说明
基本路径
﻿
﻿
﻿
所有 API 的路径都以 https://co.aippt.cn/api/ 开头
﻿
获取 Token & Code
﻿
Plan A: 接入 UI 版
仅需获取 Code, 前端初始化 AiPPT JSSDK 工具需要通过 获取JSSDK认证Code 接口获取对应的x-code来初始化 JSSDK 
﻿
Plan B: 接入 API 版
服务端调用 AiPPT API 需要通过 获取API认证Token 接口获取对应的x-token来通过 AiPPT 网关认证
前端初始化 AiPPT JSSDK 工具需要通过 获取JSSDK认证Code 接口获取对应的x-code来初始化 JSSDK 
﻿
接口鉴权说明
鉴权方式
采用 AK(api key)/SK(api secret) 签名认证, 开通 AP I账号得到 AK、SK
﻿
AK/SK 签名认证流程
1.构造规范请求: 将待发送的请求内容按照与API服务端约定的规则组装，确保客户端签名、API服务端认证时使用的请求内容一致。
2.创建待签字符串: 使用规范请求和其他信息创建待签字符串。
3.计算签名: 使用AK/SK和待签字符串计算签名。
4.信息上传: 将生成的签名信息作为请求消息头添加到 HTTP 请求中。
step1: 构造规范请求
使用AK/SK方式进行签名与认证，首先需要规范请求内容，然后再进行签名。客户端与API服务端使用相同的请求规范，可以确保同一个HTTP请求的前后端得到相同的签名结果，从而完成身份校验。
●HttpRequestMethod：HTTP 请求方法，如 GET、POST。
●ApiUri：请求资源路径，以 "/" 开头，并以 "/" 结尾，如果URI路径不以 "/" 结尾，则在尾部添加  "/" 如：/api/grant/token 需要变为 /api/grant/token/
●Timestamp: 请求的时间戳，单位秒。
step2: 创建待签字符串
伪代码: 各个参数之间用 "@" 隔开 stringToSign = HttpRequestMethod + "@" + ApiUri + "@" + Timestamp
示例(token): stringToSign = GET@/api/grant/token/@1696821929
示例(code): stringToSign = GET@/api/grant/code/@1696821929
step3: 计算签名
使用 SK和创建好的待签字符串进行 Hmac sha1 计算得到签名值 ，然后再做 base64_encode，计算得到最终签名值。
加密结果如：MipstvjcmFP20jd3WUCYvhYvzVE=
step4: 信息上传
最终请求体示例
5
GET https://co.aippt.cn/api/grant/token?uid=1&channel=xxx
Header:  x-api-key:645e1231d1ba5
Header:  x-timestamp:1696821929
Header:  x-signature:ACsZ2tral4zHq5opRIAgsxC1nOg=
﻿
获取 API 认证 Token
业务流程
﻿﻿
接口信息
描述:
token有效期目前是30天，建议接入方服务端缓存并跟踪 x-token 的过期时间并及时更新，避免频繁调用。 token 颗粒度是用户级别的，即：接入方下的每一个用户的 x-token 都不同。
接口地址:
/api/grant/token
请求方式:
GET
权限校验:
是
请求参数:
json
请求参数
参数名
位置
类型
是否必需
说明
x-api-key
header
string
是
创建账号时生成的api key
x-timestamp
header
int
是
请求时间戳，与计算签名使用的时间戳保持一致
x-signature
header
string
是
根据计算签名得到的最终签名值
uid
query
string
是
第三方用户唯一标识
channel
query
string
是
渠道标识, 可传空字符串或其他标识
请求示例
5
curl --location 'https://co.aippt.cn/api/grant/token?uid=1&channel=xxx' \
--header 'x-api-key: 645e1231d1ba5' \
--header 'x-timestamp: 1696821929' \
--header 'x-sign: Uf1UYWp45y0deQ9/eS1CCDQXqJ8='
响应字段
参数名
类型
说明
code
int
返回码，0表示成功，非0表示异常
msg
string
返回提示信息
data
object
返回数据
data.api_key
string
创建账号时生成的api key
data.uid
string
第三方用户唯一标识
data.token
string
token
data.time_expire
int
token有效期，30天
响应示例
11
{
    "code": 0,
    "data": {
        "api_key": "645e1231d1ba5",
        "uid": "123",
        "token": "ZDI0ZDNLZGUTNDIXMY0ZMTBILWEXNDYTOGU3MMQ5OGQ5YTAX",
        "time_expire": 2592000
    },
    "msg": "ok"
}
﻿
获取 JSSDK 认证 Code
业务流程
﻿﻿
接口信息
描述:
第三方用户在前端打开Iframe时，需要通过第三方服务端调用AIPPT API接口申请访问的授权码（x-code）。第三方拿到授权码（x-code）后，需要把授权码（x-code）传入 AIPPT JSSDK
接口地址:
/api/grant/code
请求方式:
GET
权限校验:
是
请求参数:
json
请求参数
参数名
位置
类型
是否必需
说明
x-api-key
header
string
是
创建账号时生成的api key
x-timestamp
header
int
是
请求时间戳，与计算签名使用的时间戳保持一致
x-signature
header
string
是
根据计算签名得到的最终签名值
uid
query
string
是
第三方用户唯一标识
channel
query
string
是
渠道标识, 可传空字符串或其他标识
请求示例
5
curl --location 'https://co.aippt.cn/api/grant/code?uid=1&channel=xxx' \
--header 'x-api-key: 645e1231d1ba5' \
--header 'x-timestamp: 1696821929' \
--header 'x-signature: S52ihSWntQ317tSIR4EEfGLL9FY=' \
响应字段
参数名
类型
说明
code
int
返回码，0表示成功，非0表示异常
msg
string
返回提示信息
data
object
返回数据
data.api_key
string
创建账号时生成的api key
data.uid
string
第三方用户唯一标识
data.code
string
code
data.time_expire
int
code有效期，24小时
响应示例
11
{
    "code": 0,
    "data": {
        "api_key": "645e1231d1ba5",
        "uid": "1",
        "code": "429738a59f91d6977843fd1c893bc66b",
        "time_expire": 86400
    },
    "msg": "ok"
}
﻿
调用规则
HTTP Verbs
Verb
Description
GET
用于获取数据
POST
用于操作数据
﻿
HTTP 提交说明
当 POST 请求的时候，请确保 Request Content-Type 是 application/json 类型。
2
req.Headers.Add("Content-Type", "application/json")
﻿
身份认证
AiPPT 所有的开放 API 都需要在请求的 HTTP Headers 传入  x-api-key与x-token 带入您的身份 Token 信息，用于完成认证。
参数说明
参数
描述
是否必传
形式
x-api-key
创建账号时生成的 App key
是
header
x-channel
渠道标识，适用于 B2B2C 的场景
是
header
x-token
通过认证接口获取到的 token
是
header
请求与响应示例
example
26
request:
curl --location 'https://co.aippt.cn/api/ai/chat/task' \
--header 'x-api-key: 645e1231d1ba5' \
--header 'x-channel: F' \
--header 'x-token: Y2QYY2UYNWYTZWU0ZC0ZODIYLTG4YTKTNZE3NDM5YWM1YZG3' \
--header 'Content-Type: application/json' \
--data '{
    "type":1,
    "title":"毕业季"
}'

response:
{
    "code": 0,
    "data": {
        "id": 44,
        "title": "毕业季",
        "status": 1,
        "import_url": "",
        "type": 1,
        "api_key": "645e1231d1ba5",
        "created_at": "2023-10-26T11:05:54.079+08:00"
    },
    "msg": "success"
}
﻿
状态码
HTTP 状态码
●200 - 成功
●400 - 请求的参数不正确，或缺少必要信息，请对比文档
●401 - 需要用户认证的接口用户信息不正确
●404 - 数据不存在，或未开放
●5xx - 服务器异常
﻿
业务状态码
场景
错误码
错误描述
备注
授权、鉴权相关
43100
鉴权系统错误
﻿
43101
鉴权系统参数不合法
﻿
43102
api_key不合法
﻿
43103
签名不合法
﻿
API公共
40000
API请求表单校验失败
﻿
40007
API请求参数错误
﻿
40008
API系统错误
﻿
AI生成相关
12100
AI系统错误
﻿
12101
AI触发违禁词验证
﻿
12102
AI任务不存在
﻿
12103
AI创建任务失败
﻿
12104
AI每日创建任务额度错误
﻿
用户作品相关
10000
作品操作公共错误
﻿
10001
作品保存失败
﻿
10002
作品不存在
﻿
10003
获取作品列表失败
﻿
10004
删除作品失败
﻿
10005
作品重命名失败
﻿
﻿