所有 API 共用的服务地址、请求头与响应结构。
生产接口基于 https://www.aigei.com/open/api/v1,使用 HTTPS。测试环境与生产环境的地址应明确区分。
| 操作 | 方法 | 参数位置 |
|---|---|---|
| 搜索 | POST | JSON 请求体 |
| 详情、文件下载、预览下载 | GET | URL 查询参数 |
GET 参数请由客户端正确进行 URL 编码;不要手工拼接未编码的资源编号。POST 请求使用 application/json。
| 参数名 | 中文名称 | 数据类型 | 必填 | 示例 | 取值约束 | 功能描述 |
|---|---|---|---|---|---|---|
Authorization |
身份凭证 | string | 是 | "Bearer <API_KEY>" |
- | 填写 Bearer 加一个空格,再填写开放平台 API Key;不要放入 URL。 |
Content-Type |
请求内容类型 | string | 否 | "application/json" |
- | POST 搜索提交 JSON 请求体时必填;GET 接口不提交请求体。 |
| 参数名 | 中文名称 | 数据类型 | 必返 | 示例 | 取值约束 | 功能描述 |
|---|---|---|---|---|---|---|
Content-Type |
响应内容类型 | string | 否 | "application/json" |
- | 接口响应使用 JSON。requestId、timeElapsed 等业务字段位于响应体中。 |
code 为 10001 表示成功;失败时 data 为 null。登录用户搜索与详情成功后返回 quota;预览与文件下载成功后返回 fund。
可选字段可能省略;类型包含 null 时也可能返回 null。“必返”表示父对象存在且非 null 时必须返回。
| 参数名 | 中文名称 | 数据类型 | 必返 | 示例 | 取值约束 | 功能描述 | |||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
requestId |
请求编号 | string / null | 是 | "f0f931dbaf264523a3ba018f44d0954a" |
- | 本次请求的编号,排查问题时请提供。 |
|||||||||||||||||||||||||||||||||||||||||
code |
状态码 | string | 是 | "10001" |
- | 业务状态码;10001 表示成功,其他值表示失败。 |
|||||||||||||||||||||||||||||||||||||||||
message |
状态说明 | string | 是 | "Success" |
- | 状态或错误说明;以 code 判断成功或失败。 |
|||||||||||||||||||||||||||||||||||||||||
timeElapsed |
执行耗时 | string / null | 是 | "508ms" |
- | 请求耗时,单位毫秒,带 ms 后缀。 |
|||||||||||||||||||||||||||||||||||||||||
fund |
实际扣费信息 | object | 否 | - |
仅支持已列字段
|
登录用户预览或文件下载成功后的实际费用与账户余额;查询、游客调用及失败时省略。 |
|||||||||||||||||||||||||||||||||||||||||
fund · 对象子属性
|
|||||||||||||||||||||||||||||||||||||||||||||||
data |
业务数据 | object / null | 是 | null |
- | 成功时返回对应接口的业务对象,失败时为 null。 |
|||||||||||||||||||||||||||||||||||||||||
quota |
调用额度 | object | 否 | - |
仅支持已列字段
|
登录用户搜索或详情成功后的调用额度消耗和剩余量,不是费用;游客、下载调用及失败时省略。 |
|||||||||||||||||||||||||||||||||||||||||
quota · 对象子属性
|
|||||||||||||||||||||||||||||||||||||||||||||||
{
"requestId" : "preview-example",
"code" : "10001",
"message" : "Success",
"timeElapsed" : "508ms",
"data" : {
"fileId" : "xPACzaFWLfJqiv6FRxsq7TmEIOJ38X",
"fileType" : "image",
"fileExtName" : "jpg",
"imageSize" : "mini",
"imageProperties" : {
"imageWidthPx" : 198,
"imageHeightPx" : 132
},
"fileDownloadUrl" : "https://example.com/open-api/previews/image.jpg?e=1792531200&token=example-signature"
},
"fund" : {
"fundNotice" : "Free",
"fundType" : "down",
"fundValue" : 0,
"fundBalance" : 5000
}
}
{
"requestId" : null,
"code" : "50401",
"message" : "Invalid request parameters",
"timeElapsed" : "0ms",
"data" : null
}