# English Version
## Introduction
{% hint style="success" %}
Welcome to join A1's developer platform and explore the infinite possibilities of AIGC together!
{% endhint %}
a1.art is committed to providing a variety of image/video generation apps to help developers easily integrate and use image/video generation technology to meet different business needs.
The a1.art platform has launched over 45,000+ image and video generation applications, including popular features such as video face swapping, anime avatars, 3D cartoon characters, and Ghibli-style illustrations. It also offers uniquely styled AI portrait applications like action figure doll-style designs, couple photo templates, and atmospheric photo shoots, as well as a vast collection of creative emojis and artistic fonts. Simply input an image or a phrase to generate stunning images or video content in a variety of styles. Waiting for you to explore!
By calling our API, you can quickly integrate the photo app into your application or service, enhancing User Experience and product value.
Our platform features include:
* **Diversified image/video generation applications** : Provide a variety of image generation applications to meet the needs of different scenarios.
* **Easy integration** : Integrate powerful image/video generation capabilities into your project with a simple API call.
* **Efficient performance** : Optimized algorithms and server architecture ensure fast response and high-quality image/video output.
* **Flexible customization** : supports multiple parameter settings to meet personalized image generation needs.
Whether you want to provide personalized image/video generation services for your users or need to automatically generate images in internal systems, our platform can provide powerful support for you.
## API Charging Rules
The API interface will generate watermark-free images for you, so that you can use the images/videos in your personal business. There are two types of image generation applications on the a1.art site: node apps and form apps.
* Call the API of the APP to generate images. The form application consumes 1 credit for each generated image. The node-type application deducts credits according to the number of nodes. The fine-drawn image consumes 3 credits for each generated image. For details, please refer to: [节点式应用 VS 表单式应用 | Node Filters VS Form Filters](https://fyze31atzb.feishu.cn/docx/H2aKdptrHotppqx3N7GcmV7Vnob#NgMRdGtW1ot3UWxGqU2ckSLLnCg)
* Call the image-to-video API to generate videos, and 10 credits are consumed for each video generated.
You can subscribe to a1.art through a Visa card to obtain points, or contact us directly to discuss setting up a custom plan.
{% hint style="danger" %}
Please pay attention to keeping the account balance sufficient to avoid call failure affecting the normal use of your business
{% endhint %}
For more subscription-related content, [please refer to](https://a1.art/ai-image-generator-api)
## What capabilities does the API provide?
API currently provides 5 interfaces:
1. **Get APP information:** APP information can be browsed through the web application details page - API pop-up window, or obtained through the API interface to understand the basic information and imported parameters of the APP.\
2. **Upload image interface** : if the user is using the image generation function, you need to call this interface to upload images before you can get the parameters of the image generation dependency
3. **Image/Video Generation Interface:** Users input the parameters on which the image/video generation depends, and can obtain a taskId. Through the taskId, the generated image/video results can be queried.
4. **Fine drawing interface:** high definition processing of the incoming image, similar to the raw image interface, after obtaining the taskId, the raw image result can be queried through the taskId
5. **Query raw graph result interface:** pass in the taskId can query the raw graph result
## Basic introduction
### Access authorization
#### Prefix
`https://a1.art`
Note: If you encounter problems with registration in China, you can try using the domain name `https://a1art.xiaopiu.com`
#### Request specification
* Network protocol: `HTTPS`protocol.
* Encoding format: `UTF-8`encoding.
* Request header: You must carry `apiKey` for background authentication and authentication. [(Get API key)](https://a1.art/?open=apikey)
* Response result: `JSON` data format. The response body structure of the API includes four parts: `code, msg, msg_cn, and data`. `Code` is the error code, `msg` is the English error description, `msg_cn` is the Chinese error description, and `data` is the result returned after calling the API; if the `code` is not `0` , the request is considered to have failed, and the failure information can refer to `msg` and `msg_cn` .
#### **Response body**
| **Parameter name** | **Type** | **Description** |
| ------------------ | -------- | --------------------- |
| code | int | Error code |
| msg | string | English Error Message |
| msg\_cn | string | Chinese Error Message |
| data | json | Response data |
### Data structure
#### Application
```javascript
export type APPInfo = {
id: string;
versionId: string;
name: string;
formArr: []Form;
styleArr: []Style;
updateDate: Date;
createDate: Date;
processTime: string;
};
```
#### Form
```javascript
// Type of the type field in the formCorresponding style, pictures, text, size
export type FormItemTypeFieldType = 'style' | 'cnet' | 'description' | 'size' ;
export type Form = {
id: string; // The id that needs to be passed for the image generation interface (except for descriptions with inputs).
type: FormItemTypeFieldType;
title: string;
inputs: []Input;
position: string; // Location of the group photo
};
```
#### Input
```javascript
export type Input = {
id: string; // The id that needs to be passed in the description form of the image generation interface
title: string;
tags: []string; // description form prompt
};
```
#### Style
```javascript
export type Style = {
id: string;
name: string;
image: string;
};
```
#### Size
```javascript
// Types of sizeId field in form: 1-7 pairs corresponding to 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 execution status, 0 - task has been submitted, 10 - task has been completed, 20 - task failed, 30 - task in progress.
export type TaskStateType = 0 ｜10 | 20 | 30 ;
export type Task = {
id: string;
startDate: Date;
finishDate: Date;
createDate: Date;
images: []string;
state: number;
};
```
### `API key`
To issue an authorization request as a user, you must use the API key. After logging in to a1, click API Manage to find and manage your API key
 
### `Application`
#### Get Application Details
`/open-api/v1/a1/apps/{appId}`& GET
**Request Parameters**
| Field Name | Type | Location | Is Mandatory | Meaning |
| ---------- | ------ | -------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| apiKey | string | header | Yes | API key |
| appId | string | path | Yes | Application ID |
| language | string | query | No | Language, if not transmitted, it is assumed to be the text used when publishing. Supported translations include 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 |
**Parameter limit**
* It does not support querying apps with digital avatar components, wordart components, group photo components in user upload mode (most group photo apps are not included in this scope), and video components
* It does not support querying unpublished node app information
{% 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 %}
**Response example**
```javascript
{
"code": 0,
"msg": "success",
"msg_cn": "成功",
"data": {
"appInfo": {
"id": "1803632078862147586",
"versionId": "1803632078866341890",
"name": "Crazy Pet",
"formArr": [ // Form parameters for raw images to be uploaded
{
"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", // The average time it takes to generate images in this app recently
"cost": 2 // Node app consumption credits
}
}
}
```
### `Image`
#### Upload images：`/open-api/v1/a1/images/upload`& POST
Note: Only images uploaded through our system can be used as raw image parameters.
**Request Parameters**
| Field Name | Type | Location | Is Mandatory | Meaning |
| ---------- | ------ | --------- | ------------ | ---------- |
| apiKey | string | header | yes | API key |
| file | file | form-data | yes | Image file |
| imageUrl | string | form-data | yes | Image Link |
**Parameter limit**
* Only png, jpg and jpeg image files can be uploaded.
* Only images can be uploaded through form forms.
* Support uploading pictures via online picture links
* Only one image can be uploaded at a time
* Image file size cannot be greater than 10 MB
**Request example**
{% tabs %}
{% tab title="Curl" %}
```
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" %}
```
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" %}
```java
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);
});java
```
{% endtab %}
{% endtabs %}
**Response example**
```javascript
{
"code": 0,
"msg": "success",
"msg_cn": "成功",
"data": {
"imageUrl": "63fa41e7-e282-4582-a07b-8e5e73e8d388.jpg",
"path": "assets/application/apikey_5f6ccf7b983e499fb8ba4e5c4de8013f/form/"
}
}
```
#### Generate images/videos
`/open-api/v1/a1/images/generate`**& POST**
> Note:
>
> 1. Node-based applications have separate credit consumption rules. For details, please refer to [节点式应用 VS 表单式应用](https://fyze31atzb.feishu.cn/docx/H2aKdptrHotppqx3N7GcmV7Vnob)
> 2. Generating one video consumes 10 credits.
**Request Parameters**
| Field Name | Type | Location | Is Mandatory | Meaning |
| ----------------------------------------------- | ------------------ | -------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| apiKey | string | header | Yes | API key |
| appId | string | body | Yes | Application id |
| versionId | string | body | Yes | Application version id |
| generateNum | string | body | Yes | Number of images to be generated in this request |
| cnet | \[]cnetForm | body | No | \| Pictures relied on for Image-to-image \| |
| [cnetForm.id](http://cnetform.id) | string | body | Yes | id of the form of type cnet in formArr |
| cnetForm.imageUrl | string | body | Yes | See the return value of the upload image interface |
| cnetForm.path | string | body | Yes | See the return value of the upload image interface |
| cnetForm.position | string | body | No | Group photo image index position (this field must be passed when using the group photo function, indicating that the image will be attached to the specified position of the group photo - the index starts from 0) |
| description | \[]descriptionForm | body | No | Descriptors relying on real-life photos |
| [descriptionForm.id](http://descriptionform.id) | string | body | Yes | id of the form of type description in formArr (if there is an input field, it is the id of the input) |
| descriptionForm.value | string | body | Yes | Description words |
| styleId | string | body | No | The image style of the raw image depends on the source - the id in styleArr. |
| size | sizeForm | body | No | Original image size dependencies |
| sizeForm.sizeId | string | body | Yes | 1 to 7 pairs corresponding to size 1:1 3:4 1:2 4:3 2:1 16:9 9:16 |
**Parameter limit**
* You need to bring the latest versionId of the application.
* Currently, generating images with unpublished node-based applications and video face swapping applications are not supported.
* Images stored in this system must be used
* Number of images/videos to be generated (generateNum=1) Note: Node-based applications can only generate one image/video at a time
* For the parameters in application formArr, pass at least one parameter for each type
* When passing a parameter of type description in the form, if the form has an inputs field, the id of the description should be passed as the id of the input
**Request example**
{% 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}, # If the form does not have an inputs field, pass the description id instead of the 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}, # If the form does not have an inputs field, pass the description id instead of the 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}, // If the form does not have an inputs field, pass the description id instead of the 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 %}
**Response example**
```javascript
{
"code": 0,
"msg": "success",
"msg_cn": "成功",
"data": {
"taskId": "507b080cfe17f7956e8690c4eba2b80f"
}
}
```
#### **Enchance Image：/open-api/v1/a1/images/optimize& POST**
1. **Request Parameters**
| Field Name | Type | Location | Is Mandatory | Meaning |
| ---------- | ------ | -------- | ------------ | --------------------------------------------- |
| apiKey | string | header | Yes | API key |
| path | string | body | Yes | See the return value of the upload image API. |
| imageUrl | string | body | Yes | See the return value of the upload image API. |
2. **Parameter limit**
* You must use images stored in this system
* Each image drawing consumes 3 points
* The size limit of the drawing image is 2048 \* 2048
3. **Request example**
{% 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. **Response example**
> The response structure is the same as the generated image
```sh
{
"code": 0,
"msg": "success",
"msg_cn": "成功",
"data": {
"taskId": "507b080cfe17f7956e8690c4eba2b80f"
}
}
```
### `Task`
`/open-api/v1/a1/tasks/{taskId}`**& GET**
> Note: The generated image address may become invalid later. It is recommended to save the generated result on your own CDN.
Note：
1. You can wait for 5 seconds and then query the result through polling
2. The state enum of task can be seen in TaskStateType
#### Query task execution results
**Request Parameters**
| Field Name | Type | Location | Is Mandatory | Meaning |
| ---------- | ------ | -------- | ------------ | -------------------------------------------------------------------------------------------------------------- |
| apiKey | string | header | Yes | API key |
| section | string | header | No | The region to which the image resource belongs. For China, please use cn. Other regions do not need to use cn. |
| taskId | string | path | Yes | taskId returned by the generate image interface |
**Parameter limit**
* Only query tasks under the current user ID
**Request example**
{% 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 %}
**Response example**
```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"
]
}
}
```
## Error code
| **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 | 账户余额不足 |
## Contact us
* Join our Discord community to communicate with our team and get quick assistance with your issues.
* For any questions, send us an email at [**contact@A1.art**](mailto:contact@A1.art), and we will respond within 2 business days.
* Follow our X account: [**@A1.art**](https://twitter.com/A1art280841)
