* **上传图片接口**：如果用户在使用图生图功能时，需要先调此接口上传图片后才可拿到生图依赖的参数
* **生图/视频接口：**用户传入生图/视频依赖的参数，可以得到一个 taskId ，通过 taskId 可以查询到生图结果
* **精绘接口：**对传入的图片进行高清处理，类似于生图接口，得到 taskId 后，通过 taskId 可以查询到生图结果
* **查询生图结果接口：**传入 taskId 可以查询到生图结果
## 基础介绍
### 访问授权
#### Prefix
`https://a1.art`
注：中国境内遇到备案问题可以尝试使用域名[`https://a1art.xiaopiu.com`](https://a1art.xiaopiu.com)
### 请求规范说明
* 网络协议：`HTTPS`协议。
* 编码格式：`UTF-8`编码。
* 请求头部：必须需要携带`apiKey`[（获取API key）](https://a1.art/?open=apikey)，用于后台的认证与鉴权。
* 响应结果：`JSON`数据格式。API 的响应体结构包含`code、msg、msg_cn、data`四个部分。`code`为错误码，`msg` 为英文错误说明，`msg_cn`为中文错误说明，`data`为调用 API 后返回的结果；如果`code` 不为`0`则认为请求失败，失败信息可参考`msg`和`msg_cn`。
#### **响应体**
| **参数名** | **类型** | **描述** |
| ------- | ------ | ------ |
| code | int | 错误码 |
| msg | string | 英文错误信息 |
| msg\_cn | string | 中文错误信息 |
| data | json | 响应数据 |
### 数据结构
#### Application
```javascript
export type APPInfo = {
id: string;
versionId: string;
name: string;
formArr: []Form;
styleArr: []Style;
updateDate: Date;
createDate: Date;
processTime: string; // 该app最近生图的平均耗时
};
```
#### Form
```javascript
// form中的type字段的类型，对应风格、图片、文本、尺寸
export type FormItemTypeFieldType = 'style' | 'cnet' | 'description' | 'size' ;
export type Form = {
id: string; // 生图接口需传的id（带有inputs的description除外）
type: FormItemTypeFieldType;
title: string;
inputs: []Input;
position: string; // 合照图片的位置
};
```
#### Input
```javascript
export type Input = {
id: string; // 生图接口description表单需传的id
title: string;
tags: []string; // description表单提示词
};
```
#### Style
```javascript
export type Style = {
id: string;
name: string;
image: string;
};
```
#### Size
```javascript
// form中的sizeId字段的类型，1到7对分别对应的size 1:1 3:4 1:2 4:3 2:1 16:9 9:16
export type FormSizeIdType = '1' | '2' | '3' ｜ '4' | '5' ｜ '6' | '7' ;
```
#### Task
```javascript
// task 执行状态，0—任务已提交 10-任务已完成 20-任务失败 30-任务进行中
export type TaskStateType = 0 ｜10 | 20 | 30 ;
export type Task = {
id: string;
startDate: Date;
finishDate: Date;
createDate: Date;
images: []string;
state: number;
};
```
### `API key`
要以用户身份发出授权请求，您必须使用 API key，您可以登陆a1之后，点击API Manage，查找并管理您的 API key
 .png?alt=media\&token=7c4bb234-f2bb-4bee-a128-d3d13cc1814c)
### `Application`
#### 获取Application详情
`/open-api/v1/a1/apps/{appId}` \&GET
**请求参数**
| 字段名 | 类型 | 位置 | 是否必传 | 含义 |
| -------- | ------ | ------ | ---- | ---------------------------------------------------------------------------------------------------------------- |
| apiKey | string | header | 是 | API key |
| appId | string | path | 是 | 应用id |
| language | string | query | 否 | 语言，不传默认为发布时使用的文案，支持翻译为zh\_CN,en\_US,zh\_TW,ru\_RU,ja\_JP,pt\_BR,es\_MX,de\_DE,id\_ID,tr\_TR,vi\_VN,th\_TH,ms\_MY |
**参数限制**
* 不支持查询带有数字分身组件、wordart组件、group photo组件为 user upload模式（绝大多数合照应用不再此范围内）、Video组件的app
* 不支持查询未发布的节点式应用信息
**请求示例**
{% tabs %}
{% tab title="Curl" %}
```sh
curl --location --request GET 'https://a1.art/open-api/v1/a1/apps/{appId}' \
--header 'apiKey: {apiKey}' \
--header 'Accept: */*' \
--header 'Host: a1.art' \
--header 'Connection: keep-alive'
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://a1.art/open-api/v1/a1/apps/{appId}"
payload={}
headers = {
'apiKey': {apiKey}
}
response = requests.request("GET", url, headers=headers, data=payload)
print(response.text)
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
var axios = require('axios');
var config = {
method: 'get',
url: 'https://a1.art/open-api/v1/a1/apps/{appId}',
headers: {
'apiKey': {apiKey},
'Accept': '*/*',
'Host': 'a1.art',
'Connection': 'keep-alive'
}
};
axios(config)
.then(function (response) {
console.log(JSON.stringify(response.data));
})
.catch(function (error) {
console.log(error);
});
```
{% endtab %}
{% endtabs %}
**响应示例**
```json
{
"code": 0,
"msg": "success",
"msg_cn": "成功",
"data": {
"appInfo": {
"id": "1803632078862147586",
"versionId": "1803632078866341890",
"name": "Crazy Pet",
"formArr": [ // 生图待传的表单参数
{
"id": "1705408562085",
"type": "cnet",
"title": "Photo of your pet",
"position": "0"
},
{
"id": "1705403286130",
"type": "description",
"title": "Description",
"inputs": [
{
"id": "description_1705463790428_variant1",
"title": "Color and breed, such as: black devon rex cat",
"tags": [
"Obsidian_black",
"Porcelain_white"
]
}
]
},
{
"id": "1705398050190",
"type": "style",
"title": "Style"
},
{
"id": "1705403291444",
"type": "size",
"title": "Size"
}
],
"styleArr": [
{
"id": "1766068889598496769",
"name": "High Quality Anmie",
"image": "https://cdn.a1.art/assets/style/cover_image/6d7358e9-ddae-4253-bcc9-d4f54ebc25d5.png"
}
],
"updateDate": "2024-06-20 19:51:55.0",
"createDate": "2024-06-20 11:32:52.0",
"processTime": "22", // 该app最近生图的平均耗时
"cost": 2 // 节点式应用消耗点数
}
}
}
```
### `Image`
#### 上传图片：`/open-api/v1/a1/images/upload`& POST
注：只有通过我们系统上传的图片才可用来做生图参数
**请求参数**
| 字段名 | 类型 | 位置 | 是否必传 | 含义 |
| -------- | ------ | --------- | ------------ | ------- |
| apiKey | string | header | 是 | API key |
| file | file | form-data | 与imageUrl传其一 | 图片文件 |
| imageUrl | string | form-data | 与file传其一 | 图片链接 |
**参数限制**
* 仅支持上传png、jpg、jpeg格式的图片文件
* 支持通过 form 表单的形式上传图片
* 支持通过在线图片链接的方式上传图片
* 每次仅可上传一张图片
* 图片文件大小不可大于10 M
**请求示例**
{% tabs %}
{% tab title="Curl" %}
```sh
curl --location --request POST 'https://a1.art/open-api/v1/a1/images/upload' \
--header 'apiKey: {apiKey}' \
--header 'Accept: */*' \
--header 'Host: a1.art' \
--header 'Connection: keep-alive' \
--header 'Content-Type: multipart/form-data;' \
--form 'file=@"/Users/xxx/Downloads/imageName.png"' \
--form 'imageUrl="https://xxx/xxx.jpeg"'
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://a1.art/open-api/v1/a1/images/upload"
payload={
'imageUrl': 'https://xxx/xxx.jpeg'
}
files=[
('file',('imageName.jpg',open('/Users/xxx/Downloads/imageName.jpg','rb'),'image/jpeg'))
]
headers = {
'apiKey': {apiKey}
}
response = requests.request("POST", url, headers=headers, data=payload, files=files)
print(response.text)
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
var axios = require('axios');
var FormData = require('form-data');
var fs = require('fs');
var data = new FormData();
data.append('file', fs.createReadStream('/Users/xxx/Documents/iamgeName'));
data.append('imageUrl', 'https://xxx/xxx.jpeg');
var config = {
method: 'post',
url: 'https://a1.art/open-api/v1/a1/images/upload',
headers: {
'apiKey': {apiKey},
'Accept': '*/*',
'Host': 'a1.art',
'Connection': 'keep-alive',
...data.getHeaders()
},
data : data
};
axios(config)
.then(function (response) {
console.log(JSON.stringify(response.data));
})
.catch(function (error) {
console.log(error);
});
```
{% endtab %}
{% endtabs %}
**响应示例**
```json
{
"code": 0,
"msg": "success",
"msg_cn": "成功",
"data": {
"imageUrl": "63fa41e7-e282-4582-a07b-8e5e73e8d388.jpg",
"path": "assets/application/apikey_5f6ccf7b983e499fb8ba4e5c4de8013f/form/"
}
}
```
#### 生成图片/视频：**`/open-api/v1/a1/images/generate`& POST**
> 注：
>
> 1. 节点式应用有单独的点数消耗规则，详情请参照 [节点式应用 VS 表单式应用](https://fyze31atzb.feishu.cn/docx/H2aKdptrHotppqx3N7GcmV7Vnob)
> 2. 生成1个视频消耗10积分
**请求参数**
| 字段名 | 类型 | 位置 | 是否必传 | 含义 |
| ----------------------------------------------- | ------------------ | ------ | ---- | --------------------------------------------------------------------------- |
| apiKey | string | header | 是 | API key |
| appId | string | body | 是 | 应用id |
| versionId | string | body | 是 | 应用版本 id (如果遇到“应用版本已更新，请重新获取应用信息”的报错，则代表应用已经更新，需要重新获取一下） |
| generateNum | string | body | 是 | 本次请求生成图片/视频的数量 |
| cnet | \[]cnetForm | body | 否 | 图生图、图生视频依赖的图片（如果查询 app 详情接口没返回才不用填，代表这个应用不需要输入图片） |
| [cnetForm.id](http://cnetform.id) | string | body | 是 | formArr 中 type 为 cnet 的 form 的 id |
| cnetForm.imageUrl | string | body | 是 | 见上传图片接口的返回值 |
| cnetForm.path | string | body | 是 | 见上传图片接口的返回值 |
| cnetForm.position | string | body | 否 | 合照图片索引位置 （用到合照功能需传该字段，表示将图片附于合照指定位置-索引从0开始） |
| description | \[]descriptionForm | body | 否 | 生图/视频依赖的描述词（如果查询 app 详情接口没返回才不用填，代表这个应用没有开放描述词输入） |
| [descriptionForm.id](http://descriptionform.id) | string | body | 是 | formArr 中 type 为 description 的 form 的 id（如果有inputs字段的话则为input的id） |
| descriptionForm.value | string | body | 是 | 描述词 |
| styleId | string | body | 否 | 生图/视频依赖的图片风格，来源— styleArr 中的id（如果查询 app 详情接口没返回才不用填，代表这个应用只能生成固定 style 的图片） |
| size | sizeForm | body | 否 | 生图/视频依赖的图片尺寸；（如果查询 app 详情接口没返回才不用填，代表这个应用只能生成固定尺寸的图片） |
| sizeForm.sizeId | string | body | 是 | 1到7对分别对应的size 1:1 3:4 1:2 4:3 2:1 16:9 9:16 |
**参数限制**
* 需要带上application最新的versionId
* 暂不支持使用未发布的节点式应用生图、视频换脸生视频
* 必须使用本系统存储的图片
* 需要传图片/视频生成数量（generateNum=1）注：节点式应用单次仅能生成一张图/视频
* 对于application formArr 里面的参数，每个type的参数至少传一个
* 在传form里面类型为description的参数时，如果form拥有inputs字段，description的id则应该传input的id
**请求示例**
{% tabs %}
{% tab title="Curl" %}
```sh
curl --location --request POST 'https://a1.art/open-api/v1/a1/images/generate' \
--header 'apiKey: {apiKey}' \
--header 'Content-Type: application/json' \
--header 'Accept: */*' \
--header 'Host: a1.art' \
--header 'Connection: keep-alive' \
--data-raw '{
"cnet": [
{
"id": {cnetId},
"imageUrl": {imageUrl},
"path": {path},
"position": {position}
}
],
"description": [
{
"id": {descriptionId/inputId}, # form如果没有inputs字段，则传description的id而非input的id
"value": {value}
}
],
"styleId": {styleId},
"size": {
"sizeId": {sizeId}
},
"appId": {appId},
"versionId": {versionId},
"generateNum": {generateNum}
}'
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
import json
url = "https://a1.art/open-api/v1/a1/images/generate"
payload = json.dumps({
"cnet": [
{
"id": {cnetId},
"imageUrl": {imageUrl},
"path": {path},
"position": {position}
}
],
"description": [
{
"id": {descriptionId/inputId}, # form如果没有inputs字段，则传description的id而非input的id
"value": {value}
}
],
"styleId": {styleId},
"size": {
"sizeId": {sizeId}
},
"appId": {appId},
"versionId": {versionId},
"generateNum": {generateNum}
})
headers = {
'apiKey': {apiKey},
'Content-Type': 'application/json',
'Accept': '*/*',
'Host': 'a1.art',
'Connection': 'keep-alive'
}
response = requests.request("POST", url, headers=headers, data=payload)
print(response.text)
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
var axios = require('axios');
var data = JSON.stringify({
"cnet": [
{
"id": {cnetId},
"imageUrl": {imageUrl},
"path": {path},
"position": {position}
}
],
"description": [
{
"id": {descriptionId/inputId}, // form如果没有inputs字段，则传description的id而非input的id
"value": {value}
}
],
"styleId": {styleId},
"size": {
"sizeId": {sizeId}
},
"appId": {appId},
"versionId": {versionId},
"generateNum": {generateNum}
});
var config = {
method: 'post',
url: 'https://a1.art/open-api/v1/a1/images/generate',
headers: {
'apiKey': {apiKey},
'Content-Type': 'application/json',
'Accept': '*/*',
'Host': 'a1.art',
'Connection': 'keep-alive'
},
data : data
};
axios(config)
.then(function (response) {
console.log(JSON.stringify(response.data));
})
.catch(function (error) {
console.log(error);
});
```
{% endtab %}
{% endtabs %}
**响应示例**
```json
{
"code": 0,
"msg": "success",
"msg_cn": "成功",
"data": {
"taskId": "507b080cfe17f7956e8690c4eba2b80f"
}
}
```
#### **图片精绘：/open-api/v1/a1/images/optimize& POST**
1. **请求参数**
| 字段名 | 类型 | 位置 | 是否必传 | 含义 |
| -------- | ------ | ------ | ---- | ----------- |
| apiKey | string | header | 是 | API key |
| path | string | body | 是 | 见上传图片接口的返回值 |
| imageUrl | string | body | 是 | 见上传图片接口的返回值 |
2. **参数限制**
* 必须使用本系统存储的图片
* 图片精绘每次消耗 3 个点数
* 精绘图片尺寸限制为2048 \* 2048
3. **请求示例**
{% tabs %}
{% tab title="Curl" %}
```sh
curl --location --request POST 'https://a1.art/open-api/v1/a1/images/optimize' \
--header 'apiKey: {apiKey}' \
--header 'Content-Type: application/json' \
--header 'Accept: */*' \
--header 'Host: a1.art' \
--header 'Connection: keep-alive' \
--data-raw '{
"path": {path},
"imageUrl": {imageUrl}
}'
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
import json
url = "https://a1.art/open-api/v1/a1/images/optimize"
payload = json.dumps({
"path": {path},
"imageUrl": {imageUrl}
})
headers = {
'apiKey': {apiKey},
'Content-Type': 'application/json',
'Accept': '*/*',
'Host': 'a1.art',
'Connection': 'keep-alive'
}
response = requests.request("POST", url, headers=headers, data=payload)
print(response.text)
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
var axios = require('axios');
var data = JSON.stringify({
"path": {path},
"imageUrl": {imageUrl}
});
var config = {
method: 'post',
url: 'https://a1.art/open-api/v1/a1/images/optimize',
headers: {
'apiKey': {apiKey},
'Content-Type': 'application/json',
'Accept': '*/*',
'Host': 'a1.art',
'Connection': 'keep-alive'
},
data : data
};
axios(config)
.then(function (response) {
console.log(JSON.stringify(response.data));
})
.catch(function (error) {
console.log(error);
});
```
{% endtab %}
{% endtabs %}
4. **响应示例**
> 响应结构同生成图片
```sh
{
"code": 0,
"msg": "success",
"msg_cn": "成功",
"data": {
"taskId": "507b080cfe17f7956e8690c4eba2b80f"
}
}
```
### `Task`
**查询任务执行结果：`/open-api/v1/a1/tasks/{taskId}`& GET**
> 注：生成的图片地址后续可能会失效，建议将生成结果保存在自己的cdn上
1. 可以等 5s 后在通过轮询去查询结果
2. task 的 state 状态枚举可见TaskStateType
**请求参数**
| 字段名 | 类型 | 位置 | 是否必传 | 含义 |
| ------- | ------ | ------ | ---- | -------------------------- |
| apiKey | string | header | 是 | API key |
| section | string | header | 否 | 图片资源所属地区，中国区使用传 cn，其他地区可不传 |
| taskId | string | path | 是 | 生成图片接口返回的taskId |
**参数限制**
* 只能查询当前用户ID下的task
**请求示例**
{% tabs %}
{% tab title="Curl" %}
```sh
curl --location --request GET 'https://a1.art/open-api/v1/a1/tasks/{taskId}' \
--header 'apiKey: {apiKey}' \
--header 'section: {section}' \
--header 'Accept: */*' \
--header 'Host: a1.art' \
--header 'Connection: keep-alive'
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://a1.art/open-api/v1/a1/tasks/{taskId}"
payload={}
headers = {
'apiKey': {apiKey},
'section': {section}
}
response = requests.request("GET", url, headers=headers, data=payload)
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
var axios = require('axios');
var config = {
method: 'get',
url: 'https://a1.art/open-api/v1/a1/tasks/{taskId}',
headers: {
'apiKey': {apiKey},
'section': {section},
'Accept': '*/*',
'Host': 'a1.art',
'Connection': 'keep-alive'
}
};
axios(config)
.then(function (response) {
console.log(JSON.stringify(response.data));
})
.catch(function (error) {
console.log(error);
});
```
{% endtab %}
{% endtabs %}
**响应示例**
```javascript
{
"code": 0,
"msg": "success",
"msg_cn": "成功",
"data": {
"id": "1803970662304264194",
"state": 10,
"startDate": "2024-06-21 09:58:16.0",
"finishDate": "2024-06-21 09:58:28.0",
"createDate": "2024-06-21 09:58:16.0",
"images": [
"imageUrl"
]
}
}
```
## 错误码
| **code** | **msg** | **msg\_cn** |
| -------- | -------------------------------------------------------------------------------- | ----------------------- |
| 0 | success | 成功 |
| 10001 | invalid params | 无效的参数 |
| 10002 | unsupported image suffix | 不支持的文件后缀 |
| 10410 | Missing API key | 缺少API key |
| 10411 | Invalid API key | 无效的API key |
| 20000 | too may request | 接口访问触发限流 |
| 20002 | server error | 服务器错误 |
| 20003 | service internal error | 服务内部错误 |
| 20100 | file error | 文件异常 |
| 20101 | file suffix error | 文件后缀异常 |
| 324010 | This app does not support API access | 此应用不支持通过API访问 |
| 324011 | The quantity must not exceed 4 | 单个应用单次请求生图数量1～4张 |
| 324012 | This app does not exist | 无效的应用ID |
| 324013 | The application is updated. You need to obtain the application information again | 应用版本已更新，请重新获取应用信息 |
| 324018 | You can only use API of your built apps. | 调用他人的未发布应用api |
| 400000 | Missing image file | 缺少图片文件 |
| 400001 | Only one image can be uploaded at a time | 一次只支持上传一张图片 |
| 400002 | Non image format files are not supported | 不支持非图片格式文件 |
| 400003 | The image file cannot exceed 10M | 图片文件不能超过10M |
| 400004 | Invalid file | 无效的文件 |
| 400005 | This image format is not supported | 不支持该图片格式 |
| 400006 | The size of the image file cannot exceed 2048\*2048 | 图片文件尺寸不能超过 2048\*2048 |
| 324019 | No rights to use VIP app\*Available after payment | 没有使用 vip app 的权益\*付费后可用 |
| 810012 | balance insufficient error | 账户余额不足 |
## 联系我们
使用微信扫码加入Open API 开发者交流群