# Background Change
Source: https://docstest.akool.io/ai-tools-suite/background-change
The resources (image, video, voice) generated by our API are valid for 7 days. Please save the relevant resources as soon as possible to prevent expiration.
### Background Change
```
POST https://openapi.akool.com/api/open/v3/content/image/bg/replace
```
**Request Headers**
| **Parameter** | **Value** | **Description** |
| ------------- | ------------ | ------------------------------------------- |
| Authorization | Bearer token | Your API Key used for request authorization |
**Body Attributes**
| **Parameter** | **isRequired** | **Type** | **Value** | **Description** |
| ------------------------- | -------------- | -------- | ----------------------------- | --------------------------------------------------------------------------- |
| color\_code | false | String | eg: #aafbe3 | background color。 Use hexadecimal to represent colors |
| template\_url | false | String | | resource address of the background image |
| origin\_img | true | String | | Foreground image address |
| modify\_template\_size | false | String | eg:"3031x3372" | The size of the template image after expansion |
| modify\_origin\_img\_size | true | String | eg: "3031x2894" | The size of the foreground image after scaling |
| overlay\_origin\_x | true | int | eg: 205 | The position of the upper left corner of the foreground image in the canvas |
| overlay\_origin\_y | true | int | eg: 497 | The position of the upper left corner of the foreground image in the canvas |
| overlay\_template\_x | false | int | eg: 10 | The position of the upper left corner of the template image in the canvas |
| overlay\_template\_y | false | int | eg: 497 | The position of the upper left corner of the template image in the canvas |
| canvas\_size | true | String | eg:"3840x3840" | Canvas size |
| webhookUrl | true | String | | Callback url address based on HTTP request |
| removeBg | false | Boolean | true or false default false | Whether to remove the background image |
In addition to using the required parameters,you can also use one or both of the color\_code or template\_url parameters(but this is not required). Once you use template\_url, you can carry three additional parameters: modify\_template\_size, overlay\_template\_x, and overlay\_template\_y.
**Response Attributes**
| **Parameter** | **Type** | **Value** | **Description** |
| ------------- | -------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------ |
| code | int | 1000 | Interface returns business status code(1000:success) |
| msg | String | | Interface returns status information |
| data | Object | `{ _id: "", image_status: 1 }` | \_id: Interface returns data, image\_status: the status of image: 【1:queueing, 2:processing, 3:completed,4:failed】 |
**Example**
**Body**
You have 4 combination parameters to choose from
The first combination of parameters: use template\_url
```json
{
"canvas_size": "3840x3840",
"template_url": "https://s3-alpha-sig.figma.com/img/dd86/048d/a2f66b5440ca0097162432cc5d420f31?Expires=1712534400&Key-Pair-Id=APKAQ4GOSFWCVNEHN3O4&Signature=YfFEN1MK9UZvh5CX8ne6OOPWLW4mMYU7x8jm7CyCtD5XyEmz-nsuzuLE2TdfYNXtt6vF3TLmyRbECkpAKzEnnpR8LMNgT7w2v-qn~QwnJAjAhmBhBwZ95eUEQ1IPxpX~8Gp8U3aUOYHla3mwWEULlSpFgcei6HffDZh2oIC6prKzH8rWB4JuUcpUvKw7Lq~kUfeEZ8Em-l3DvgQYzrKIuAAvoPKiYOeqIcmUs9Ba1d9wAFbjJXxHqo9xxJENMLtXIOqjGbcZLV9DWpk-fZnQAhC-ikrqoEpU~zA64aqcGYE0pv~LmV7LrCrugBcujQFBvdZqgdoV8po4HBH1Io~TkQ__",
"modify_template_size": "3830x3830",
"overlay_template_x": 5,
"overlay_template_y": 5,
"origin_img": "https://drz0f01yeq1cx.cloudfront.net/1711939252580-7e40bd1a-e480-42ed-8585-3f9ffccf6bdb-5822.png",
"modify_origin_img_size": "3830x2145",
"overlay_origin_x": 5,
"overlay_origin_y": 849
}
```
The second combination of parameters:use color\_code
```json
{
"color_code": "#c9aafb",
"canvas_size": "3840x3840",
"origin_img": "https://drz0f01yeq1cx.cloudfront.net/1712132369637-69a946c0-b2a7-4fe6-92c8-2729b36cc13e-0183.png",
"modify_origin_img_size": "3060x3824",
"overlay_origin_x": 388,
"overlay_origin_y": 8
}
```
The third combination of parameters: use template\_url and color\_code
```json
{
"color_code": "#aafbe3",
"canvas_size": "3840x3840",
"template_url": "https://s3-alpha-sig.figma.com/img/dd86/048d/a2f66b5440ca0097162432cc5d420f31?Expires=1712534400&Key-Pair-Id=APKAQ4GOSFWCVNEHN3O4&Signature=YfFEN1MK9UZvh5CX8ne6OOPWLW4mMYU7x8jm7CyCtD5XyEmz-nsuzuLE2TdfYNXtt6vF3TLmyRbECkpAKzEnnpR8LMNgT7w2v-qn~QwnJAjAhmBhBwZ95eUEQ1IPxpX~8Gp8U3aUOYHla3mwWEULlSpFgcei6HffDZh2oIC6prKzH8rWB4JuUcpUvKw7Lq~kUfeEZ8Em-l3DvgQYzrKIuAAvoPKiYOeqIcmUs9Ba1d9wAFbjJXxHqo9xxJENMLtXIOqjGbcZLV9DWpk-fZnQAhC-ikrqoEpU~zA64aqcGYE0pv~LmV7LrCrugBcujQFBvdZqgdoV8po4HBH1Io~TkQ__",
"modify_template_size": "3828x3828",
"overlay_template_x": 2049,
"overlay_template_y": -6,
"origin_img": "https://drz0f01yeq1cx.cloudfront.net/1712132369637-69a946c0-b2a7-4fe6-92c8-2729b36cc13e-0183.png",
"modify_origin_img_size": "3062x3828",
"overlay_origin_x": -72,
"overlay_origin_y": -84
}
```
The fourth combination of parameters:
```json
{
"canvas_size": "3840x3840",
"origin_img": "https://drz0f01yeq1cx.cloudfront.net/1712132369637-69a946c0-b2a7-4fe6-92c8-2729b36cc13e-0183.png",
"modify_origin_img_size": "3060x3824",
"overlay_origin_x": 388,
"overlay_origin_y": 8
}
```
**Request**
```bash cURL
curl --location 'https://openapi.akool.com/api/open/v3/content/image/bg/replace' \
--header 'Authorization: Bearer token' \
--header 'Content-Type: application/json' \
--data '{
"canvas_size": "3840x3840",
"template_url": "https://s3-alpha-sig.figma.com/img/dd86/048d/a2f66b5440ca0097162432cc5d420f31?Expires=1712534400&Key-Pair-Id=APKAQ4GOSFWCVNEHN3O4&Signature=YfFEN1MK9UZvh5CX8ne6OOPWLW4mMYU7x8jm7CyCtD5XyEmz-nsuzuLE2TdfYNXtt6vF3TLmyRbECkpAKzEnnpR8LMNgT7w2v-qn~QwnJAjAhmBhBwZ95eUEQ1IPxpX~8Gp8U3aUOYHla3mwWEULlSpFgcei6HffDZh2oIC6prKzH8rWB4JuUcpUvKw7Lq~kUfeEZ8Em-l3DvgQYzrKIuAAvoPKiYOeqIcmUs9Ba1d9wAFbjJXxHqo9xxJENMLtXIOqjGbcZLV9DWpk-fZnQAhC-ikrqoEpU~zA64aqcGYE0pv~LmV7LrCrugBcujQFBvdZqgdoV8po4HBH1Io~TkQ__",
"modify_template_size": "3830x3830",
"overlay_template_x": 5,
"overlay_template_y": 5,
"origin_img": "https://drz0f01yeq1cx.cloudfront.net/1711939252580-7e40bd1a-e480-42ed-8585-3f9ffccf6bdb-5822.png",
"modify_origin_img_size": "3830x2145",
"overlay_origin_x": 5,
"overlay_origin_y": 849
}
'
```
```java Java
OkHttpClient client = new OkHttpClient().newBuilder()
.build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n \"canvas_size\": \"3840x3840\",\n \"template_url\": \"https://s3-alpha-sig.figma.com/img/dd86/048d/a2f66b5440ca0097162432cc5d420f31?Expires=1712534400&Key-Pair-Id=APKAQ4GOSFWCVNEHN3O4&Signature=YfFEN1MK9UZvh5CX8ne6OOPWLW4mMYU7x8jm7CyCtD5XyEmz-nsuzuLE2TdfYNXtt6vF3TLmyRbECkpAKzEnnpR8LMNgT7w2v-qn~QwnJAjAhmBhBwZ95eUEQ1IPxpX~8Gp8U3aUOYHla3mwWEULlSpFgcei6HffDZh2oIC6prKzH8rWB4JuUcpUvKw7Lq~kUfeEZ8Em-l3DvgQYzrKIuAAvoPKiYOeqIcmUs9Ba1d9wAFbjJXxHqo9xxJENMLtXIOqjGbcZLV9DWpk-fZnQAhC-ikrqoEpU~zA64aqcGYE0pv~LmV7LrCrugBcujQFBvdZqgdoV8po4HBH1Io~TkQ__\",\n \"modify_template_size\": \"3830x3830\",\n \"overlay_template_x\": 5,\n \"overlay_template_y\": 5,\n \"origin_img\": \"https://drz0f01yeq1cx.cloudfront.net/1711939252580-7e40bd1a-e480-42ed-8585-3f9ffccf6bdb-5822.png\",\n \"modify_origin_img_size\": \"3830x2145\",\n \"overlay_origin_x\": 5,\n \"overlay_origin_y\": 849,\n}");
Request request = new Request.Builder()
.url("https://contentapi.akool.com/api/v3/content/image/bg/replace")
.method("POST", body)
.addHeader("authorization", "Bearer token")
.addHeader("content-type", "application/json")
.build();
Response response = client.newCall(request).execute();
```
```javascript Javascript
const myHeaders = new Headers();
myHeaders.append("Authorization", "Bearer token");
myHeaders.append("Content-Type", "application/json");
const raw = JSON.stringify({
"canvas_size": "3840x3840",
"template_url": "https://s3-alpha-sig.figma.com/img/dd86/048d/a2f66b5440ca0097162432cc5d420f31?Expires=1712534400&Key-Pair-Id=APKAQ4GOSFWCVNEHN3O4&Signature=YfFEN1MK9UZvh5CX8ne6OOPWLW4mMYU7x8jm7CyCtD5XyEmz-nsuzuLE2TdfYNXtt6vF3TLmyRbECkpAKzEnnpR8LMNgT7w2v-qn~QwnJAjAhmBhBwZ95eUEQ1IPxpX~8Gp8U3aUOYHla3mwWEULlSpFgcei6HffDZh2oIC6prKzH8rWB4JuUcpUvKw7Lq~kUfeEZ8Em-l3DvgQYzrKIuAAvoPKiYOeqIcmUs9Ba1d9wAFbjJXxHqo9xxJENMLtXIOqjGbcZLV9DWpk-fZnQAhC-ikrqoEpU~zA64aqcGYE0pv~LmV7LrCrugBcujQFBvdZqgdoV8po4HBH1Io~TkQ__",
"modify_template_size": "3830x3830",
"overlay_template_x": 5,
"overlay_template_y": 5,
"origin_img": "https://drz0f01yeq1cx.cloudfront.net/1711939252580-7e40bd1a-e480-42ed-8585-3f9ffccf6bdb-5822.png",
"modify_origin_img_size": "3830x2145",
"overlay_origin_x": 5,
"overlay_origin_y": 849
});
const requestOptions = {
method: "POST",
headers: myHeaders,
body: raw,
redirect: "follow"
};
fetch("https://openapi.akool.com/api/open/v3/content/image/bg/replace", requestOptions)
.then((response) => response.text())
.then((result) => console.log(result))
.catch((error) => console.error(error));
```
```php PHP
'Bearer token',
'Content-Type' => 'application/json'
];
$body = '{
"canvas_size": "3840x3840",
"template_url": "https://s3-alpha-sig.figma.com/img/dd86/048d/a2f66b5440ca0097162432cc5d420f31?Expires=1712534400&Key-Pair-Id=APKAQ4GOSFWCVNEHN3O4&Signature=YfFEN1MK9UZvh5CX8ne6OOPWLW4mMYU7x8jm7CyCtD5XyEmz-nsuzuLE2TdfYNXtt6vF3TLmyRbECkpAKzEnnpR8LMNgT7w2v-qn~QwnJAjAhmBhBwZ95eUEQ1IPxpX~8Gp8U3aUOYHla3mwWEULlSpFgcei6HffDZh2oIC6prKzH8rWB4JuUcpUvKw7Lq~kUfeEZ8Em-l3DvgQYzrKIuAAvoPKiYOeqIcmUs9Ba1d9wAFbjJXxHqo9xxJENMLtXIOqjGbcZLV9DWpk-fZnQAhC-ikrqoEpU~zA64aqcGYE0pv~LmV7LrCrugBcujQFBvdZqgdoV8po4HBH1Io~TkQ__",
"modify_template_size": "3830x3830",
"overlay_template_x": 5,
"overlay_template_y": 5,
"origin_img": "https://drz0f01yeq1cx.cloudfront.net/1711939252580-7e40bd1a-e480-42ed-8585-3f9ffccf6bdb-5822.png",
"modify_origin_img_size": "3830x2145",
"overlay_origin_x": 5,
"overlay_origin_y": 849
}';
$request = new Request('POST', 'https://openapi.akool.com/api/open/v3/content/image/bg/replace', $headers, $body);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();
```
```python Python
import requests
import json
url = "https://openapi.akool.com/api/open/v3/content/image/bg/replace"
payload = json.dumps({
"canvas_size": "3840x3840",
"template_url": "https://s3-alpha-sig.figma.com/img/dd86/048d/a2f66b5440ca0097162432cc5d420f31?Expires=1712534400&Key-Pair-Id=APKAQ4GOSFWCVNEHN3O4&Signature=YfFEN1MK9UZvh5CX8ne6OOPWLW4mMYU7x8jm7CyCtD5XyEmz-nsuzuLE2TdfYNXtt6vF3TLmyRbECkpAKzEnnpR8LMNgT7w2v-qn~QwnJAjAhmBhBwZ95eUEQ1IPxpX~8Gp8U3aUOYHla3mwWEULlSpFgcei6HffDZh2oIC6prKzH8rWB4JuUcpUvKw7Lq~kUfeEZ8Em-l3DvgQYzrKIuAAvoPKiYOeqIcmUs9Ba1d9wAFbjJXxHqo9xxJENMLtXIOqjGbcZLV9DWpk-fZnQAhC-ikrqoEpU~zA64aqcGYE0pv~LmV7LrCrugBcujQFBvdZqgdoV8po4HBH1Io~TkQ__",
"modify_template_size": "3830x3830",
"overlay_template_x": 5,
"overlay_template_y": 5,
"origin_img": "https://drz0f01yeq1cx.cloudfront.net/1711939252580-7e40bd1a-e480-42ed-8585-3f9ffccf6bdb-5822.png",
"modify_origin_img_size": "3830x2145",
"overlay_origin_x": 5,
"overlay_origin_y": 849
})
headers = {
'Authorization': 'Bearer token',
'Content-Type': 'application/json'
}
response = requests.request("POST", url, headers=headers, data=payload)
print(response.text)
```
**Response**
```json
{
"code": 1000,
"msg": "OK",
"data": {
"create_time": 1712133151184,
"uid": 1432101,
"type": 3,
"faceswap_quality": 2,
"image_id": "c7ed5294-6783-481e-af77-61a850cd19c7",
"image_sub_status": 1,
"image_status": 1, // the status of image： 【1:queueing, 2:processing,3:completed, 4:failed】
"deduction_credit": 4,
"buttons": [],
"used_buttons": [],
"upscaled_urls": [],
"error_reasons": [],
"_id": "660d15b83ec46e810ca642f5",
"__v": 0
}
}
```
### Get Image Result image info
```
GET https://openapi.akool.com/api/open/v3/content/image/infobymodelid?image_model_id=660d15b83ec46e810ca642f5
```
**Request Headers**
| **Parameter** | **Value** | **Description** |
| ------------- | ------------ | ------------------------------------------- |
| Authorization | Bearer token | Your API Key used for request authorization |
**Query Attributes**
| **Parameter** | **Type** | **Value** | **Description** |
| ---------------- | -------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| image\_model\_id | String | | image db id：You can get it based on the `_id` field returned by [https://openapi.akool.com/api/open/v3/content/image/createbyimagine](https://openapi.akool.com/api/open/v3/content/image/createbyimagine) api. |
**Response Attributes**
| **Parameter** | **Type** | **Value** | **Description** |
| ------------- | -------- | ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| code | int | 1000 | Interface returns business status code(1000:success) |
| msg | String | | Interface returns status information |
| data | Object | `{image_status:1,_id:"",image:""}` | image\_status: the status of image： 【1:queueing, 2:processing, 3:completed, 4:failed】 image: Image result after processing \_id: Interface returns data |
**Example**
**Request**
```bash cURL
curl --location 'https://openapi.akool.com/api/open/v3/content/image/infobymodelid?image_model_id=660d15b83ec46e810ca642f5' \
--header 'Authorization: Bearer token'
```
```java Java
OkHttpClient client = new OkHttpClient().newBuilder()
.build();
MediaType mediaType = MediaType.parse("text/plain");
RequestBody body = RequestBody.create(mediaType, "");
Request request = new Request.Builder()
.url("https://openapi.akool.com/api/open/v3/content/image/infobymodelid?image_model_id=660d15b83ec46e810ca642f5")
.method("GET", body)
.addHeader("Authorization", "Bearer token")
.build();
Response response = client.newCall(request).execute();
```
```js Javascript
const myHeaders = new Headers();
myHeaders.append("Authorization", "Bearer token");
const requestOptions = {
method: "GET",
headers: myHeaders,
redirect: "follow"
};
fetch("https://openapi.akool.com/api/open/v3/content/image/infobymodelid?image_model_id=660d15b83ec46e810ca642f5", requestOptions)
.then((response) => response.text())
.then((result) => console.log(result))
.catch((error) => console.error(error));
```
```php PHP
'Bearer token'
];
$request = new Request('GET', 'https://openapi.akool.com/api/open/v3/content/image/infobymodelid?image_model_id=660d15b83ec46e810ca642f5', $headers);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();
```
```python Python
import requests
url = "https://openapi.akool.com/api/open/v3/content/image/infobymodelid?image_model_id=660d15b83ec46e810ca642f5"
payload = {}
headers = {
'Authorization': 'Bearer token'
}
response = requests.request("GET", url, headers=headers, data=payload)
print(response.text)
```
**Response**
```json
{
"code": 1000,
"msg": "OK",
"data": {
"_id": "660d15b83ec46e810ca642f5",
"create_time": 1712133560525,
"uid": 1486241,
"type": 3,
"faceswap_quality": 2,
"image_id": "e23018b5-b7a9-4981-a2ff-b20559f9b2cd",
"image_sub_status": 3,
"image_status": 3, // the status of image：【1：queueing， 2：processing，3：completed，4：failed】
"deduction_credit": 4,
"buttons": [],
"used_buttons": [],
"upscaled_urls": [],
"error_reasons": [],
"__v": 0,
"external_img": "https://drz0f01yeq1cx.cloudfront.net/1712133563402-result.png",
"image": "https://drz0f01yeq1cx.cloudfront.net/1712133564746-d4a80a20-9612-4f59-958b-db9dec09b320-9409.png" // Image result after processing
}
}
```
**Response Code Description**
Please note that if the value of the response code is not equal to 1000, the request is failed or wrong
| **Parameter** | **Value** | **Description** |
| ------------- | --------- | --------------------------------------------------------------------- |
| code | 1000 | Success |
| code | 1003 | Parameter error or Parameter can not be empty |
| code | 1005 | Operation is too frequent |
| code | 1006 | Your quota is not enough |
| code | 1007 | The number of people who can have their faces changed cannot exceed 8 |
| code | 1101 | Invalid authorization or The request token has expired |
| code | 1102 | Authorization cannot be empty |
| code | 1200 | The account has been banned |
# Face Swap
Source: https://docstest.akool.io/ai-tools-suite/faceswap
The resources (image, video, voice) generated by our API are valid for 7 days. Please save the relevant resources as soon as possible to prevent expiration.
Experience our face swap technology in action by exploring our interactive demo on GitHub: [AKool Face Swap Demo](https://github.com/AKOOL-Official/akool-face-swap-demo).
### Image Faceswap
```bash
POST https://openapi.akool.com/api/open/v3/faceswap/highquality/specifyimage
```
**Request Headers**
| **Parameter** | **Value** | **Description** |
| ------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------- |
| Authorization | Bearer `{token}` | Your API Key used for request authorization.[getToken](https://docs.akool.com/authentication/usage#get-the-token) |
**Body Attributes**
| **Parameter** | **Type** | **Value** | **Description** |
| ------------- | -------- | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| targetImage | Array | `[{path:"",opts:""}]` | A collection of faces in the original image(Each array element is an object, and the object contains 2 properties, path:Links to faces detected in the original image.opts: Key information of faces detected in original pictures(You can get it through the face [https://sg3.akool.com/detect](https://docs.akool.com/ai-tools-suite/faceswap#face-detect) API,You can get the landmarks\_str value returned by the api interface as the value of opts) |
| sourceImage | Array | `[{path:"",opts:""}]` | Replacement target image information.(Each array element is an object, and the object contains 2 properties, path:Links to faces detected in target images.opts: Key information of the face detected in the target image(You can get it through the face [https://sg3.akool.com/detect](https://docs.akool.com/ai-tools-suite/faceswap#face-detect) API,You can get the landmarks\_str value returned by the api interface as the value of opts) |
| face\_enhance | Int | 0 or 1 | Whether facial enhancement: 1 means open， 0 means close |
| modifyImage | String | | Modify the link address of the image |
| webhookUrl | String | | Callback url address based on HTTP request |
**Response Attributes**
| Parameter | Type | Value | Description |
| --------- | ------ | ----------------------------- | ----------------------------------------------------------------------------------------- |
| code | int | 1000 | Interface returns business status code(1000: success) |
| msg | String | | Interface returns status information |
| data | Object | `{_id:"",url: "",job_id: ""}` | \_id: Interface returns data url: faceswwap result url job\_id: Task processing unique id |
**Example**
**Body**
```json
{
"targetImage": [ // A collection of faces in the original image
{
"path": "https://d21ksh0k4smeql.cloudfront.net/crop_1694593694387-4562-0-1694593694575-0526.png", // Links to faces detected in the original image
"opts": "262,175:363,175:313,215:272,279" // Key information of faces detected in original pictures【You can get it through the face https://sg3.akool.com/detect API,You can get the landmarks_str value returned by the api interface as the value of opts
}
],
"sourceImage": [ // Replacement target image information
{
"path": "https://d21ksh0k4smeql.cloudfront.net/crop_1705462509874-9254-0-1705462510015-9261.png", // Links to faces detected in target images
"opts": "239,364:386,366:317,472:266,539" // Key information of the face detected in the target image【You can get it through the face https://sg3.akool.com/detect API,You can get the landmarks_str value returned by the api interface as the value of opts
}
],
"face_enhance": 0, // Whether facial enhancement: 1 means open， 0 means close
"modifyImage": "https://d21ksh0k4smeql.cloudfront.net/bdd1c994c4cd7a58926088ae8a479168-1705462506461-1966.jpeg", // Modify the link address of the image
"webhookUrl":"" // Callback url address based on HTTP request
}
```
**Request**
```bash cURL
curl -X POST --location "https://openapi.akool.com/api/open/v3/faceswap/highquality/specifyimage" \
-H "Authorization: Bearer token" \
-H "Content-Type: application/json" \
-d '{
"sourceImage": [
{
"path": "https://d21ksh0k4smeql.cloudfront.net/crop_1694593694387-4562-0-1694593694575-0526.png",
"opts": "262,175:363,175:313,215:272,279"
}
],
"targetImage": [
{
"path": "https://d21ksh0k4smeql.cloudfront.net/crop_1705462509874-9254-0-1705462510015-9261.png",
"opts": "239,364:386,366:317,472:266,539"
}
],
"face_enhance": 0,
"modifyImage": "https://d21ksh0k4smeql.cloudfront.net/bdd1c994c4cd7a58926088ae8a479168-1705462506461-1966.jpeg",
"webhookUrl": ""
}'
```
```java Java
OkHttpClient client = new OkHttpClient().newBuilder()
.build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n \"sourceImage\": [ \n {\n \"path\": \"https://d21ksh0k4smeql.cloudfront.net/crop_1694593694387-4562-0-1694593694575-0526.png\", \n \"opts\": \"262,175:363,175:313,215:272,279\" \n }\n ],\n \"targetImage\": [ \n {\n \"path\": \"https://d21ksh0k4smeql.cloudfront.net/crop_1705462509874-9254-0-1705462510015-9261.png\", \n \"opts\": \"239,364:386,366:317,472:266,539\" \n }\n ],\n \"face_enhance\": 0, \n \"modifyImage\": \"https://d21ksh0k4smeql.cloudfront.net/bdd1c994c4cd7a58926088ae8a479168-1705462506461-1966.jpeg\", \n \"webhookUrl\":\"\" \n}");
Request request = new Request.Builder()
.url("https://openapi.akool.com/api/open/v3/faceswap/highquality/specifyimage")
.method("POST", body)
.addHeader("Authorization", "Bearer token")
.addHeader("Content-Type", "application/json")
.build();
Response response = client.newCall(request).execute();
```
```js Javascript
const myHeaders = new Headers();
myHeaders.append("Authorization", "Bearer token");
myHeaders.append("Content-Type", "application/json");
const raw = JSON.stringify({
"sourceImage": [
{
"path": "https://d21ksh0k4smeql.cloudfront.net/crop_1694593694387-4562-0-1694593694575-0526.png",
"opts": "262,175:363,175:313,215:272,279"
}
],
"targetImage": [
{
"path": "https://d21ksh0k4smeql.cloudfront.net/crop_1705462509874-9254-0-1705462510015-9261.png",
"opts": "239,364:386,366:317,472:266,539"
}
],
"face_enhance": 0,
"modifyImage": "https://d21ksh0k4smeql.cloudfront.net/bdd1c994c4cd7a58926088ae8a479168-1705462506461-1966.jpeg",
"webhookUrl": ""
});
const requestOptions = {
method: "POST",
headers: myHeaders,
body: raw,
redirect: "follow"
};
fetch("https://openapi.akool.com/api/open/v3/faceswap/highquality/specifyimage", requestOptions)
.then((response) => response.text())
.then((result) => console.log(result))
.catch((error) => console.error(error));
```
```php PHP
'Bearer token',
'Content-Type' => 'application/json'
];
$body = '{
"sourceImage": [
{
"path": "https://d21ksh0k4smeql.cloudfront.net/crop_1694593694387-4562-0-1694593694575-0526.png",
"opts": "262,175:363,175:313,215:272,279"
}
],
"targetImage": [
{
"path": "https://d21ksh0k4smeql.cloudfront.net/crop_1705462509874-9254-0-1705462510015-9261.png",
"opts": "239,364:386,366:317,472:266,539"
}
],
"face_enhance": 0,
"modifyImage": "https://d21ksh0k4smeql.cloudfront.net/bdd1c994c4cd7a58926088ae8a479168-1705462506461-1966.jpeg",
"webhookUrl": ""
}';
$request = new Request('POST', 'https://openapi.akool.com/api/open/v3/faceswap/highquality/specifyimage', $headers, $body);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();
```
```python Python
import requests
import json
url = "https://openapi.akool.com/api/open/v3/faceswap/highquality/specifyimage"
payload = json.dumps({
"sourceImage": [
{
"path": "https://d21ksh0k4smeql.cloudfront.net/crop_1694593694387-4562-0-1694593694575-0526.png",
"opts": "262,175:363,175:313,215:272,279"
}
],
"targetImage": [
{
"path": "https://d21ksh0k4smeql.cloudfront.net/crop_1705462509874-9254-0-1705462510015-9261.png",
"opts": "239,364:386,366:317,472:266,539"
}
],
"face_enhance": 0,
"modifyImage": "https://d21ksh0k4smeql.cloudfront.net/bdd1c994c4cd7a58926088ae8a479168-1705462506461-1966.jpeg",
"webhookUrl": ""
})
headers = {
'Authorization': 'Bearer token',
'Content-Type': 'application/json'
}
response = requests.request("POST", url, headers=headers, data=payload)
print(response.text)
```
**Response**
```json
{
"code": 1000, // Interface returns business status code
"msg": "Please be patient! If your results are not generated in three hours, please check your input image.", // Interface returns status information
"data": {
"_id": "6593c94c0ef703e8c055e3c8", // Interface returns data
"url": "https://***.cloudfront.net/final_71688047459_.pic-1704184129269-4947-f8abc658-fa82-420f-b1b3-c747d7f18e14-8535.jpg", // faceswwap result url
"job_id": "20240102082900592-5653" // Task processing unique id
}
}
```
### V4 Image Faceswap (Simplified)
```bash
POST https://openapi.akool.com/api/open/v4/faceswap/faceswapByImage
```
**Request Headers**
| **Parameter** | **Value** | **Description** |
| ------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------- |
| Authorization | Bearer `{token}` | Your API Key used for request authorization.[getToken](https://docs.akool.com/authentication/usage#get-the-token) |
**Body Attributes**
| **Parameter** | **Type** | **Value** | **Description** |
| ------------- | -------- | ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| targetImage | Array | `[{path:""}]` | A collection of faces in the original image (Each array element is an object containing path: Links to faces in the original image) |
| sourceImage | Array | `[{path:""}]` | Replacement target image information (Each array element is an object containing path: Links to replacement faces) |
| model\_name | String | "akool\_faceswap\_image\_hq" | The model name used for face swap processing. Enum: \["akool\_faceswap\_image\_hq"]. The 'akool\_faceswap\_image\_hq' model only supports high-quality face swapping for a single face in an image. |
| webhookUrl | String | | Callback url address based on HTTP request |
**Response Attributes**
| Parameter | Type | Value | Description |
| --------- | ------ | ----------------------------- | ---------------------------------------------------------------------------------------- |
| code | Int | 1000 | Interface returns business status code(1000: success) |
| msg | String | | Interface returns status information |
| data | Object | `{_id:"",url: "",job_id: ""}` | \_id: Interface returns data url: faceswap result url job\_id: Task processing unique id |
**Example**
**Body**
```json
{
"targetImage": [ // A collection of faces in the original image
{
"path": "https://drz0f01yeq1cx.cloudfront.net/1756283639652-91bbc793c9a44830ba3dc5f4ae9d9793-12.png" // Links to faces detected in the original image
}
],
"sourceImage": [ // Replacement target image information
{
"path": "https://d3fulx9g4ogwhk.cloudfront.net/canva_backend/255b106e-6629-4d64-a2ac-e54d905959ca.jpeg" // Links to faces detected in target images
}
],
"model_name": "akool_faceswap_image_hq", // Model name for face swap processing
"webhookUrl":"https://landing-test.akool.io/interface/stats-api/api/open/v5/faceswap/faceswapByImage" // Callback url address based on HTTP request
}
```
**Request**
```bash cURL
curl -X POST --location "https://openapi.akool.com/api/open/v4/faceswap/faceswapByImage" \
-H "Authorization: Bearer token" \
-H "Content-Type: application/json" \
-d '{
"targetImage": [
{
"path": "https://drz0f01yeq1cx.cloudfront.net/1756283639652-91bbc793c9a44830ba3dc5f4ae9d9793-12.png"
}
],
"sourceImage": [
{
"path": "https://d3fulx9g4ogwhk.cloudfront.net/canva_backend/255b106e-6629-4d64-a2ac-e54d905959ca.jpeg"
}
],
"model_name": "akool_faceswap_image_hq",
"webhookUrl": "https://landing-test.akool.io/interface/stats-api/api/open/v5/faceswap/faceswapByImage"
}'
```
```java Java
OkHttpClient client = new OkHttpClient().newBuilder()
.build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n \"targetImage\": [\n {\n \"path\": \"https://drz0f01yeq1cx.cloudfront.net/1756283639652-91bbc793c9a44830ba3dc5f4ae9d9793-12.png\"\n }\n ],\n \"sourceImage\": [\n {\n \"path\": \"https://d3fulx9g4ogwhk.cloudfront.net/canva_backend/255b106e-6629-4d64-a2ac-e54d905959ca.jpeg\"\n }\n ],\n \"model_name\": \"akool_faceswap_image_hq\",\n \"webhookUrl\": \"https://landing-test.akool.io/interface/stats-api/api/open/v5/faceswap/faceswapByImage\"\n}");
Request request = new Request.Builder()
.url("https://openapi.akool.com/api/open/v4/faceswap/faceswapByImage")
.method("POST", body)
.addHeader("Authorization", "Bearer token")
.addHeader("Content-Type", "application/json")
.build();
Response response = client.newCall(request).execute();
```
```js Javascript
const myHeaders = new Headers();
myHeaders.append("Authorization", "Bearer token");
myHeaders.append("Content-Type", "application/json");
const raw = JSON.stringify({
"targetImage": [
{
"path": "https://drz0f01yeq1cx.cloudfront.net/1756283639652-91bbc793c9a44830ba3dc5f4ae9d9793-12.png"
}
],
"sourceImage": [
{
"path": "https://d3fulx9g4ogwhk.cloudfront.net/canva_backend/255b106e-6629-4d64-a2ac-e54d905959ca.jpeg"
}
],
"model_name": "akool_faceswap_image_hq",
"webhookUrl": "https://landing-test.akool.io/interface/stats-api/api/open/v5/faceswap/faceswapByImage"
});
const requestOptions = {
method: "POST",
headers: myHeaders,
body: raw,
redirect: "follow"
};
fetch("https://openapi.akool.com/api/open/v4/faceswap/faceswapByImage", requestOptions)
.then((response) => response.text())
.then((result) => console.log(result))
.catch((error) => console.error(error));
```
```php PHP
'Bearer token',
'Content-Type' => 'application/json'
];
$body = '{
"targetImage": [
{
"path": "https://drz0f01yeq1cx.cloudfront.net/1756283639652-91bbc793c9a44830ba3dc5f4ae9d9793-12.png"
}
],
"sourceImage": [
{
"path": "https://d3fulx9g4ogwhk.cloudfront.net/canva_backend/255b106e-6629-4d64-a2ac-e54d905959ca.jpeg"
}
],
"model_name": "akool_faceswap_image_hq",
"webhookUrl": "https://landing-test.akool.io/interface/stats-api/api/open/v5/faceswap/faceswapByImage"
}';
$request = new Request('POST', 'https://openapi.akool.com/api/open/v4/faceswap/faceswapByImage', $headers, $body);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();
```
```python Python
import requests
import json
url = "https://openapi.akool.com/api/open/v4/faceswap/faceswapByImage"
payload = json.dumps({
"targetImage": [
{
"path": "https://drz0f01yeq1cx.cloudfront.net/1756283639652-91bbc793c9a44830ba3dc5f4ae9d9793-12.png"
}
],
"sourceImage": [
{
"path": "https://d3fulx9g4ogwhk.cloudfront.net/canva_backend/255b106e-6629-4d64-a2ac-e54d905959ca.jpeg"
}
],
"model_name": "akool_faceswap_image_hq",
"webhookUrl": "https://landing-test.akool.io/interface/stats-api/api/open/v5/faceswap/faceswapByImage"
})
headers = {
'Authorization': 'Bearer token',
'Content-Type': 'application/json'
}
response = requests.request("POST", url, headers=headers, data=payload)
print(response.text)
```
**Response**
```json
{
"code": 1000, // Interface returns business status code
"msg": "Please be patient! If your results are not generated in three hours, please check your input image.", // Interface returns status information
"data": {
"_id": "6593c94c0ef703e8c055e3c8", // Interface returns data
"url": "https://***.cloudfront.net/final_71688047459_.pic-1704184129269-4947-f8abc658-fa82-420f-b1b3-c747d7f18e14-8535.jpg", // faceswap result url
"job_id": "20240102082900592-5653" // Task processing unique id
}
}
```
### Video Faceswap
```
POST https://openapi.akool.com/api/open/v3/faceswap/highquality/specifyvideo
```
**Request Headers**
| **Parameter** | **Value** | **Description** |
| ------------- | ---------------- | ------------------------------------------- |
| Authorization | Bearer `{token}` | Your API Key used for request authorization |
**Body Attributes**
| **Parameter** | **Type** | **Value** | **Description** |
| ------------- | -------- | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| sourceImage | Array | `[{path:"",opts:""}]` | Replacement target image information:sourceImage means that you need to change it to the link collection of the face you need. You need to pass your image through the [https://sg3.akool.com/detect](https://docs.akool.com/ai-tools-suite/faceswap#face-detect) interface. Obtain the link and key point data and fill them here, and ensure that they correspond to the order of the targetImage. You need to pay attention to that each picture in the sourceImage must be a single face, otherwise the face change may fail. (Each array element is an object, and the object contains 2 properties, path:Links to faces detected in the original image. opts: Key information of faces detected in original pictures【You can get it through the face [https://sg3.akool.com/detect](https://docs.akool.com/ai-tools-suite/faceswap#face-detect) API, You can get the landmarks\_str value returned by the api interface as the value of opts) |
| targetImage | Array | `[{path:"",opts:""}]` | A collection of faces in the original video： targetImage represents the collection of faces after face detection using modifyVideo. When the original video has multiple faces, here is the image link and key point data of each face. You need to pass [https://sg3.akool.com/detect](https://docs.akool.com/ai-tools-suite/faceswap#face-detect) interface to obtain data.(Each array element is an object, and the object contains 2 properties, path:Links to faces detected in target images. opts: Key information of the face detected in the target image【You can get it through the face [https://sg3.akool.com/detect](https://docs.akool.com/ai-tools-suite/faceswap#face-detect) API, You can get the landmarks\_str value returned by the api interface as the value of opts) |
| face\_enhance | Int | 0 or 1 | Whether facial enhancement: 1 means open， 0 means close |
| modifyVideo | String | | modifyImage represents the original image you need to change the face |
| webhookUrl | String | | Callback url address based on HTTP request |
**Response Attributes**
| Parameter | Type | Value | Description |
| --------- | ------ | ----------------------------- | ------------------------------------------------------------------------------------------ |
| code | int | 1000 | Interface returns business status code(1000: success) |
| msg | String | | Interface returns status information |
| data | Object | `{_id:"",url: "",job_id: ""}` | `_id`: Interface returns data url: faceswwap result url job\_id: Task processing unique id |
**Example**
**Body**
```json
{
"sourceImage": [ // Replacement target image information： sourceImage means that you need to change it to the link collection of the face you need. You need to pass your image through the https://sg3.akool.com/detect interface. Obtain the link and key point data and fill them here, and ensure that they correspond to the order of the targetImage. You need to pay attention to that each picture in the sourceImage must be a single face, otherwise the face change may fail.
{
"path": "https://d21ksh0k4smeql.cloudfront.net/crop_1705475757658-3362-0-1705475757797-3713.png", // Links to faces detected in the original image
"opts": "239,364:386,366:317,472:266,539" // Key information of faces detected in original pictures【You can get it through the face https://sg3.akool.com/detect API,You only need to enter the first 4 items of the content array of the landmarks field of the returned data, and concatenate them into a string through ":", like this: ["434,433","588,449","509,558","432,614", "0,0", "0,0"] to "434,433:588,449:509,558:432,614"】
}
],
"targetImage": [ // A collection of faces in the original video： targetImage represents the collection of faces after face detection using modifyVideo. When the original image has multiple faces, here is the image link and key point data of each face. You need to pass https://sg3.akool.com/detect interface to obtain data
{
"path": "https://d21ksh0k4smeql.cloudfront.net/crop_1705479323786-0321-0-1705479323896-7695.png", // Links to faces detected in target images
"opts": "176,259:243,259:209,303:183,328" // Key information of the face detected in the target image【You can get it through the face https://sg3.akool.com/detect API,You only need to enter the first 4 items of the content array of the landmarks field of the returned data, and concatenate them into a string through ":"， like this: ["1622,759","2149,776","1869,1085","1875,1345", "0,0", "0,0"] to "1622,759:2149,776:1869,1085:1875,1345"】
}
],
"face_enhance":0,
"modifyVideo": "https://d21ksh0k4smeql.cloudfront.net/avatar_01-1705479314627-0092.mp4", // modifyImage represents the original image you need to change the face;
"webhookUrl":"" // Callback url address based on HTTP request
}
```
**Request**
```bash cURL
curl --location 'https://openapi.akool.com/api/open/v3/faceswap/highquality/specifyvideo' \
--header 'Authorization: Bearer token' \
--header 'Content-Type: application/json' \
--data '{
"sourceImage": [
{
"path": "https://d21ksh0k4smeql.cloudfront.net/crop_1705475757658-3362-0-1705475757797-3713.png",
"opts": "239,364:386,366:317,472:266,539"
}
],
"targetImage": [
{
"path": "https://d21ksh0k4smeql.cloudfront.net/crop_1705479323786-0321-0-1705479323896-7695.png",
"opts": "176,259:243,259:209,303:183,328"
}
],
"face_enhance": 0,
"modifyVideo": "https://d21ksh0k4smeql.cloudfront.net/avatar_01-1705479314627-0092.mp4",
"webhookUrl":""
}'
```
```java Java
OkHttpClient client = new OkHttpClient().newBuilder()
.build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n \"sourceImage\": [ \n {\n \"path\": \"https://d21ksh0k4smeql.cloudfront.net/crop_1705475757658-3362-0-1705475757797-3713.png\", \n \"opts\": \"239,364:386,366:317,472:266,539\" \n }\n ],\n \"targetImage\": [ \n {\n \"path\": \"https://d21ksh0k4smeql.cloudfront.net/crop_1705479323786-0321-0-1705479323896-7695.png\", \n \"opts\": \"176,259:243,259:209,303:183,328\" \n }\n ],\n \"modifyVideo\": \"https://d21ksh0k4smeql.cloudfront.net/avatar_01-1705479314627-0092.mp4\", \n \"webhookUrl\":\"\" \n\n}");
Request request = new Request.Builder()
.url("https://openapi.akool.com/api/open/v3/faceswap/highquality/specifyvideo")
.method("POST", body)
.addHeader("Authorization", "Bearer token")
.addHeader("Content-Type", "application/json")
.build();
Response response = client.newCall(request).execute();
```
```js Javascript
const myHeaders = new Headers();
myHeaders.append("Authorization", "Bearer token");
myHeaders.append("Content-Type", "application/json");
const raw = JSON.stringify({
"sourceImage": [
{
"path": "https://d21ksh0k4smeql.cloudfront.net/crop_1705475757658-3362-0-1705475757797-3713.png",
"opts": "239,364:386,366:317,472:266,539"
}
],
"targetImage": [
{
"path": "https://d21ksh0k4smeql.cloudfront.net/crop_1705479323786-0321-0-1705479323896-7695.png",
"opts": "176,259:243,259:209,303:183,328"
}
],
"face_enhance": 0,
"modifyVideo": "https://d21ksh0k4smeql.cloudfront.net/avatar_01-1705479314627-0092.mp4",
"webhookUrl": ""
});
const requestOptions = {
method: "POST",
headers: myHeaders,
body: raw,
redirect: "follow"
};
fetch("https://openapi.akool.com/api/open/v3/faceswap/highquality/specifyvideo", requestOptions)
.then((response) => response.text())
.then((result) => console.log(result))
.catch((error) => console.error(error));
```
```php PHP
'Bearer token',
'Content-Type' => 'application/json'
];
$body = '{
"sourceImage": [
{
"path": "https://d21ksh0k4smeql.cloudfront.net/crop_1705475757658-3362-0-1705475757797-3713.png",
"opts": "239,364:386,366:317,472:266,539"
}
],
"targetImage": [
{
"path": "https://d21ksh0k4smeql.cloudfront.net/crop_1705479323786-0321-0-1705479323896-7695.png",
"opts": "176,259:243,259:209,303:183,328"
}
],
"face_enhance": 0,
"modifyVideo": "https://d21ksh0k4smeql.cloudfront.net/avatar_01-1705479314627-0092.mp4",
"webhookUrl": ""
}';
$request = new Request('POST', 'https://openapi.akool.com/api/open/v3/faceswap/highquality/specifyvideo', $headers, $body);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();
```
```python Python
import requests
import json
url = "https://openapi.akool.com/api/open/v3/faceswap/highquality/specifyvideo"
payload = json.dumps({
"sourceImage": [
{
"path": "https://d21ksh0k4smeql.cloudfront.net/crop_1705475757658-3362-0-1705475757797-3713.png",
"opts": "239,364:386,366:317,472:266,539"
}
],
"targetImage": [
{
"path": "https://d21ksh0k4smeql.cloudfront.net/crop_1705479323786-0321-0-1705479323896-7695.png",
"opts": "176,259:243,259:209,303:183,328"
}
],
"face_enhance": 0,
"modifyVideo": "https://d21ksh0k4smeql.cloudfront.net/avatar_01-1705479314627-0092.mp4",
"webhookUrl": ""
})
headers = {
'Authorization': 'Bearer token',
'Content-Type': 'application/json'
}
response = requests.request("POST", url, headers=headers, data=payload)
print(response.text)
```
**Response**
```json
{
"code": 1000, // Interface returns business status code
"msg": "Please be patient! If your results are not generated in three hours, please check your input image.", // Interface returns status information
"data": {
"_id": "6582bf774e47940151d8fa1e", // db id
"url": "https://***.cloudfront.net/final_1703067481578-7151-1703067481578-7151-470fbfbc-ab77-4868-a7f4-dbba1ec4f1c9-3478.jpg", // faceswwap result url
"job_id": "20231220101831489-3860" // Task processing unique id
}
}
```
### Get Faceswap Result List Byids
```
GET https://openapi.akool.com/api/open/v3/faceswap/result/listbyids?_ids=64ef2f27b33f466877701c6a
```
**Request Headers**
| **Parameter** | **Value** | **Description** |
| ------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------- |
| Authorization | Bearer `{token}` | Your API Key used for request authorization.[getToken](https://docs.akool.com/authentication/usage#get-the-token) |
**Query Attributes**
| Parameter | Type | Value | Description |
| --------- | ------ | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| \_ids | String | | result ids are strings separated by commas【You can get it by returning the \_id field from [https://openapi.akool.com/api/open/v3/faceswap/highquality/specifyimage](https://docs.akool.com/ai-tools-suite/faceswap#image-faceswap) or [https://openapi.akool.com/api/open/v3/faceswap/highquality/specifyvideo](https://docs.akool.com/ai-tools-suite/faceswap#video-faceswap) api.】 |
**Response Attributes**
| Parameter | Type | Value | Description |
| --------- | ------ | ------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| code | int | 1000 | Interface returns business status code(1000: success) |
| msg | String | | Interface returns status information |
| data | Object | `result: [{faceswap_status:"",url: "",createdAt: ""}]` | faceswap\_status: faceswap result status: 1 In Queue 2 Processing 3 Success 4 failed url: faceswwap result url createdAt: current faceswap action created time |
**Example**
**Request**
```bash cURL
curl --location 'https://openapi.akool.com/api/open/v3/faceswap/result/listbyids?_ids=64ef2f27b33f466877701c6a' \
--header 'Authorization: Bearer token'
```
```java Java
OkHttpClient client = new OkHttpClient().newBuilder()
.build();
MediaType mediaType = MediaType.parse("text/plain");
RequestBody body = RequestBody.create(mediaType, "");
Request request = new Request.Builder()
.url("https://openapi.akool.com/api/open/v3/faceswap/result/listbyids?_ids=64ef2f27b33f466877701c6a")
.method("GET", body)
.addHeader("Authorization", "Bearer token")
.build();
Response response = client.newCall(request).execute();
```
```js Javascript
const myHeaders = new Headers();
myHeaders.append("Authorization", "Bearer token");
const requestOptions = {
method: "GET",
headers: myHeaders,
redirect: "follow"
};
fetch("https://openapi.akool.com/api/open/v3/faceswap/result/listbyids?_ids=64ef2f27b33f466877701c6a", requestOptions)
.then((response) => response.text())
.then((result) => console.log(result))
.catch((error) => console.error(error));
```
```php PHP
'Bearer token'
];
$request = new Request('GET', 'https://openapi.akool.com/api/open/v3/faceswap/result/listbyids?_ids=64ef2f27b33f466877701c6a', $headers);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();
```
```python Python
import requests
url = "https://openapi.akool.com/api/open/v3/faceswap/result/listbyids?_ids=64ef2f27b33f466877701c6a"
payload = {}
headers = {
'Authorization': 'Bearer token'
}
response = requests.request("GET", url, headers=headers, data=payload)
print(response.text)
```
**Response**
```json
{
"code": 1000, // error code
"msg": "OK", // api message
"data": {
"result": [
{
"faceswap_type": 1,
"faceswap_quality": 2,
"faceswap_status": 1, // faceswap result status: 1 In Queue 2 Processing 3 Success 4 failed
"deduction_status": 1,
"image": 1,
"video_duration": 0,
"deduction_duration": 0,
"update_time": 0,
"_id": "64dae65af6e250d4fb2bca63",
"userId": "64d985c5571729d3e2999477",
"uid": 378337,
"url": "https://d21ksh0k4smeql.cloudfront.net/final_material__d71fad6e-a464-43a5-9820-6e4347dce228-80554b9d-2387-4b20-9288-e939952c0ab4-0356.jpg", // faceswwap result url
"createdAt": "2023-08-15T02:43:38.536Z" // current faceswap action created time
}
]
}
}
```
### GET Faceswap User Credit Info
```
GET https://openapi.akool.com/api/open/v3/faceswap/quota/info
```
**Request Headers**
| **Parameter** | **Value** | **Description** |
| ------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------- |
| Authorization | Bearer `{token}` | Your API Key used for request authorization.[getToken](https://docs.akool.com/authentication/usage#get-the-token) |
**Response Attributes**
| Parameter | Type | Value | Description |
| --------- | ------ | ---------------- | ----------------------------------------------------- |
| code | int | 1000 | Interface returns business status code(1000: success) |
| msg | String | | Interface returns status information |
| data | Object | `{"credit": 0 }` | credit: Account balance |
**Example**
**Request**
```bash
curl --location 'https://openapi.akool.com/api/open/v3/faceswap/quota/info' \
--header 'Authorization: Bearer token'
```
```java Java
OkHttpClient client = new OkHttpClient().newBuilder()
.build();
MediaType mediaType = MediaType.parse("text/plain");
RequestBody body = RequestBody.create(mediaType, "");
Request request = new Request.Builder()
.url("https://openapi.akool.com/api/open/v3/faceswap/quota/info")
.method("GET", body)
.addHeader("Authorization", "Bearer token")
.build();
Response response = client.newCall(request).execute();
```
```js Javascript
const myHeaders = new Headers();
myHeaders.append("Authorization", "Bearer token");
const requestOptions = {
method: "GET",
headers: myHeaders,
redirect: "follow"
};
fetch("https://openapi.akool.com/api/open/v3/faceswap/quota/info", requestOptions)
.then((response) => response.text())
.then((result) => console.log(result))
.catch((error) => console.error(error));
```
```php PHP
'Bearer token'
];
$request = new Request('GET', 'https://openapi.akool.com/api/open/v3/faceswap/quota/info', $headers);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();
```
```python Python
import requests
url = "https://openapi.akool.com/api/open/v3/faceswap/quota/info"
payload = {}
headers = {
'Authorization': 'Bearer token'
}
response = requests.request("GET", url, headers=headers, data=payload)
print(response.text)
```
**Response**
```json
{
"code": 1000, // Business status code
"msg": "OK", // The interface returns status information
"data": {
"credit": 0 // Account balance
}
}
```
### POST Faceswap Result Del Byids
```
POST https://openapi.akool.com/api/open/v3/faceswap/result/delbyids
```
**Request Headers**
| **Parameter** | **Value** | **Description** |
| ------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------- |
| Authorization | Bearer `{token}` | Your API Key used for request authorization.[getToken](https://docs.akool.com/authentication/usage#get-the-token) |
**Body Attributes**
| Parameter | Type | Value | Description |
| --------- | ------ | ----- | ------------------------------------------ |
| \_ids | String | | result ids are strings separated by commas |
**Response Attributes**
| Parameter | Type | Value | Description |
| --------- | ------ | ----- | ---------------------------------------------------- |
| code | int | 1000 | Interface returns business status code(1000:success) |
| msg | String | | Interface returns status information |
**Example**
**Body**
```json
{
"_ids":""//result ids are strings separated by commas
}
```
**Request**
```bash cURL
curl --location 'https://openapi.akool.com/api/open/v3/faceswap/result/delbyids' \
--header 'Authorization: Bearer token' \
--header 'Content-Type: application/json' \
--data '{
"_ids":""
}'
```
```java Java
OkHttpClient client = new OkHttpClient().newBuilder()
.build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n \"_ids\":\"\"\n}");
Request request = new Request.Builder()
.url("https://openapi.akool.com/api/open/v3/faceswap/result/delbyids")
.method("POST", body)
.addHeader("Authorization", "Bearer token")
.addHeader("Content-Type", "application/json")
.build();
Response response = client.newCall(request).execute();
```
```js JavaScript
const myHeaders = new Headers();
myHeaders.append("Authorization", "Bearer token");
myHeaders.append("Content-Type", "application/json");
const raw = JSON.stringify({
"_ids": ""
});
const requestOptions = {
method: "POST",
headers: myHeaders,
body: raw,
redirect: "follow"
};
fetch("https://openapi.akool.com/api/open/v3/faceswap/result/delbyids", requestOptions)
.then((response) => response.text())
.then((result) => console.log(result))
.catch((error) => console.error(error));
```
```php PHP
'Bearer token',
'Content-Type' => 'application/json'
];
$body = '{
"_ids": ""
}';
$request = new Request('POST', 'https://openapi.akool.com/api/open/v3/faceswap/result/delbyids', $headers, $body);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();
```
```python Python
import requests
import json
url = "https://openapi.akool.com/api/open/v3/faceswap/result/delbyids"
payload = json.dumps({
"_ids": ""
})
headers = {
'Authorization': 'Bearer token',
'Content-Type': 'application/json'
}
response = requests.request("POST", url, headers=headers, data=payload)
print(response.text)
```
**Response**
```json
{
"code": 1000, // Business status code
"msg": "OK" // The interface returns status information
}
```
### Face Detect
```
POST https://sg3.akool.com/detect
```
**Request Headers**
| **Parameter** | **Value** | **Description** |
| ------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------- |
| Authorization | Bearer `{token}` | Your API Key used for request authorization.[getToken](https://docs.akool.com/authentication/usage#get-the-token) |
**Body Attributes**
| Parameter | Type | Value | Description |
| ------------ | ------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| single\_face | Boolean | true/false | Is it a single face picture: This should be true when the incoming picture has only one face, and false when the incoming picture has multiple faces. |
| image\_url | String | | image link: You can choose to enter this parameter or the img parameter. |
| img | String | | Image base64 information: You can choose to enter this parameter or the image\_url parameter. |
**Response Attributes**
| Parameter | Type | Value | Description |
| ----------- | ------ | ----- | ------------------------------------------------- |
| error\_code | int | 0 | Interface returns business status code(0:success) |
| error\_msg | String | | error message of this api |
| landmarks | Array | \[] | Key point data of face |
**Example**
**Body**
```json
{
"single_face": false, // Is it a single face picture: This should be true when the incoming picture has only one face, and false when the incoming picture has multiple faces.
"image_url":"https://d21ksh0k4smeql.cloudfront.net/IMG_6150-1696984459910-0610.jpeg", // image link：You can choose to enter this parameter or the img parameter.
"img": "data:image/jpeg;base64***" // Image base64 information：You can choose to enter this parameter or the image_url parameter.
}
```
**Request**
```bash cURL
curl --location 'https://sg3.akool.com/detect' \
--header 'Authorization: Bearer token' \
--header 'Content-Type: application/json' \
--data '{
"single_face": false,
"image_url":"https://d21ksh0k4smeql.cloudfront.net/IMG_6150-1696984459910-0610.jpeg",
"img": "data:image/jpeg;base64***"
}'
```
```java Java
OkHttpClient client = new OkHttpClient().newBuilder()
.build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n \"single_face\": false, \n \"image_url\":\"https://d21ksh0k4smeql.cloudfront.net/IMG_6150-1696984459910-0610.jpeg\", \n \"img\": \"data:image/jpeg;base64***\" \n}");
Request request = new Request.Builder()
.url("https://sg3.akool.com/detect")
.method("POST", body)
.addHeader("Authorization", "Bearer token")
.addHeader("Content-Type", "application/json")
.build();
Response response = client.newCall(request).execute();
```
```js Javascript
const myHeaders = new Headers();
myHeaders.append("Authorization", "Bearer token");
myHeaders.append("Content-Type", "application/json");
const raw = JSON.stringify({
"single_face": false,
"image_url": "https://d21ksh0k4smeql.cloudfront.net/IMG_6150-1696984459910-0610.jpeg",
"img": "data:image/jpeg;base64***"
});
const requestOptions = {
method: "POST",
headers: myHeaders,
body: raw,
redirect: "follow"
};
fetch("https://sg3.akool.com/detect", requestOptions)
.then((response) => response.text())
.then((result) => console.log(result))
.catch((error) => console.error(error));
```
```php PHP
'Bearer token',
'Content-Type' => 'application/json'
];
$body = '{
"single_face": false,
"image_url": "https://d21ksh0k4smeql.cloudfront.net/IMG_6150-1696984459910-0610.jpeg",
"img": "data:image/jpeg;base64***"
}';
$request = new Request('POST', 'https://sg3.akool.com/detect', $headers, $body);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();
```
```python Python
import requests
import json
url = "https://sg3.akool.com/detect"
payload = json.dumps({
"single_face": False,
"image_url": "https://d21ksh0k4smeql.cloudfront.net/IMG_6150-1696984459910-0610.jpeg",
"img": "data:image/jpeg;base64***"
})
headers = {
'Authorization': 'Bearer token',
'Content-Type': 'application/json'
}
response = requests.request("POST", url, headers=headers, data=payload)
print(response.text)
```
**Response**
```json
{
"error_code": 0, // error code: 0 is seccuss
"error_msg": "SUCCESS", // error message of this api
"landmarks": [ // Key point data of face
[
[
238,365
],
[
386,363
],
[
318,470
],
[
267,539
],
[
0,0
],
[
0,0
]
]
],
"landmarks_str": [
"238,365:386,363:318,470:267,539"
],
"region": [
[
150,195,317,429
]
],
"seconds": 0.04458212852478027, // API time-consuming
"trx_id": "74178dc5-199a-479a-89d0-4b0e1c161219"
}
```
**Response Code Description**
Please note that if the value of the response code is not equal to 1000, the request is failed or wrong
| **Parameter** | **Value** | **Description** |
| ------------- | --------- | --------------------------------------------------------------------- |
| code | 1000 | Success |
| code | 1003 | Parameter error or Parameter can not be empty |
| code | 1005 | Operation is too frequent |
| code | 1006 | Your quota is not enough |
| code | 1007 | The number of people who can have their faces changed cannot exceed 8 |
| code | 1101 | Invalid authorization or The request token has expired |
| code | 1102 | Authorization cannot be empty |
| code | 1200 | The account has been banned |
# Image Generate
Source: https://docstest.akool.io/ai-tools-suite/image-generate
Easily create an image from scratch with our AI image generator by entering descriptive text.
The resources (image, video, voice) generated by our API are valid for 7 days. Please save the relevant resources as soon as possible to prevent expiration.
### Text to image / Image to image
```
POST https://openapi.akool.com/api/open/v3/content/image/createbyprompt
```
**Request Headers**
| **Parameter** | **Value** | **Description** |
| ------------- | ------------ | ------------------------------------------- |
| Authorization | Bearer token | Your API Key used for request authorization |
**Body Attributes**
| **Parameter** | **Type** | **Value** | **Description** |
| ------------- | -------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| prompt | String | | Describe the information needed to generate the image |
| scale | String | "1:1" "4:3" "3:4" "16:9" "9:16" "3:2" "2:3" | The size of the generated image default: "1:1" |
| source\_image | String | | Need to generate the original image link of the image 【If you want to perform imageToImage operation you can pass in this parameter】 |
| webhookUrl | String | | Callback url address based on HTTP request |
**Response Attributes**
| **Parameter** | **Type** | **Value** | **Description** |
| ------------- | -------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------- |
| code | int | 1000 | Interface returns business status code(1000:success) |
| msg | String | | Interface returns status information |
| data | Object | `{ _id: "", image_status: 1 }` | \_id: Interface returns data, image\_status: the status of image: 【1:queueing, 2:processing, 3:completed, 4:failed】 |
**Example**
**Body**
```json
{
"prompt": "Sun Wukong is surrounded by heavenly soldiers and generals", // Describe the information needed to generate the image
"scale": "1:1",
"source_image": "https://drz0f01yeq1cx.cloudfront.net/1708333063911-9cbe39b7-3c5f-4a35-894c-359a6cbb76c3-3283.png", // Need to generate the original image link of the image 【If you want to perform imageToImage operation you can pass in this parameter】
"webhookUrl":"http://localhost:3007/image/webhook" // Callback url address based on HTTP request
}
```
**Request**
```bash cURL
curl --location 'https://openapi.akool.com/api/open/v3/content/image/createbyprompt' \
--header 'Authorization: Bearer token' \
--header 'Content-Type: application/json' \
--data '{
"prompt": "Sun Wukong is surrounded by heavenly soldiers and generals",
"source_image": "https://drz0f01yeq1cx.cloudfront.net/1708333063911-9cbe39b7-3c5f-4a35-894c-359a6cbb76c3-3283.png",
"scale": "1:1",
"webhookUrl":"http://localhost:3007/image/webhook"
}
'
```
```java Java
OkHttpClient client = new OkHttpClient().newBuilder()
.build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n \"prompt\": \"Sun Wukong is surrounded by heavenly soldiers and generals\", \n \"source_image\": \"https://drz0f01yeq1cx.cloudfront.net/1708333063911-9cbe39b7-3c5f-4a35-894c-359a6cbb76c3-3283.png\", \n \"webhookUrl\":\"http://localhost:3007/image/webhook\" \n}\n");
Request request = new Request.Builder()
.url("https://openapi.akool.com/api/open/v3/content/image/createbyprompt")
.method("POST", body)
.addHeader("Authorization", "Bearer token")
.addHeader("Content-Type", "application/json")
.build();
Response response = client.newCall(request).execute();
```
```javascript Javascript
const myHeaders = new Headers();
myHeaders.append("Authorization", "Bearer token");
myHeaders.append("Content-Type", "application/json");
const raw = JSON.stringify({
"prompt": "Sun Wukong is surrounded by heavenly soldiers and generals",
"source_image": "https://drz0f01yeq1cx.cloudfront.net/1708333063911-9cbe39b7-3c5f-4a35-894c-359a6cbb76c3-3283.png",
"scale": "1:1",
"webhookUrl": "http://localhost:3007/image/webhook"
});
const requestOptions = {
method: "POST",
headers: myHeaders,
body: raw,
redirect: "follow"
};
fetch("https://openapi.akool.com/api/open/v3/content/image/createbyprompt", requestOptions)
.then((response) => response.text())
.then((result) => console.log(result))
.catch((error) => console.error(error));
```
```php PHP
'Bearer token',
'Content-Type' => 'application/json'
];
$body = '{
"prompt": "Sun Wukong is surrounded by heavenly soldiers and generals",
"source_image": "https://drz0f01yeq1cx.cloudfront.net/1708333063911-9cbe39b7-3c5f-4a35-894c-359a6cbb76c3-3283.png",
"scale": "1:1",
"webhookUrl": "http://localhost:3007/image/webhook"
}';
$request = new Request('POST', 'https://openapi.akool.com/api/open/v3/content/image/createbyprompt', $headers, $body);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();
```
```python Python
import requests
import json
url = "https://openapi.akool.com/api/open/v3/content/image/createbyprompt"
payload = json.dumps({
"prompt": "Sun Wukong is surrounded by heavenly soldiers and generals",
"source_image": "https://drz0f01yeq1cx.cloudfront.net/1708333063911-9cbe39b7-3c5f-4a35-894c-359a6cbb76c3-3283.png",
"scale": "1:1",
"webhookUrl": "http://localhost:3007/image/webhook"
})
headers = {
'Authorization': 'Bearer token',
'Content-Type': 'application/json'
}
response = requests.request("POST", url, headers=headers, data=payload)
print(response.text)
```
**Response**
```json
{
"code": 1000,
"msg": "OK",
"data": {
"faceswap_quality": 2,
"deduction_credit": 2,
"buttons": [],
"used_buttons": [],
"upscaled_urls": [],
"_id": "64dd82eef0b6684651e90131",
"uid": 378337,
"create_time": 1692238574633,
"origin_prompt": "***",
"source_image": "https://***.cloudfront.net/1702436829534-4a813e6c-303e-48c7-8a4e-b915ae408b78-5034.png",
"prompt": "***** was a revolutionary leader who transformed *** into a powerful communist state.",
"type": 4,
"from": 1,
"image_status": 1 // the status of image： 【1:queueing, 2:processing,3:completed, 4:failed】
}
}
```
### Generate 4K or variations
```
POST https://openapi.akool.com/api/open/v3/content/image/createbybutton
```
**Request Headers**
| **Parameter** | **Value** | **Description** |
| ------------- | ------------ | ------------------------------------------- |
| Authorization | Bearer token | Your API Key used for request authorization |
**Body Attributes**
| **Parameter** | **Type** | **Value** | **Description** |
| ------------- | -------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| \_id | String | | the image`_id` you had generated, you can got it from [https://openapi.akool.com/api/open/v3/content/image/createbyprompt](https://openapi.akool.com/api/open/v3/content/image/createbyprompt) |
| button | String | | the type of operation you want to perform, You can get the field（display\_buttons） value from [https://openapi.akool.com/api/open/v3/content/image/infobymodelid](https://openapi.akool.com/api/open/v3/content/image/infobymodelid) 【U(1-4): Generate a single 4k image based on the corresponding serial number original image， V(1-4)：Generate a single variant image based on the corresponding serial number original image】 |
| webhookUrl | String | | Callback url address based on HTTP request |
**Response Attributes**
| **Parameter** | **Type** | **Value** | **Description** |
| ------------- | -------- | ------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| code | int | 1000 | Interface returns business status code(1000:success) |
| msg | String | | Interface returns status information |
| data | Object | `{_id:"",image_content_model_id: "",op_button: "",image_status:1}` | `_id`: Interface returns data image\_content\_model\_id: the origin image `_id` you had generated op\_button: the type of operation you want to perform image\_status: the status of image： 【1:queueing, 2:processing, 3:completed, 4:failed】 |
**Example**
**Body**
```json
{
"_id": "65d3206b83ccf5ab7d46cdc6", // the image【_id】 you had generated, you can got it from https://openapi.akool.com/api/open/v3/content/image/createbyprompt
"button": "U2", // the type of operation you want to perform, You can get the field（display_buttons） value from https://content.akool.com/api/v1/content/image/infobyid 【U(1-4): Generate a single 4k image based on the corresponding serial number original image， V(1-4)：Generate a single variant image based on the corresponding serial number original image】
"webhookUrl":"http://localhost:3007/image/webhook" // Callback url address based on HTTP request
}
```
**Request**
```bash cURL
curl --location 'https://openapi.akool.com/api/open/v3/content/image/createbybutton' \
--header 'Authorization: Bearer token' \
--header 'Content-Type: application/json' \
--data '{
"_id": "65d3206b83ccf5ab7d46cdc6",
"button": "U2",
"webhookUrl":"http://localhost:3007/image/webhook"
}'
```
```java Java
OkHttpClient client = new OkHttpClient().newBuilder()
.build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n \"_id\": \"65d3206b83ccf5ab7d46cdc6\", \n \"button\": \"U2\", \n \"webhookUrl\":\"http://localhost:3007/image/webhook\" \n}");
Request request = new Request.Builder()
.url("https://openapi.akool.com/api/open/v3/content/image/createbybutton")
.method("POST", body)
.addHeader("Authorization", "Bearer token")
.addHeader("Content-Type", "application/json")
.build();
Response response = client.newCall(request).execute();
```
```js Javascript
const myHeaders = new Headers();
myHeaders.append("Authorization", "Bearer token");
myHeaders.append("Content-Type", "application/json");
const raw = JSON.stringify({
"_id": "65d3206b83ccf5ab7d46cdc6",
"button": "U2",
"webhookUrl": "http://localhost:3007/image/webhook"
});
const requestOptions = {
method: "POST",
headers: myHeaders,
body: raw,
redirect: "follow"
};
fetch("https://openapi.akool.com/api/open/v3/content/image/createbybutton", requestOptions)
.then((response) => response.text())
.then((result) => console.log(result))
.catch((error) => console.error(error));
```
```php PHP
'Bearer token',
'Content-Type' => 'application/json'
];
$body = '{
"_id": "65d3206b83ccf5ab7d46cdc6",
"button": "U2",
"webhookUrl": "http://localhost:3007/image/webhook"
}';
$request = new Request('POST', 'https://openapi.akool.com/api/open/v3/content/image/createbybutton', $headers, $body);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();
```
```python Python
import requests
import json
url = "https://openapi.akool.com/api/open/v3/content/image/createbybutton"
payload = json.dumps({
"_id": "65d3206b83ccf5ab7d46cdc6",
"button": "U2",
"webhookUrl": "http://localhost:3007/image/webhook"
})
headers = {
'Authorization': 'Bearer token',
'Content-Type': 'application/json'
}
response = requests.request("POST", url, headers=headers, data=payload)
print(response.text)
```
**Response**
```json
{
"code": 1000,
"msg": "OK",
"data": {
"faceswap_quality": 2,
"deduction_credit": 2,
"buttons": [],
"used_buttons": [],
"upscaled_urls": [],
"_id": "6508292f16e5ba407d47d21b",
"image_content_model_id": "6508288416e5ba407d47d13f", // the origin image【_id】 you had generated
"create_time": 1695033647012,
"op_button": "U2", // the type of operation you want to perform
"op_buttonMessageId": "kwZsk6elltno5Nt37VLj",
"image_status": 1, // the status of image： 【1:queueing, 2:processing, 3:completed, 4:failed】
"from": 1
}
}
```
### Get Image Result image info
```
GET https://openapi.akool.com/api/open/v3/content/image/infobymodelid?image_model_id=64dd838cf0b6684651e90217
```
**Request Headers**
| **Parameter** | **Value** | **Description** |
| ------------- | ------------ | ------------------------------------------- |
| Authorization | Bearer token | Your API Key used for request authorization |
**Query Attributes**
| **Parameter** | **Type** | **Value** | **Description** |
| ---------------- | -------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| image\_model\_id | String | | image db id：You can get it based on the `_id` field returned by [https://openapi.akool.com/api/open/v3/content/image/createbyprompt](https://openapi.akool.com/api/open/v3/content/image/createbyprompt) or [https://openapi.akool.com/api/open/v3/content/image/createbybutton](https://openapi.akool.com/api/open/v3/content/image/createbybutton) api. |
**Response Attributes**
| **Parameter** | **Type** | **Value** | **Description** |
| ------------- | -------- | ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| code | int | 1000 | Interface returns business status code(1000:success) |
| msg | String | | Interface returns status information |
| data | Object | `{image_status:1,_id:"",image:""}` | image\_status: the status of image： 【1:queueing, 2:processing, 3:completed, 4:failed】 image: Image result after processing \_id: Interface returns data |
**Example**
**Request**
```bash cURL
curl --location 'https://openapi.akool.com/api/open/v3/content/image/infobymodelid?image_model_id=662a10df4197b3af58532e89' \
--header 'Authorization: Bearer token'
```
```java Java
OkHttpClient client = new OkHttpClient().newBuilder()
.build();
MediaType mediaType = MediaType.parse("text/plain");
RequestBody body = RequestBody.create(mediaType, "");
Request request = new Request.Builder()
.url("https://openapi.akool.com/api/open/v3/content/image/infobymodelid?image_model_id=662a10df4197b3af58532e89")
.method("GET", body)
.addHeader("Authorization", "Bearer token")
.build();
Response response = client.newCall(request).execute();
```
```js Javascript
const myHeaders = new Headers();
myHeaders.append("Authorization", "Bearer token");
const requestOptions = {
method: "GET",
headers: myHeaders,
redirect: "follow"
};
fetch("https://openapi.akool.com/api/open/v3/content/image/infobymodelid?image_model_id=662a10df4197b3af58532e89", requestOptions)
.then((response) => response.text())
.then((result) => console.log(result))
.catch((error) => console.error(error));
```
```php PHP
'Bearer token'
];
$request = new Request('GET', 'https://openapi.akool.com/api/open/v3/content/image/infobymodelid?image_model_id=662a10df4197b3af58532e89', $headers);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();
```
```python Python
import requests
url = "https://openapi.akool.com/api/open/v3/content/image/infobymodelid?image_model_id=662a10df4197b3af58532e89"
payload = {}
headers = {
'Authorization': 'Bearer token'
}
response = requests.request("GET", url, headers=headers, data=payload)
print(response.text)
```
**Response**
```json
{
"code": 1000,
"msg": "OK",
"data": {
"faceswap_quality": 2,
"deduction_credit": 2,
"buttons": [ "U1",
"U2",
"U3",
"U4",
"V1",
"V2",
"V3",
"V4"],
"used_buttons": [],
"upscaled_urls": [],
"_id": "662a10df4197b3af58532e89",
"create_time": 1714032863272,
"uid": 378337,
"type": 3,
"image_status": 3, // the status of image：【1：queueing， 2：processing，3：completed，4：failed】
"image": "https://***.cloudfront.net/1714032892336-e0ec9305-e217-4b79-8704-e595a822c12b-8013.png" // Image result after processing
}
}
```
**Response Code Description**
Please note that if the value of the response code is not equal to 1000, the request is failed or wrong
| **Parameter** | **Value** | **Description** |
| ------------- | --------- | ------------------------------------------------------ |
| code | 1000 | Success |
| code | 1003 | Parameter error or Parameter can not be empty |
| code | 1008 | The content you get does not exist |
| code | 1009 | You do not have permission to operate |
| code | 1010 | You can not operate this content |
| code | 1101 | Invalid authorization or The request token has expired |
| code | 1102 | Authorization cannot be empty |
| code | 1108 | image generate error,please try again later |
| code | 1200 | The account has been banned |
# Image to Video
Source: https://docstest.akool.io/ai-tools-suite/image2video
Easily transform static images into dynamic videos with our AI Image to Video tool by adding motion, transitions, and effects in seconds.
You can use the following APIs to create videos from images with various effects and audio options.
The resources (image, video, voice) generated by our API are valid for 7 days. Please save the relevant resources as soon as possible to prevent expiration.
## Pricing
### Image to Video
| Video Duration | 720p | 1080p | 4k |
| -------------- | ---------------- | ---------------- | ---------------- |
| 5 seconds | 20 credits/video | 25 credits/video | 30 credits/video |
| 10 seconds | 40 credits/video | 50 credits/video | 60 credits/video |
### Video to Audio
| Video Duration | Credits |
| -------------- | ---------------- |
| 5 seconds | 5 credits/video |
| 10 seconds | 10 credits/video |
**Note:** The Video to Audio feature is charged only when used separately. It is free of charge when included in Image to Video.
## Create Image to Video
```
POST https://openapi.akool.com/api/open/v4/image2Video/createBySourcePrompt
```
**Request Headers**
| **Parameter** | **Value** | **Description** |
| ------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------- |
| Authorization | Bearer `{token}` | Your API Key used for request authorization.[getToken](https://docs.akool.com/authentication/usage#get-the-token) |
**Body Attributes**
| **Parameter** | **Type** | **Required** | **Description** |
| ------------------ | -------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| image\_url | String | true | Image URL to be animated |
| prompt | String | true | Prompt text describing how to animate the image |
| negative\_prompt | String | true | Prompt text describing what to avoid in the animation |
| extend\_prompt | Boolean | false | Whether to use algorithm default extended prompts |
| resolution | String | true | Resolution options: 720p, 1080p, 4k |
| audio\_url | String | false | Audio URL, required when audio\_type = 2 |
| audio\_type | Integer | true | Audio type: 1 = AI generate, 2 = user custom upload, 3 = none (no audio) |
| video\_length | Integer | true | Video duration in seconds, options: 5, 10 (10s only available for pro and above subscriptions) |
| is\_premium\_model | Boolean | false | Whether to use premium video model for faster generation (pro and above subscriptions only) |
| effect\_code | String | false | Effect code: if specified, prompt content will be ignored.[getEffectCode](https://docs.akool.com/ai-tools-suite/image2video#get-available-effects) |
| webhookurl | String | false | Callback URL for POST requests |
**Response Attributes**
| **Parameter** | **Type** | **Description** |
| ------------------- | -------- | ------------------------------------------------------------ |
| code | Integer | Interface returns business status code (1000:success) |
| msg | String | Interface returns status information |
| data | Object | Response data object |
| - create\_time | Long | Creation timestamp |
| - uid | Integer | User ID |
| - team\_id | String | Team ID |
| - status | Integer | Task status: 1=queueing, 2=processing, 3=completed, 4=failed |
| - webhookUrl | String | Callback URL |
| - resolution | String | Video resolution |
| - file\_name | String | Output file name |
| - effect\_name | String | Effect name |
| - \_id | String | Document ID |
| - image\_url | String | Input image URL |
| - prompt | String | Animation prompt |
| - negative\_prompt | String | Negative prompt |
| - extend\_prompt | Boolean | Whether extended prompts were used |
| - audio\_type | Integer | Audio type used |
| - audio\_url | String | Audio URL used |
| - deduction\_credit | Integer | Credits deducted |
| - effect\_code | String | Effect code used |
**Example**
**Body**
```json
{
"image_url": "https://drz0f01yeq1cx.cloudfront.net/1753772478686-9524-b6e4169bb1b44d5d8361936b3f6eddb8.png",
"prompt": "Animate this image with smooth camera movement and subtle object motion.",
"negative_prompt": "blurry, distorted hands, missing fingers, unnatural pose, double hands, extra limbs, bad anatomy, low quality, cartoonish, exaggerated features, open mouth, aggressive expression, modern clothing, pixelated, vibrant colors, overexposed, flickering, blurry details, subtitles, logo, style, artwork, painting, picture, static, overall grayish, worst quality, JPEG compression artifacts, ugly, incomplete, extra fingers, poorly drawn hands, poorly drawn face, deformed, disfigured, malformed limbs, fused fingers, static characters, messy background, three legs, crowded background, walking backwards",
"extend_prompt": true,
"resolution": "4k",
"audio_url": "https://drz0f01yeq1cx.cloudfront.net/1753772497950-9213-1749809724426audio.mp3",
"audio_type": 2,
"video_length": 10,
"is_premium_model": true,
"effect_code": "squish_89244231312",
"webhookurl": "http://localhost:3000/demo"
}
```
**Request**
```bash cURL
curl --location 'https://openapi.akool.com/api/open/v4/image2Video/createBySourcePrompt' \
--header 'Authorization: Bearer {{token}}' \
--header 'Content-Type: application/json' \
--data '{
"image_url": "https://drz0f01yeq1cx.cloudfront.net/1753772478686-9524-b6e4169bb1b44d5d8361936b3f6eddb8.png",
"prompt": "Animate this image with smooth camera movement and subtle object motion.",
"negative_prompt": "blurry, distorted hands, missing fingers, unnatural pose, double hands, extra limbs, bad anatomy, low quality, cartoonish, exaggerated features, open mouth, aggressive expression, modern clothing, pixelated, vibrant colors, overexposed, flickering, blurry details, subtitles, logo, style, artwork, painting, picture, static, overall grayish, worst quality, JPEG compression artifacts, ugly, incomplete, extra fingers, poorly drawn hands, poorly drawn face, deformed, disfigured, malformed limbs, fused fingers, static characters, messy background, three legs, crowded background, walking backwards",
"extend_prompt": true,
"resolution": "4k",
"audio_url": "https://drz0f01yeq1cx.cloudfront.net/1753772497950-9213-1749809724426audio.mp3",
"audio_type": 2,
"video_length": 10,
"is_premium_model": true,
"effect_code": "squish_89244231312",
"webhookurl": "http://localhost:3000/demo"
}'
```
```java Java
OkHttpClient client = new OkHttpClient().newBuilder()
.build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n \"image_url\": \"https://drz0f01yeq1cx.cloudfront.net/1753772478686-9524-b6e4169bb1b44d5d8361936b3f6eddb8.png\",\n \"prompt\": \"Animate this image with smooth camera movement and subtle object motion.\",\n \"negative_prompt\": \"blurry, distorted hands, missing fingers, unnatural pose, double hands, extra limbs, bad anatomy, low quality, cartoonish, exaggerated features, open mouth, aggressive expression, modern clothing, pixelated, vibrant colors, overexposed, flickering, blurry details, subtitles, logo, style, artwork, painting, picture, static, overall grayish, worst quality, JPEG compression artifacts, ugly, incomplete, extra fingers, poorly drawn hands, poorly drawn face, deformed, disfigured, malformed limbs, fused fingers, static characters, messy background, three legs, crowded background, walking backwards\",\n \"extend_prompt\": true,\n \"resolution\": \"4k\",\n \"audio_url\": \"https://drz0f01yeq1cx.cloudfront.net/1753772497950-9213-1749809724426audio.mp3\",\n \"audio_type\": 2,\n \"video_length\": 10,\n \"is_premium_model\": true,\n \"effect_code\": \"squish_89244231312\",\n \"webhookurl\": \"http://localhost:3000/demo\"\n}");
Request request = new Request.Builder()
.url("https://openapi.akool.com/api/open/v4/image2Video/createBySourcePrompt")
.method("POST", body)
.addHeader("Authorization", "Bearer {{token}}")
.addHeader("Content-Type", "application/json")
.build();
Response response = client.newCall(request).execute();
```
```js Javascript
const myHeaders = new Headers();
myHeaders.append("Authorization", "Bearer {{token}}");
myHeaders.append("Content-Type", "application/json");
const raw = JSON.stringify({
"image_url": "https://drz0f01yeq1cx.cloudfront.net/1753772478686-9524-b6e4169bb1b44d5d8361936b3f6eddb8.png",
"prompt": "Animate this image with smooth camera movement and subtle object motion.",
"negative_prompt": "blurry, distorted hands, missing fingers, unnatural pose, double hands, extra limbs, bad anatomy, low quality, cartoonish, exaggerated features, open mouth, aggressive expression, modern clothing, pixelated, vibrant colors, overexposed, flickering, blurry details, subtitles, logo, style, artwork, painting, picture, static, overall grayish, worst quality, JPEG compression artifacts, ugly, incomplete, extra fingers, poorly drawn hands, poorly drawn face, deformed, disfigured, malformed limbs, fused fingers, static characters, messy background, three legs, crowded background, walking backwards",
"extend_prompt": true,
"resolution": "4k",
"audio_url": "https://drz0f01yeq1cx.cloudfront.net/1753772497950-9213-1749809724426audio.mp3",
"audio_type": 2,
"video_length": 10,
"is_premium_model": true,
"effect_code": "squish_89244231312",
"webhookurl": "http://localhost:3000/demo"
});
const requestOptions = {
method: "POST",
headers: myHeaders,
body: raw,
redirect: "follow"
};
fetch("https://openapi.akool.com/api/open/v4/image2Video/createBySourcePrompt", requestOptions)
.then((response) => response.text())
.then((result) => console.log(result))
.catch((error) => console.error(error));
```
```php PHP
'Bearer {{token}}',
'Content-Type' => 'application/json'
];
$body = '{
"image_url": "https://drz0f01yeq1cx.cloudfront.net/1753772478686-9524-b6e4169bb1b44d5d8361936b3f6eddb8.png",
"prompt": "Animate this image with smooth camera movement and subtle object motion.",
"negative_prompt": "blurry, distorted hands, missing fingers, unnatural pose, double hands, extra limbs, bad anatomy, low quality, cartoonish, exaggerated features, open mouth, aggressive expression, modern clothing, pixelated, vibrant colors, overexposed, flickering, blurry details, subtitles, logo, style, artwork, painting, picture, static, overall grayish, worst quality, JPEG compression artifacts, ugly, incomplete, extra fingers, poorly drawn hands, poorly drawn face, deformed, disfigured, malformed limbs, fused fingers, static characters, messy background, three legs, crowded background, walking backwards",
"extend_prompt": true,
"resolution": "4k",
"audio_url": "https://drz0f01yeq1cx.cloudfront.net/1753772497950-9213-1749809724426audio.mp3",
"audio_type": 2,
"video_length": 10,
"is_premium_model": true,
"effect_code": "squish_89244231312",
"webhookurl": "http://localhost:3000/demo"
}';
$request = new Request('POST', 'https://openapi.akool.com/api/open/v4/image2Video/createBySourcePrompt', $headers, $body);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();
?>
```
```python Python
import requests
import json
url = "https://openapi.akool.com/api/open/v4/image2Video/createBySourcePrompt"
payload = json.dumps({
"image_url": "https://drz0f01yeq1cx.cloudfront.net/1753772478686-9524-b6e4169bb1b44d5d8361936b3f6eddb8.png",
"prompt": "Animate this image with smooth camera movement and subtle object motion.",
"negative_prompt": "blurry, distorted hands, missing fingers, unnatural pose, double hands, extra limbs, bad anatomy, low quality, cartoonish, exaggerated features, open mouth, aggressive expression, modern clothing, pixelated, vibrant colors, overexposed, flickering, blurry details, subtitles, logo, style, artwork, painting, picture, static, overall grayish, worst quality, JPEG compression artifacts, ugly, incomplete, extra fingers, poorly drawn hands, poorly drawn face, deformed, disfigured, malformed limbs, fused fingers, static characters, messy background, three legs, crowded background, walking backwards",
"extend_prompt": true,
"resolution": "4k",
"audio_url": "https://drz0f01yeq1cx.cloudfront.net/1753772497950-9213-1749809724426audio.mp3",
"audio_type": 2,
"video_length": 10,
"is_premium_model": true,
"effect_code": "squish_89244231312",
"webhookurl": "http://localhost:3000/demo"
})
headers = {
'Authorization': 'Bearer {{token}}',
'Content-Type': 'application/json'
}
response = requests.request("POST", url, headers=headers, data=payload)
print(response.text)
```
**Response**
```json
{
"code": 1000,
"msg": "OK",
"data": {
"create_time": 1754362985482,
"uid": 101400,
"team_id": "6805fb69e92d9edc7ca0b409",
"status": 1,
"webhookUrl": "http://localhost:3000/demo",
"resolution": "4k",
"file_name": "Image2Video_Animate this image with .mp4",
"effect_name": "Squish",
"_id": "689174694b4dbdd4ab3d28c9",
"image_url": "https://drz0f01yeq1cx.cloudfront.net/1753772478686-9524-b6e4169bb1b44d5d8361936b3f6eddb8.png",
"prompt": "Animate this image with smooth camera movement and subtle object motion.",
"negative_prompt": "blurry, distorted hands, missing fingers, unnatural pose, double hands, extra limbs, bad anatomy, low quality, cartoonish, exaggerated features, open mouth, aggressive expression, modern clothing, pixelated, vibrant colors, overexposed, flickering, blurry details, subtitles, logo, style, artwork, painting, picture, static, overall grayish, worst quality, JPEG compression artifacts, ugly, incomplete, extra fingers, poorly drawn hands, poorly drawn face, deformed, disfigured, malformed limbs, fused fingers, static characters, messy background, three legs, crowded background, walking backwards",
"extend_prompt": true,
"audio_type": 2,
"audio_url": "https://drz0f01yeq1cx.cloudfront.net/1753772497950-9213-1749809724426audio.mp3",
"deduction_credit": 60,
"effect_code": "squish_89244231312"
}
}
```
## Get Image to Video Results
```
POST https://openapi.akool.com/api/open/v4/image2Video/resultsByIds
```
**Request Headers**
| **Parameter** | **Value** | **Description** |
| ------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------- |
| Authorization | Bearer `{token}` | Your API Key used for request authorization.[getToken](https://docs.akool.com/authentication/usage#get-the-token) |
**Body Attributes**
| **Parameter** | **Type** | **Required** | **Description** |
| ------------- | -------- | ------------ | -------------------------------- |
| \_ids | String | true | Multiple IDs separated by commas |
**Response Attributes**
| **Parameter** | **Type** | **Description** |
| -------------------- | -------- | ------------------------------------------------------- |
| code | Integer | Interface returns business status code (1000:success) |
| msg | String | Interface returns status information |
| data | Object | Response data object |
| - result | Array | Array of result objects |
| -- \_id | String | Document ID |
| -- create\_time | Long | Creation timestamp |
| -- uid | Integer | User ID |
| -- team\_id | String | Team ID |
| -- update\_time | Long | Last update time/completion time |
| -- video\_duration | Number | Actual video duration |
| -- webhookUrl | String | Callback URL |
| -- file\_name | String | File name |
| -- effect\_name | String | Effect name |
| -- image\_url | String | Image URL |
| -- prompt | String | Prompt text |
| -- resolution | String | Resolution |
| -- audio\_type | Integer | Audio type |
| -- audio\_url | String | Audio URL |
| -- deduction\_credit | Integer | Actual credits deducted |
| -- effect\_code | String | Effect code |
| -- video\_url | String | Generated video URL |
| -- status | Integer | Status: 1=queueing, 2=processing, 3=completed, 4=failed |
| -- only\_add\_audio | Boolean | Whether only audio was added |
**Example**
**Body**
```json
{
"_ids": "68919a464b4dbdd4ab3d3034,6891a07f5d612f78c9204f1c"
}
```
**Request**
```bash cURL
curl --location 'https://openapi.akool.com/api/open/v4/image2Video/resultsByIds' \
--header 'Authorization: Bearer {{token}}' \
--header 'Content-Type: application/json' \
--data '{
"_ids": "68919a464b4dbdd4ab3d3034,6891a07f5d612f78c9204f1c"
}'
```
```java Java
OkHttpClient client = new OkHttpClient().newBuilder()
.build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n \"_ids\": \"68919a464b4dbdd4ab3d3034,6891a07f5d612f78c9204f1c\"\n}");
Request request = new Request.Builder()
.url("https://openapi.akool.com/api/open/v4/image2Video/resultsByIds")
.method("POST", body)
.addHeader("Authorization", "Bearer {{token}}")
.addHeader("Content-Type", "application/json")
.build();
Response response = client.newCall(request).execute();
```
```js Javascript
const myHeaders = new Headers();
myHeaders.append("Authorization", "Bearer {{token}}");
myHeaders.append("Content-Type", "application/json");
const raw = JSON.stringify({
"_ids": "68919a464b4dbdd4ab3d3034,6891a07f5d612f78c9204f1c"
});
const requestOptions = {
method: "POST",
headers: myHeaders,
body: raw,
redirect: "follow"
};
fetch("https://openapi.akool.com/api/open/v4/image2Video/resultsByIds", requestOptions)
.then((response) => response.text())
.then((result) => console.log(result))
.catch((error) => console.error(error));
```
```php PHP
'Bearer {{token}}',
'Content-Type' => 'application/json'
];
$body = '{
"_ids": "68919a464b4dbdd4ab3d3034,6891a07f5d612f78c9204f1c"
}';
$request = new Request('POST', 'https://openapi.akool.com/api/open/v4/image2Video/resultsByIds', $headers, $body);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();
?>
```
```python Python
import requests
import json
url = "https://openapi.akool.com/api/open/v4/image2Video/resultsByIds"
payload = json.dumps({
"_ids": "68919a464b4dbdd4ab3d3034,6891a07f5d612f78c9204f1c"
})
headers = {
'Authorization': 'Bearer {{token}}',
'Content-Type': 'application/json'
}
response = requests.request("POST", url, headers=headers, data=payload)
print(response.text)
```
**Response**
```json
{
"code": 1000,
"msg": "OK",
"data": {
"result": [
{
"_id": "6891a2295d612f78c9204f77",
"create_time": 1754374697629,
"uid": 101400,
"team_id": "6805fb69e92d9edc7ca0b409",
"update_time": 1754374394023,
"video_duration": 5.063,
"webhookUrl": "http://localhost:3000/demo",
"file_name": "Image2Video_Animate this image with .mp4",
"effect_name": "Squish",
"image_url": "https://drz0f01yeq1cx.cloudfront.net/1753772478686-9524-b6e4169bb1b44d5d8361936b3f6eddb8.png",
"prompt": "Animate this image with smooth camera movement and subtle object motion.",
"resolution": "4k",
"audio_type": 2,
"audio_url": "https://drz0f01yeq1cx.cloudfront.net/1753772497950-9213-1749809724426audio.mp3",
"deduction_credit": 5,
"effect_code": "squish_89244231312",
"status": 1,
"only_add_audio": true
},
{
"_id": "6891abe782f7cd2a890c44ba",
"create_time": 1754377191100,
"uid": 101400,
"team_id": "6805fb69e92d9edc7ca0b409",
"sub_type": 1501,
"video_duration": 5.063,
"webhookUrl": "http://localhost:3000/demo",
"file_name": "Image2Video_Animate this image with .mp4",
"effect_name": "Squish",
"update_time": 1754377293090,
"image_url": "https://drz0f01yeq1cx.cloudfront.net/1753772478686-9524-b6e4169bb1b44d5d8361936b3f6eddb8.png",
"prompt": "Animate this image with smooth camera movement and subtle object motion.",
"resolution": "4k",
"audio_type": 2,
"audio_url": "https://drz0f01yeq1cx.cloudfront.net/1753772497950-9213-1749809724426audio.mp3",
"deduction_credit": 30,
"effect_code": "squish_89244231312",
"video_url": "https://d2qf6ukcym4kn9.cloudfront.net/1754377291791-1423.mp4",
"status": 3,
"only_add_audio": false
}
]
}
}
```
## Get Available Effects
```
GET https://openapi.akool.com/api/open/v4/image2Video/effects
```
**Request Headers**
| **Parameter** | **Value** | **Description** |
| ------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------- |
| Authorization | Bearer `{token}` | Your API Key used for request authorization.[getToken](https://docs.akool.com/authentication/usage#get-the-token) |
**Response Attributes**
| **Parameter** | **Type** | **Description** |
| --------------- | -------- | ----------------------------------------------------- |
| code | Integer | Interface returns business status code (1000:success) |
| msg | String | Interface returns status information |
| data | Object | Response data object |
| - result | Array | Array of effect objects |
| -- \_id | String | Effect document ID |
| -- create\_time | Long | Creation timestamp |
| -- logo | String | Effect logo URL |
| -- name | String | Effect name |
| -- video\_url | String | Effect preview video URL |
| -- effect\_code | String | Effect code |
| - count | Integer | Total number of effects |
**Request**
```bash cURL
curl --location 'https://openapi.akool.com/api/open/v4/image2Video/effects' \
--header 'Authorization: Bearer {{token}}'
```
```java Java
OkHttpClient client = new OkHttpClient().newBuilder()
.build();
Request request = new Request.Builder()
.url("https://openapi.akool.com/api/open/v4/image2Video/effects")
.method("GET", null)
.addHeader("Authorization", "Bearer {{token}}")
.build();
Response response = client.newCall(request).execute();
```
```js Javascript
const myHeaders = new Headers();
myHeaders.append("Authorization", "Bearer {{token}}");
const requestOptions = {
method: "GET",
headers: myHeaders,
redirect: "follow"
};
fetch("https://openapi.akool.com/api/open/v4/image2Video/effects", requestOptions)
.then((response) => response.text())
.then((result) => console.log(result))
.catch((error) => console.error(error));
```
```php PHP
'Bearer {{token}}'
];
$request = new Request('GET', 'https://openapi.akool.com/api/open/v4/image2Video/effects', $headers);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();
?>
```
```python Python
import requests
url = "https://openapi.akool.com/api/open/v4/image2Video/effects"
headers = {
'Authorization': 'Bearer {{token}}'
}
response = requests.request("GET", url, headers=headers)
print(response.text)
```
**Response**
```json
{
"code": 1000,
"msg": "Success",
"data": {
"result": [
{
"_id": "687632b95a0f52799eeed701",
"create_time": 1752576694502,
"logo": "https://static.website-files.org/assets/Image_to_Video/Lora/Squish.png",
"name": "Squish",
"video_url": "https://static.website-files.org/assets/Image_to_Video/Lora/Squish.mp4",
"effect_code": "squish_89244231312"
},
{
"_id": "687632ba5a0f52799eeed887",
"create_time": 1752576694502,
"logo": "https://static.website-files.org/assets/Image_to_Video/Lora/Cakeify.png",
"name": "Cakeify",
"video_url": "https://static.website-files.org/assets/Image_to_Video/Lora/Cakeify.mp4",
"effect_code": "cakeify_24743216"
},
{
"_id": "687632bc5a0f52799eeed929",
"create_time": 1752576694502,
"logo": "https://static.website-files.org/assets/Image_to_Video/Lora/Samurai.png",
"name": "Samurai",
"video_url": "https://static.website-files.org/assets/Image_to_Video/Lora/Samurai.mp4",
"effect_code": "samurai_99757865"
}
],
"count": 10
}
}
```
## Update Video Audio
```
POST https://openapi.akool.com/api/open/v4/image2Video/updateVideoAudio
```
**Request Headers**
| **Parameter** | **Value** | **Description** |
| ------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------- |
| Authorization | Bearer `{token}` | Your API Key used for request authorization.[getToken](https://docs.akool.com/authentication/usage#get-the-token) |
**Body Attributes**
| **Parameter** | **Type** | **Required** | **Description** |
| -------------- | -------- | ------------ | ---------------------------------------- |
| pre\_video\_id | String | true | Image to Video result \_id |
| audio\_url | String | true | Audio URL, required when audio\_type = 2 |
| audio\_type | Integer | true | 1 = AI Generate, 2 = user custom upload |
**Response Attributes**
| **Parameter** | **Type** | **Description** |
| ------------------- | -------- | ------------------------------------------------------- |
| code | Integer | Interface returns business status code (1000:success) |
| msg | String | Interface returns status information |
| data | Object | Response data object |
| - create\_time | Long | Creation timestamp |
| - uid | Integer | User ID |
| - team\_id | String | Team ID |
| - update\_time | Long | Last update time |
| - video\_duration | Number | Video duration |
| - webhookUrl | String | Callback URL |
| - resolution | String | Resolution |
| - file\_name | String | File name |
| - effect\_name | String | Effect name |
| - \_id | String | Document ID |
| - pre\_video\_id | String | Original video ID |
| - image\_url | String | Image URL |
| - prompt | String | Prompt text |
| - negative\_prompt | String | Negative prompt |
| - extend\_prompt | Boolean | Whether extended prompts were used |
| - audio\_type | Integer | Audio type |
| - audio\_url | String | Audio URL |
| - deduction\_credit | Integer | Credits deducted |
| - effect\_code | String | Effect code |
| - status | Integer | Status: 1=queueing, 2=processing, 3=completed, 4=failed |
| - only\_add\_audio | Boolean | Whether only audio was added |
**Example**
**Body**
```json
{
"pre_video_id": "6890830af27dfad2a3e6062d",
"audio_url": "https://drz0f01yeq1cx.cloudfront.net/1753772497950-9213-1749809724426audio.mp3",
"audio_type": 2
}
```
**Request**
```bash cURL
curl --location 'https://openapi.akool.com/api/open/v4/image2Video/updateVideoAudio' \
--header 'Authorization: Bearer {{token}}' \
--header 'Content-Type: application/json' \
--data '{
"pre_video_id": "6890830af27dfad2a3e6062d",
"audio_url": "https://drz0f01yeq1cx.cloudfront.net/1753772497950-9213-1749809724426audio.mp3",
"audio_type": 2
}'
```
```java Java
OkHttpClient client = new OkHttpClient().newBuilder()
.build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n \"pre_video_id\": \"6890830af27dfad2a3e6062d\",\n \"audio_url\": \"https://drz0f01yeq1cx.cloudfront.net/1753772497950-9213-1749809724426audio.mp3\",\n \"audio_type\": 2\n}");
Request request = new Request.Builder()
.url("https://openapi.akool.com/api/open/v4/image2Video/updateVideoAudio")
.method("POST", body)
.addHeader("Authorization", "Bearer {{token}}")
.addHeader("Content-Type", "application/json")
.build();
Response response = client.newCall(request).execute();
```
```js Javascript
const myHeaders = new Headers();
myHeaders.append("Authorization", "Bearer {{token}}");
myHeaders.append("Content-Type", "application/json");
const raw = JSON.stringify({
"pre_video_id": "6890830af27dfad2a3e6062d",
"audio_url": "https://drz0f01yeq1cx.cloudfront.net/1753772497950-9213-1749809724426audio.mp3",
"audio_type": 2
});
const requestOptions = {
method: "POST",
headers: myHeaders,
body: raw,
redirect: "follow"
};
fetch("https://openapi.akool.com/api/open/v4/image2Video/updateVideoAudio", requestOptions)
.then((response) => response.text())
.then((result) => console.log(result))
.catch((error) => console.error(error));
```
```php PHP
'Bearer {{token}}',
'Content-Type' => 'application/json'
];
$body = '{
"pre_video_id": "6890830af27dfad2a3e6062d",
"audio_url": "https://drz0f01yeq1cx.cloudfront.net/1753772497950-9213-1749809724426audio.mp3",
"audio_type": 2
}';
$request = new Request('POST', 'https://openapi.akool.com/api/open/v4/image2Video/updateVideoAudio', $headers, $body);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();
?>
```
```python Python
import requests
import json
url = "https://openapi.akool.com/api/open/v4/image2Video/updateVideoAudio"
payload = json.dumps({
"pre_video_id": "6890830af27dfad2a3e6062d",
"audio_url": "https://drz0f01yeq1cx.cloudfront.net/1753772497950-9213-1749809724426audio.mp3",
"audio_type": 2
})
headers = {
'Authorization': 'Bearer {{token}}',
'Content-Type': 'application/json'
}
response = requests.request("POST", url, headers=headers, data=payload)
print(response.text)
```
**Response**
```json
{
"code": 1000,
"msg": "OK",
"data": {
"create_time": 1754374697629,
"uid": 101400,
"team_id": "6805fb69e92d9edc7ca0b409",
"update_time": 1754374394023,
"video_duration": 5.063,
"webhookUrl": "http://localhost:3000/demo",
"resolution": "4k",
"file_name": "Image2Video_Animate this image with .mp4",
"effect_name": "Squish",
"_id": "6891a2295d612f78c9204f77",
"pre_video_id": "6891a07f5d612f78c9204f1c",
"image_url": "https://drz0f01yeq1cx.cloudfront.net/1753772478686-9524-b6e4169bb1b44d5d8361936b3f6eddb8.png",
"prompt": "Animate this image with smooth camera movement and subtle object motion.",
"negative_prompt": "",
"extend_prompt": false,
"audio_type": 2,
"audio_url": "https://drz0f01yeq1cx.cloudfront.net/1753772497950-9213-1749809724426audio.mp3",
"deduction_credit": 5,
"effect_code": "squish_89244231312",
"status": 1,
"only_add_audio": true
}
}
```
## Delete Videos
```
POST https://openapi.akool.com/api/open/v4/image2Video/delbyids
```
**Request Headers**
| **Parameter** | **Value** | **Description** |
| ------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------- |
| Authorization | Bearer `{token}` | Your API Key used for request authorization.[getToken](https://docs.akool.com/authentication/usage#get-the-token) |
**Body Attributes**
| **Parameter** | **Type** | **Required** | **Description** |
| ------------- | -------- | ------------ | -------------------------------- |
| \_ids | String | true | Multiple IDs separated by commas |
**Response Attributes**
| **Parameter** | **Type** | **Description** |
| ------------------- | -------- | ----------------------------------------------------- |
| code | Integer | Interface returns business status code (1000:success) |
| msg | String | Interface returns status information |
| data | Object | Response data object |
| - successIds | Array | Successfully deleted video IDs |
| - noPermissionItems | Array | Failed deletion information list |
| -- \_id | String | Failed deletion video ID |
| -- msg | String | Failure reason |
**Example**
**Body**
```json
{
"_ids": "68919a464b4dbdd4ab3d3034,6891a07f5d612f78c9204f1c,6891a2295d612f78c9204f77"
}
```
**Request**
```bash cURL
curl --location 'https://openapi.akool.com/api/open/v4/image2Video/delbyids' \
--header 'Authorization: Bearer {{token}}' \
--header 'Content-Type: application/json' \
--data '{
"_ids": "68919a464b4dbdd4ab3d3034,6891a07f5d612f78c9204f1c,6891a2295d612f78c9204f77"
}'
```
```java Java
OkHttpClient client = new OkHttpClient().newBuilder()
.build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n \"_ids\": \"68919a464b4dbdd4ab3d3034,6891a07f5d612f78c9204f1c,6891a2295d612f78c9204f77\"\n}");
Request request = new Request.Builder()
.url("https://openapi.akool.com/api/open/v4/image2Video/delbyids")
.method("POST", body)
.addHeader("Authorization", "Bearer {{token}}")
.addHeader("Content-Type", "application/json")
.build();
Response response = client.newCall(request).execute();
```
```js Javascript
const myHeaders = new Headers();
myHeaders.append("Authorization", "Bearer {{token}}");
myHeaders.append("Content-Type", "application/json");
const raw = JSON.stringify({
"_ids": "68919a464b4dbdd4ab3d3034,6891a07f5d612f78c9204f1c,6891a2295d612f78c9204f77"
});
const requestOptions = {
method: "POST",
headers: myHeaders,
body: raw,
redirect: "follow"
};
fetch("https://openapi.akool.com/api/open/v4/image2Video/delbyids", requestOptions)
.then((response) => response.text())
.then((result) => console.log(result))
.catch((error) => console.error(error));
```
```php PHP
'Bearer {{token}}',
'Content-Type' => 'application/json'
];
$body = '{
"_ids": "68919a464b4dbdd4ab3d3034,6891a07f5d612f78c9204f1c,6891a2295d612f78c9204f77"
}';
$request = new Request('POST', 'https://openapi.akool.com/api/open/v4/image2Video/delbyids', $headers, $body);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();
?>
```
```python Python
import requests
import json
url = "https://openapi.akool.com/api/open/v4/image2Video/delbyids"
payload = json.dumps({
"_ids": "68919a464b4dbdd4ab3d3034,6891a07f5d612f78c9204f1c,6891a2295d612f78c9204f77"
})
headers = {
'Authorization': 'Bearer {{token}}',
'Content-Type': 'application/json'
}
response = requests.request("POST", url, headers=headers, data=payload)
print(response.text)
```
**Response**
```json
{
"code": 1000,
"msg": "Delete successfully",
"data": {
"successIds": [
"6882f4c10529ae771e71531d"
],
"noPermissionItems": [
{
"_id": "6881cd86618fa41c89557b0c",
"msg": "video resource is processing, please try again later"
}
]
}
}
```
# null
Source: https://docstest.akool.io/ai-tools-suite/jarvis-moderator
# Overview
Automate content moderation reduces the cost of your image, video, text, and voice moderation by accurately detecting inappropriate content.
Jarvis Moderator provides services through open application programming interfaces (APIs). You can obtain the inference result by calling APIs. It helps you build an intelligent service system and improves service efficiency.
* A software tool such as curl and Postman
These are good options if you are more comfortable writing code, HTTP requests, and API calls. For details, see Using Postman to Call Jarvis.
# Internationalization labels
The following content will be subject to review and detection to ensure compliance with relevant laws, regulations, and platform policies:
1. Advertising: Detects malicious advertising and redirection content to prevent users from being led to unsafe or inappropriate sites.
2. Violent Content: Detects violent or terrorist content to prevent the dissemination of harmful information.
3. Political Content: Reviews political content to ensure that it does not involve sensitive or inflammatory political information.
4. Specified Speech: Detects specified speech or voice content to identify and manage audio that meets certain conditions.
5. Specified Lyrics: Detects specified lyrics content to prevent the spread of inappropriate or harmful lyrics.
6. Sexual Content: Reviews content related to sexual behavior or sexual innuendo to protect users from inappropriate information.
7. Moaning Sounds: Detects sounds related to sexual activity, such as moaning, to prevent the spread of such audio.
8. Contraband: Identifies and blocks all illegal or prohibited content.
9. Profane Language: Reviews and filters content containing profanity or vulgar language.
10. Religious Content: Reviews religious content to avoid controversy or offense to specific religious beliefs.
11. Cyberbullying: Detects cyberbullying behavior to prevent such content from harming users.
12. Harmful or Inappropriate Content: Reviews and manages harmful or inappropriate content to maintain a safe and positive environment on the platform.
13. Silent Audio: Detects silent audio content to identify and address potential technical issues or other anomalies.
14. Customized Content: Allows users to define and review specific types of content according to business needs or compliance requirements.
This content will be thoroughly detected by our review system to ensure that all content on the platform meets the relevant standards and regulations.
# Subscribing to the Service
**NOTE:**
This service is available only to enterprise users now.
To subscribe to Jarvis Moderator, perform the following steps:
1. Register an AKOOL account.
2. Then click the picture icon in the upper right corner of the website, and click the “APl Credentials” function to set the key pair (clientId, clientSecret) used when accessing the API and save it.
3. Use the secret key pair just saved to send the api interface to obtain the access token.
### Jarvis Moderator
```
POST https://openapitest.akool.com/api/open/v3/content/analysis/sentiment
```
**Request Headers**
| **Parameter** | **Value** | **Description** |
| ------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Authorization | Bearer token | Your API Key used for request authorization. You can get from [https://openapitest.akool.com/api/open/v3/getToken](https://openapitest.akool.com/api/open/v3/getToken) api. |
**Body Attributes**
| **Parameter** | **Type** | **Value** | **Description** |
| ------------- | -------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| content | String | | url or text， when the content is a image, video, or audio, a url must be provided. When the content provided is text, it can be either text content or a url. |
| type | Number | | 1: image 2:video 3: auido 4: text |
| language | String | Optional | When type=2 or 3 or 4, it is best to provide the language to ensure the accuracy of the results。 Supplying the input language in ISO-639-1 format |
| webhookUrl | String | Optional | Callback url address based on HTTP request. |
| input | String | Optional | The user defines the content to be detected in words |
We restrict image to 20MB. we currently support PNG (.png), JPEG (.jpeg and .jpg), WEBP (.webp), and non-animated GIF (.gif).
We restrict audio to 25MB, 60minute we currently support .flac, .mp3, .mp4, .mpeg, .mpga, .m4a, .ogg, .wav, .webm
We restrict video to 1024MB, resolution limited to 1080p. we currently support .mp4, .avi
When the content provided is text, it can be either text content or a url. If it is url, we currently support .txt, .docx, .xml, .pdf, .csv, .md, .json
ISO-639-1: [https://en.wikipedia.org/wiki/List\_of\_ISO\_639\_language\_codes](https://en.wikipedia.org/wiki/List_of_ISO_639_language_codes)
**Response Attributes**
| **Parameter** | **Type** | **Value** | **Description** |
| ------------- | -------- | ---------------------------- | -------------------------------------------------------------------------------------------------------------- |
| code | int | 1000 | Interface returns business status code(1000:success) |
| msg | String | | Interface returns status information |
| data | Object | `{ "_id": "", "status": 1 }` | `_id`: Interface returns data, status: the status of video： \[1:queueing, 2:processing, 3:completed, 4:failed] |
**Example**
**Body**
```json
{
"type":1, // 1:image 2:video 3: auido 4:text
"content":"https://drz0f01yeq1cx.cloudfront.net/1714023431475-food.jpg",
"webhookUrl":"http://localhost:3004/api/v3/webhook",
"input": "xxx" // The user defines the content to be detected in words
}
```
**Request**
```bash cURL
curl --location 'https://openapitest.akool.com/api/open/v3/content/analysis/sentiment' \
--header 'Authorization: Bearer token' \
--header 'Content-Type: application/json' \
--data '{
"type":1,
"content":"https://drz0f01yeq1cx.cloudfront.net/1714023431475-food.jpg",
}'
```
```java Java
OkHttpClient client = new OkHttpClient().newBuilder()
.build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n \n \"type\":1,\n \"content\":\"https://drz0f01yeq1cx.cloudfront.net/1714023431475-food.jpg\"\n\n}");
Request request = new Request.Builder()
.url("https://openapitest.akool.com/api/open/v3/content/analysis/sentiment")
.method("POST", body)
.addHeader("Authorization", "Bearer token")
.addHeader("Content-Type", "application/json")
.build();
Response response = client.newCall(request).execute();
```
```js Javascript
const myHeaders = new Headers();
myHeaders.append("Authorization", "Bearer token");
myHeaders.append("Content-Type", "application/json");
const raw = JSON.stringify({
"type": 1,
"content": "https://drz0f01yeq1cx.cloudfront.net/1714023431475-food.jpg"
});
const requestOptions = {
method: "POST",
headers: myHeaders,
body: raw,
redirect: "follow"
};
fetch("https://openapitest.akool.com/api/open/v3/content/analysis/sentiment", requestOptions)
.then((response) => response.text())
.then((result) => console.log(result))
.catch((error) => console.error(error));
```
```php PHP
'Bearer token',
'Content-Type' => 'application/json'
];
$body = '{
"type": 1,
"content": "https://drz0f01yeq1cx.cloudfront.net/1714023431475-food.jpg"
}';
$request = new Request('POST', 'https://openapitest.akool.com/api/open/v3/content/analysis/sentiment', $headers, $body);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();
```
```python Python
import requests
import json
url = "https://openapitest.akool.com/api/open/v3/content/analysis/sentiment"
payload = json.dumps({
"type": 1,
"content": "https://drz0f01yeq1cx.cloudfront.net/1714023431475-food.jpg"
})
headers = {
'Authorization': 'Bearer token',
'Content-Type': 'application/json'
}
response = requests.request("POST", url, headers=headers, data=payload)
print(response.text)
```
**Response**
```json
{
"code": 1000,
"msg": "OK",
"data": {
"create_time": 1710757900382,
"uid": 101690,
"type": 1,
"status": 1, // current status of content： 【1：queueing（The requested operation is being processed），2：processing（The requested operation is being processing），3：completed（The request operation has been processed successfully），4：failed（The request operation processing failed）】
"webhookUrl": "http://localhost:3007/api/open/v3/test/webhook",
"result": "",
"_id": "65f8180c24d9989e93dde3b6",
"__v": 0
}
}
```
### Get analysis Info Result
```
GET https://openapitest.akool.com/api/open/v3/content/analysis/infobyid?_id=662df7928ee006bf033b64bf
```
**Request Headers**
| **Parameter** | **Value** | **Description** |
| ------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Authorization | Bearer token | Your API Key used for request authorization. You can get from [https://openapitest.akool.com/api/open/v3/getToken](https://openapitest.akool.com/api/open/v3/getToken) api. |
**Query Attributes**
| **Parameter** | **Type** | **Value** | **Description** |
| ------------- | -------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| \_id | String | NULL | video db id: You can get it based on the `_id` field returned by [https://openapitest.akool.com/api/open/v3/content/analysis/sentiment](https://openapitest.akool.com/api/open/v3/content/analysis/sentiment) . |
**Response Attributes**
| **Parameter** | **Type** | **Value** | **Description** |
| ------------- | -------- | ------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| code | int | 1000 | Interface returns business status code(1000:success) |
| msg | String | OK | Interface returns status information |
| data | Object | `{ status:1, _id:"", result:"", final_conclusion: "" }` | video\_status: the status of video：【1:queueing, 2:processing, 3:completed, 4:failed】 result: sentiment analysis result【Related information returned by the detection content】 final\_conclusion: final conclusion.【Non-Compliant、Compliant、Unknown】 \_id: Interface returns data |
**Example**
**Request**
```bash cURL
curl --location 'https://openapitest.akool.com/api/open/v3/content/analysis/infobyid?_id=662e20b93baa7aa53169a325' \
--header 'Authorization: Bearer token'
```
```java Java
OkHttpClient client = new OkHttpClient().newBuilder()
.build();
MediaType mediaType = MediaType.parse("text/plain");
RequestBody body = RequestBody.create(mediaType, "");
Request request = new Request.Builder()
.url("https://openapitest.akool.com/api/open/v3/content/analysis/infobyid?_id=662e20b93baa7aa53169a325")
.method("GET", body)
.addHeader("Authorization", "Bearer token")
.build();
Response response = client.newCall(request).execute();
```
```js Javascript
const myHeaders = new Headers();
myHeaders.append("Authorization", "Bearer token");
const requestOptions = {
method: "GET",
headers: myHeaders,
redirect: "follow"
};
fetch("https://openapitest.akool.com/api/open/v3/content/analysis/infobyid?_id=662e20b93baa7aa53169a325", requestOptions)
.then((response) => response.text())
.then((result) => console.log(result))
.catch((error) => console.error(error));
```
```php PHP
'Bearer token'
];
$request = new Request('GET', 'https://openapitest.akool.com/api/open/v3/content/analysis/infobyid?_id=662e20b93baa7aa53169a325', $headers);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();
```
```python Python
import requests
url = "https://openapitest.akool.com/api/open/v3/content/analysis/infobyid?_id=662e20b93baa7aa53169a325"
payload = {}
headers = {
'Authorization': 'Bearer token'
}
response = requests.request("GET", url, headers=headers, data=payload)
print(response.text)
```
**Response**
```json
{
"code": 1000,
"msg": "OK",
"data": {
"_id": "662e20b93baa7aa53169a325",
"uid": 100002,
"status": 3,
"result": "- violence: Presence of a person holding a handgun, which can be associated with violent content.\nResult: Non-Compliant",
"final_conclusion" :"Non-Compliant" // Non-Compliant、Compliant、Unknown
}
}
```
**Response Code Description**
Please note that if the value of the response code is not equal to 1000, the request is failed or wrong
| **Parameter** | **Value** | **Description** |
| ------------- | --------- | ---------------------------------------------------------------------------------- |
| code | 1000 | Success |
| code | 1003 | Parameter error or Parameter can not be empty |
| code | 1008 | The content you get does not exist |
| code | 1009 | You do not have permission to operate |
| code | 1101 | Invalid authorization or The request token has expired |
| code | 1102 | Authorization cannot be empty |
| code | 1200 | The account has been banned |
| code | 1201 | create audio error, please try again later |
| code | 1202 | The same video cannot be translated lipSync in the same language more than 1 times |
| code | 1203 | video should be with audio |
# lipSync
Source: https://docstest.akool.io/ai-tools-suite/lip-sync
The resources (image, video, voice) generated by our API are valid for 7 days.
Please save the relevant resources as soon as possible to prevent expiration.
### Create lipSync
```
POST https://openapi.akool.com/api/open/v3/content/video/lipsync
```
**Request Headers**
| **Parameter** | **Value** | **Description** |
| ------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Authorization | Bearer token | Your API Key used for request authorization. You can get from [https://openapi.akool.com/api/open/v3/getToken](https://openapi.akool.com/api/open/v3/getToken) api. |
**Body Attributes**
| **Parameter** | **Type** | **Value** | **Description** |
| ------------- | -------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| video\_url | String | | The video url address you want to lipsync, fps greater than 25 will affect the generated effect. It is recommended that the video fps be below 25. |
| audio\_url | String | | resource address of the audio,It is recommended that the audio length and video length be consistent, otherwise it will affect the generation effect. |
| webhookUrl | String | | Callback url address based on HTTP request. |
**Response Attributes**
| **Parameter** | **Type** | **Value** | **Description** |
| ------------- | -------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| code | int | 1000 | Interface returns business status code(1000:success) |
| msg | String | | Interface returns status information |
| data | Object | `{ "_id": "", "video_status": 1, "video": "" }` | `id`: Interface returns data, video\_status: the status of video： \[1:queueing, 2:processing, 3:completed, 4:failed], video: the url of Generated video |
**Example**
**Body**
```json
{
"video_url": "https://d11fbe263bhqij.cloudfront.net/agicontent/video/global_reach/Global_reach_EN_01.mp4",
"audio_url": "https://drz0f01yeq1cx.cloudfront.net/1712719410293-driving_audio_2.wav",
"webhookUrl": "https://openapitest.akool.com/api/open/v3/test/webhook"
}
```
**Request**
```bash cURL
curl --location 'https://openapi.akool.com/api/open/v3/content/video/lipsync' \
--header 'authorization: Bearer token' \
--header 'content-type: application/json' \
--data '{
"video_url": "https://d11fbe263bhqij.cloudfront.net/agicontent/video/global_reach/Global_reach_EN_01.mp4",
"audio_url": "https://drz0f01yeq1cx.cloudfront.net/1712719410293-driving_audio_2.wav",
"webhookUrl":"https://openapitest.akool.com/api/open/v3/test/webhook"
}'
```
```java Java
OkHttpClient client = new OkHttpClient().newBuilder()
.build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n \"video_url\": \"https://d11fbe263bhqij.cloudfront.net/agicontent/video/global_reach/Global_reach_EN_01.mp4\",\n \"audio_url\": \"https://drz0f01yeq1cx.cloudfront.net/1712719410293-driving_audio_2.wav\",\n \"webhookUrl\":\"https://openapitest.akool.com/api/open/v3/test/webhook\"\n}");
Request request = new Request.Builder()
.url("https://openapi.akool.com/api/open/v3/content/video/lipsync")
.method("POST", body)
.addHeader("authorization", "Bearer token")
.addHeader("content-type", "application/json")
.build();
Response response = client.newCall(request).execute();
```
```js Javascript
const myHeaders = new Headers();
myHeaders.append("authorization", "Bearer token");
myHeaders.append("content-type", "application/json");
const raw = JSON.stringify({
video_url:
"https://d11fbe263bhqij.cloudfront.net/agicontent/video/global_reach/Global_reach_EN_01.mp4",
audio_url:
"https://drz0f01yeq1cx.cloudfront.net/1712719410293-driving_audio_2.wav",
webhookUrl: "https://openapitest.akool.com/api/open/v3/test/webhook",
});
const requestOptions = {
method: "POST",
headers: myHeaders,
body: raw,
redirect: "follow",
};
fetch(
"https://openapi.akool.com/api/open/v3/content/video/lipsync",
requestOptions
)
.then((response) => response.text())
.then((result) => console.log(result))
.catch((error) => console.error(error));
```
```php PHP
'Bearer token',
'content-type' => 'application/json'
];
$body = '{
"video_url": "https://d11fbe263bhqij.cloudfront.net/agicontent/video/global_reach/Global_reach_EN_01.mp4",
"audio_url": "https://drz0f01yeq1cx.cloudfront.net/1712719410293-driving_audio_2.wav",
"webhookUrl": "https://openapitest.akool.com/api/open/v3/test/webhook"
}';
$request = new Request('POST', 'https://openapi.akool.com/api/open/v3/content/video/lipsync', $headers, $body);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();
```
```python Python
import requests
import json
url = "https://openapi.akool.com/api/open/v3/content/video/lipsync"
payload = json.dumps({
"video_url": "https://d11fbe263bhqij.cloudfront.net/agicontent/video/global_reach/Global_reach_EN_01.mp4",
"audio_url": "https://drz0f01yeq1cx.cloudfront.net/1712719410293-driving_audio_2.wav",
"webhookUrl": "https://openapitest.akool.com/api/open/v3/test/webhook"
})
headers = {
'authorization': 'Bearer token',
'content-type': 'application/json'
}
response = requests.request("POST", url, headers=headers, data=payload)
print(response.text)
```
**Response**
```json
{
"code": 1000,
"msg": "OK",
"data": {
"create_time": 1712720702523,
"uid": 100002,
"type": 9,
"from": 2,
"target_video": "https://d11fbe263bhqij.cloudfront.net/agicontent/video/global_reach/Global_reach_EN_01.mp4",
"faceswap_quality": 2,
"video_id": "8ddc4a27-d173-4cf5-aa37-13e340fed8f3",
"video_status": 1, // current status of video： 【1：queueing（The requested operation is being processed），2：processing（The requested operation is being processing），3：completed（The request operation has been processed successfully），4：failed（The request operation processing failed, the reason for the failure can be viewed in the video translation details.）】
"video_lock_duration": 11.7,
"deduction_lock_duration": 20,
"external_video": "",
"video": "", // the url of Generated video
"storage_loc": 1,
"input_audio": "https://drz0f01yeq1cx.cloudfront.net/1712719410293-driving_audio_2.wav",
"webhookUrl": "https://openapitest.akool.com/api/open/v3/test/webhook",
"task_id": "66160b3ee3ef778679dfd30f",
"lipsync": true,
"_id": "66160f989dfc997ac289037b",
"__v": 0
}
}
```
### Get Video Info Result
```
GET https://openapi.akool.com/api/open/v3/content/video/infobymodelid?video_model_id=66160f989dfc997ac289037b
```
**Request Headers**
| **Parameter** | **Value** | **Description** |
| ------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Authorization | Bearer token | Your API Key used for request authorization. You can get from [https://openapi.akool.com/api/open/v3/getToken](https://openapi.akool.com/api/open/v3/getToken) api. |
**Query Attributes**
| **Parameter** | **Type** | **Value** | **Description** |
| ---------------- | -------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| video\_model\_id | String | NULL | video db id: You can get it based on the `_id` field returned by [https://openapi.akool.com/api/open/v3/content/video/lipsync](https://openapi.akool.com/api/open/v3/content/video/lipsync) . |
**Response Attributes**
| **Parameter** | **Type** | **Value** | **Description** |
| ------------- | -------- | -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| code | int | 1000 | Interface returns business status code(1000:success) |
| msg | String | OK | Interface returns status information |
| data | Object | `{ video_status:1, _id:"", video:"" }` | video\_status: the status of video：【1:queueing, 2:processing, 3:completed, 4:failed】 video: Generated video resource url \_id: Interface returns data |
**Example**
**Request**
```bash cURL
curl --location 'http://openapi.akool.com/api/open/v3/content/video/infobymodelid?video_model_id=66160f989dfc997ac289037b' \
--header 'Authorization: Bearer token'
```
```java Java
OkHttpClient client = new OkHttpClient().newBuilder()
.build();
MediaType mediaType = MediaType.parse("text/plain");
RequestBody body = RequestBody.create(mediaType, "");
Request request = new Request.Builder()
.url("http://openapi.akool.com/api/open/v3/content/video/infobymodelid?video_model_id=66160f989dfc997ac289037b")
.method("GET", body)
.addHeader("Authorization", "Bearer token")
.build();
Response response = client.newCall(request).execute();
```
```js Javascript
const myHeaders = new Headers();
myHeaders.append("Authorization", "Bearer token");
const requestOptions = {
method: "GET",
headers: myHeaders,
redirect: "follow",
};
fetch(
"http://openapi.akool.com/api/open/v3/content/video/infobymodelid?video_model_id=66160f989dfc997ac289037b",
requestOptions
)
.then((response) => response.text())
.then((result) => console.log(result))
.catch((error) => console.error(error));
```
```php PHP
'Bearer token'
];
$request = new Request('GET', 'http://openapi.akool.com/api/open/v3/content/video/infobymodelid?video_model_id=66160f989dfc997ac289037b', $headers);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();
```
```python Python
import requests
url = "http://openapi.akool.com/api/open/v3/content/video/infobymodelid?video_model_id=66160f989dfc997ac289037b"
payload = {}
headers = {
'Authorization': 'Bearer token'
}
response = requests.request("GET", url, headers=headers, data=payload)
print(response.text)
```
**Response**
```json
{
"code": 1000,
"msg": "OK",
"data": {
"faceswap_quality": 2,
"storage_loc": 1,
"_id": "66160f989dfc997ac289037b",
"create_time": 1692242625334,
"uid": 378337,
"type": 2,
"from": 1,
"video_id": "788bcd2b-09bb-4e9c-b0f2-6d41ee5b2a67",
"video_lock_duration": 7.91,
"deduction_lock_duration": 10,
"video_status": 2, // current status of video： 【1：queueing（The requested operation is being processed），2：processing（The requested operation is being processing），3：completed（The request operation has been processed successfully），4：failed（The request operation processing failed, the reason for the failure can be viewed in the video translation details.）】
"external_video": "",
"video": "" // Generated video resource url
}
}
```
**Response Code Description**
{" "}
Please note that if the value of the response code is not equal to 1000, the request
is failed or wrong
| **Parameter** | **Value** | **Description** |
| ------------- | --------- | --------------------------------------------------------------------------------- |
| code | 1000 | Success |
| code | 1003 | Parameter error or Parameter can not beempty |
| code | 1008 | The content you get does not exist |
| code | 1009 | Youdo not have permission to operate |
| code | 1101 | Invalid authorization or Therequest token has expired |
| code | 1102 | Authorization cannot be empty |
| code | 1200 | The account has been banned |
| code | 1201 | create audio error, pleasetry again later |
| code | 1202 | The same video cannot be translated lipSync inthe same language more than 1 times |
| code | 1203 | video should be with audio |
| code | 1204 | Your video duration is exceed 60s! |
| code | 1205 | Create videoerror, please try again later |
| code | 1207 | The video you are using exceeds thesize limit allowed by the system by 300M |
| code | 1209 | Please upload a videoin another encoding format |
| code | 1210 | The video you are using exceeds thevalue allowed by the system by 60fp |
| code | 1211 | Create lipsync error, pleasetry again later |
# live avatar
Source: https://docstest.akool.io/ai-tools-suite/live-avatar
Real-time avatar
The resources (image, video, voice) generated by our API are valid for 7 days.
Please save the relevant resources as soon as possible to prevent expiration.
### Create session
```
POST https://openapi.akool.com/api/open/v3/liveAvatar/session/create
```
**Request Headers**
| **Parameter** | **Value** | **Description** |
| ------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Authorization | Bearer token | Your API Key used for request authorization. You can get from [https://openapi.akool.com/api/open/v3/getToken](https://openapi.akool.com/api/open/v3/getToken) api. |
**Body Attributes**
| **Parameter** | **Type** | **Value** | **Description** |
| --------------- | -------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| avatar\_id | String | | Digital human model in real-time avatar, The current system provides four options: \_"Kai\_1080P\_back"、"Katha\_1080P\_back"、"Olivia\_1080P\_back"、"who\_1080P\_back". If you want to use a custom uploaded video, you need to call the *[https://openapi.akool.com/api/open/v3/avatar/create](https://openapi.akool.com/api/open/v3/avatar/create)* interface to create a template. This process takes some time to process. You can check the processing status through the interface *[https://openapi.akool.com/api/open/v3/avatar/detail](https://openapi.akool.com/api/open/v3/avatar/detail)*. When status=3, you can use the avatar\_id field to pass it in. |
| background\_url | String | | The user can provide a background image to replace the avatar background in the video. If it is not passed or is empty, the avatar default background will be used. |
**Response Attributes**
| **Parameter** | **Type** | **Value** | **Description** |
| ------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| code | int | 1000 | Interface returns business status code(1000:success) |
| msg | String | | Interface returns status information |
| data | Object | `{ "_id": "", "status": 1, "stream_urls": { "client_pull_stream_url":"", "client_chat_room_url":"", "server_chat_room_url":"" } }` | `_id`: Interface returns data, status: the status of session： \[1:queueing, 2:processing, 3:completed, 4:failed], stream\_urls: the url of live avatar, *client\_pull\_stream\_url*: Client streaming address, *client\_chat\_room\_url*: Client websocket link address, *server\_chat\_room\_url*: server websocket link address, The address suffix such as server\_8898 is the object processed by the server algorithm |
**Example**
**Body**
```json
{
"_id": "6698c9d69cf7b0d61d1b6420",
"status": 1,
"task_id": "6698c9d69b4c131d2cf15f2d",
"app_name": "openapi_live",
"stream_name": "20240718075254093_8898",
"stream_urls": {
"client_pull_stream_url": "https://stream-open-test.akool.io:8443/final_openapi_live/20240718075254093_8898.flv", // Client streaming address
"client_chat_room_url": "wss://stream-open-test.akool.io:8443/final_20240718075254093_8898/client_8898.chat", // Client websocket link address
"server_chat_room_url": "wss://stream-open-test.akool.io:8443/final_20240718075254093_8898/server_8898.chat" // server websocket link address, The address suffix such as server_8898 is the object processed by the server algorithm
}
}
```
**Request**
```bash cURL
curl --location 'https://openapi.akool.com/api/open/v3/liveAvatar/session/create' \
--header 'authorization: Bearer token' \
--header 'content-type: application/json' \
--data '{
"avatar_id": "Kai_1080P_back",
"background_url": "https://static.website-files.org/assets/images/generator/text2image/1716867976184-c698621e-9bf3-4924-8d79-0ba1856669f2-6178_thumbnail.webp",
"webhookUrl":"https://openapitest.akool.com/api/open/v3/test/webhook"
}'
```
```java Java
OkHttpClient client = new OkHttpClient().newBuilder()
.build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n \"avatar_id\": \"Kai_1080P_back\",\n \"webhookUrl\":\"https://openapitest.akool.com/api/open/v3/test/webhook\"\n}");
Request request = new Request.Builder()
.url("https://openapi.akool.com/api/open/v3/liveAvatar/session/create")
.method("POST", body)
.addHeader("authorization", "Bearer token")
.addHeader("content-type", "application/json")
.build();
Response response = client.newCall(request).execute();
```
```js Javascript
const myHeaders = new Headers();
myHeaders.append("authorization", "Bearer token");
myHeaders.append("content-type", "application/json");
const raw = JSON.stringify({
avatar_id: "Kai_1080P_back",
background_url: "https://static.website-files.org/assets/images/generator/text2image/1716867976184-c698621e-9bf3-4924-8d79-0ba1856669f2-6178_thumbnail.webp",
webhookUrl: "https://openapitest.akool.com/api/open/v3/test/webhook",
});
const requestOptions = {
method: "POST",
headers: myHeaders,
body: raw,
redirect: "follow",
};
fetch(
"https://openapi.akool.com/api/open/v3/liveAvatar/session/create",
requestOptions
)
.then((response) => response.text())
.then((result) => console.log(result))
.catch((error) => console.error(error));
```
```php PHP
'Bearer token',
'content-type' => 'application/json'
];
$body = '{
"avatar_id": "Kai_1080P_back",
"background_url": "https://static.website-files.org/assets/images/generator/text2image/1716867976184-c698621e-9bf3-4924-8d79-0ba1856669f2-6178_thumbnail.webp",
"webhookUrl": "https://openapitest.akool.com/api/open/v3/test/webhook"
}';
$request = new Request('POST', 'https://openapi.akool.com/api/open/v3/liveAvatar/session/create', $headers, $body);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();
```
```python Python
import requests
import json
url = "https://openapi.akool.com/api/open/v3/liveAvatar/session/create"
payload = json.dumps({
"avatar_id": "Kai_1080P_back",
"background_url": "https://static.website-files.org/assets/images/generator/text2image/1716867976184-c698621e-9bf3-4924-8d79-0ba1856669f2-6178_thumbnail.webp",
"webhookUrl": "https://openapitest.akool.com/api/open/v3/test/webhook"
})
headers = {
'authorization': 'Bearer token',
'content-type': 'application/json'
}
response = requests.request("POST", url, headers=headers, data=payload)
print(response.text)
```
**Response**
```json
{
"code": 1000,
"msg": "OK",
"data": {
"_id": "6698c9d69cf7b0d61d1b6420",
"uid": 100010,
"type": 1,
"status": 1,
"task_id": "6698c9d69b4c131d2cf15f2d",
"app_name": "openapi_live",
"stream_name": "20240718075254093_8898",
"stream_urls": {
"client_pull_stream_url": "https://stream-open-test.akool.io:8443/final_openapi_live/20240718075254093_8898.flv", // Client streaming address
"client_chat_room_url": "wss://stream-open-test.akool.io:8443/final_20240718075254093_8898/client_8898.chat", // Client websocket link address
"server_chat_room_url": "wss://stream-open-test.akool.io:8443/final_20240718075254093_8898/server_8898.chat" // server websocket link address, The address suffix such as server_8898 is the object processed by the server algorithm
}
}
}
```
### Get Session Info Result
```
GET https://openapi.akool.com/api/open/v3/liveAvatar/session/detail?id=6698c9d69cf7b0d61d1b6420
```
**Request Headers**
| **Parameter** | **Value** | **Description** |
| ------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Authorization | Bearer token | Your API Key used for request authorization. You can get from [https://openapi.akool.com/api/open/v3/getToken](https://openapi.akool.com/api/open/v3/getToken) api. |
**Query Attributes**
| **Parameter** | **Type** | **Value** | **Description** |
| ------------- | -------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| id | String | NULL | video db id: You can get it based on the `_id` field returned by [https://openapi.akool.com/api/open/v3/liveAvatar/session/create](https://openapi.akool.com/api/open/v3/liveAvatar/session/create) . |
**Response Attributes**
| **Parameter** | **Type** | **Value** | **Description** |
| ------------- | -------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| code | int | 1000 | Interface returns business status code(1000:success) |
| msg | String | OK | Interface returns status information |
| data | Object | `{ status:1, _id:"", stream_urls:{} }` | status: the status of live avatar：【1:queueing, 2:processing, 3:completed, 4:failed】 stream\_urls: the url of live avatar, \_id: Interface returns data |
**Example**
**Request**
```bash cURL
curl --location 'http://openapi.akool.com/api/open/v3/liveAvatar/session/detail?id=6698c9d69cf7b0d61d1b6420' \
--header 'Authorization: Bearer token'
```
```java Java
OkHttpClient client = new OkHttpClient().newBuilder()
.build();
MediaType mediaType = MediaType.parse("text/plain");
RequestBody body = RequestBody.create(mediaType, "");
Request request = new Request.Builder()
.url("http://openapi.akool.com/api/open/v3/liveAvatar/session/detail?id=6698c9d69cf7b0d61d1b6420")
.method("GET", body)
.addHeader("Authorization", "Bearer token")
.build();
Response response = client.newCall(request).execute();
```
```js Javascript
const myHeaders = new Headers();
myHeaders.append("Authorization", "Bearer token");
const requestOptions = {
method: "GET",
headers: myHeaders,
redirect: "follow",
};
fetch(
"http://openapi.akool.com/api/open/v3/liveAvatar/session/detail?id=6698c9d69cf7b0d61d1b6420",
requestOptions
)
.then((response) => response.text())
.then((result) => console.log(result))
.catch((error) => console.error(error));
```
```php PHP
'Bearer token'
];
$request = new Request('GET', 'http://openapi.akool.com/api/open/v3/liveAvatar/session/detail?id=6698c9d69cf7b0d61d1b6420', $headers);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();
```
```python Python
import requests
url = "http://openapi.akool.com/api/open/v3/liveAvatar/session/detail?id=6698c9d69cf7b0d61d1b6420"
payload = {}
headers = {
'Authorization': 'Bearer token'
}
response = requests.request("GET", url, headers=headers, data=payload)
print(response.text)
```
**Response**
```json
{
"code": 1000,
"msg": "OK",
"data": {
"_id": "6698c9d69cf7b0d61d1b6420",
"uid": 100010,
"type": 1,
"status": 3,
"task_id": "6698c9d69b4c131d2cf15f2d",
"stream_urls": {
"client_pull_stream_url": "https://stream-open-test.akool.io:8443/final_openapi_live/20240718075254093_8898.flv"
}
}
}
```
### Close Session
```
POST https://openapi.akool.com/api/open/v3/liveAvatar/session/close
```
**Request Headers**
| **Parameter** | **Value** | **Description** |
| ------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Authorization | Bearer token | Your API Key used for request authorization. You can get from [https://openapi.akool.com/api/open/v3/getToken](https://openapi.akool.com/api/open/v3/getToken) api. |
**Body Attributes**
| **Parameter** | **Type** | **Value** | **Description** |
| ------------- | -------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| id | String | NULL | session id: You can get it based on the `_id` field returned by [https://openapi.akool.com/api/open/v3/liveAvatar/session/create](https://openapi.akool.com/api/open/v3/liveAvatar/session/create) . |
**Response Attributes**
| **Parameter** | **Type** | **Value** | **Description** |
| ------------- | -------- | --------- | ---------------------------------------------------- |
| code | int | 1000 | Interface returns business status code(1000:success) |
| msg | String | OK | Interface returns status information |
**Example**
**Request**
```bash cURL
curl --location 'http://openapi.akool.com/api/open/v3/liveAvatar/session/close' \
--header 'Authorization: Bearer token'
```
```java Java
OkHttpClient client = new OkHttpClient().newBuilder()
.build();
MediaType mediaType = MediaType.parse("text/plain");
RequestBody body = RequestBody.create(mediaType, "");
Request request = new Request.Builder()
.url("http://openapi.akool.com/api/open/v3/liveAvatar/session/close")
.method("POST", body)
.addHeader("Authorization", "Bearer token")
.build();
Response response = client.newCall(request).execute();
```
```js Javascript
const myHeaders = new Headers();
myHeaders.append("Authorization", "Bearer token");
const requestOptions = {
method: "POST",
headers: myHeaders,
redirect: "follow",
};
fetch(
"http://openapi.akool.com/api/open/v3/liveAvatar/session/close",
requestOptions
)
.then((response) => response.text())
.then((result) => console.log(result))
.catch((error) => console.error(error));
```
```php PHP
'Bearer token'
];
$request = new Request('POST', 'http://openapi.akool.com/api/open/v3/liveAvatar/session/close', $headers);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();
```
```python Python
import requests
url = "http://openapi.akool.com/api/open/v3/liveAvatar/session/close"
payload = {}
headers = {
'Authorization': 'Bearer token'
}
response = requests.request("POST", url, headers=headers, data=payload)
print(response.text)
```
**Response**
```json
{
"code": 1000,
"msg": "OK"
}
```
### Pause Session
```
POST https://openapi.akool.com/api/open/v3/liveAvatar/session/pause
```
Calling this interface will pause the streaming, and the processing of data may be delayed by 0.5s to several seconds.
Resending the websocket message will continue streaming. Please note that if you do not send messages for a long time after pausing, the connection will time out and you will need to restart the session.
**Request Headers**
| **Parameter** | **Value** | **Description** |
| ------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Authorization | Bearer token | Your API Key used for request authorization. You can get from [https://openapi.akool.com/api/open/v3/getToken](https://openapi.akool.com/api/open/v3/getToken) api. |
**Body Attributes**
| **Parameter** | **Type** | **Value** | **Description** |
| ------------- | -------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| id | String | NULL | session id: You can get it based on the `_id` field returned by [https://openapi.akool.com/api/open/v3/liveAvatar/session/create](https://openapi.akool.com/api/open/v3/liveAvatar/session/create) . |
**Response Attributes**
| **Parameter** | **Type** | **Value** | **Description** |
| ------------- | -------- | --------- | ---------------------------------------------------- |
| code | int | 1000 | Interface returns business status code(1000:success) |
| msg | String | OK | Interface returns status information |
**Example**
**Request**
```bash cURL
curl --location 'http://openapi.akool.com/api/open/v3/liveAvatar/session/pause' \
--header 'Authorization: Bearer token'
```
```java Java
OkHttpClient client = new OkHttpClient().newBuilder()
.build();
MediaType mediaType = MediaType.parse("text/plain");
RequestBody body = RequestBody.create(mediaType, "");
Request request = new Request.Builder()
.url("http://openapi.akool.com/api/open/v3/liveAvatar/session/pause")
.method("POST", body)
.addHeader("Authorization", "Bearer token")
.build();
Response response = client.newCall(request).execute();
```
```js Javascript
const myHeaders = new Headers();
myHeaders.append("Authorization", "Bearer token");
const requestOptions = {
method: "POST",
headers: myHeaders,
redirect: "follow",
};
fetch(
"http://openapi.akool.com/api/open/v3/liveAvatar/session/pause",
requestOptions
)
.then((response) => response.text())
.then((result) => console.log(result))
.catch((error) => console.error(error));
```
```php PHP
'Bearer token'
];
$request = new Request('POST', 'http://openapi.akool.com/api/open/v3/liveAvatar/session/pause', $headers);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();
```
```python Python
import requests
url = "http://openapi.akool.com/api/open/v3/liveAvatar/session/pause"
payload = {}
headers = {
'Authorization': 'Bearer token'
}
response = requests.request("POST", url, headers=headers, data=payload)
print(response.text)
```
**Response**
```json
{
"code": 1000,
"msg": "OK"
}
```
### Get Session List
```
GET https://openapi.akool.com/api/open/v3/liveAvatar/session/list?page=1&size=10&status=1
```
**Request Headers**
| **Parameter** | **Value** | **Description** |
| ------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Authorization | Bearer token | Your API Key used for request authorization. You can get from [https://openapi.akool.com/api/open/v3/getToken](https://openapi.akool.com/api/open/v3/getToken) api. |
**Query Attributes**
| **Parameter** | **Type** | **Value** | **Description** |
| ------------- | -------- | --------- | ------------------------------------------------------------------ |
| page | Number | 1 | Current number of pages，Default is 1. |
| size | Number | 10 | Current number of returns per page，Default is 100. |
| status | Number | NULL | session status: 【1:queueing, 2:processing, 3:completed, 4:failed】. |
**Response Attributes**
| **Parameter** | **Type** | **Value** | **Description** |
| ------------- | -------- | --------------------------------------------------------- | ---------------------------------------------------------- |
| code | int | 1000 | Interface returns business status code(1000:success) |
| msg | String | OK | Interface returns status information |
| data | Array | `{count： 1, data: [{ task_id: "xx", stream_urls: {} }] }` | task\_id: task id of session. url: the url of live avatar. |
**Example**
**Request**
```bash cURL
curl --location 'http://openapi.akool.com/api/open/v3/liveAvatar/session/list?page=1&size=10&status=1' \
--header 'Authorization: Bearer token'
```
```java Java
OkHttpClient client = new OkHttpClient().newBuilder()
.build();
MediaType mediaType = MediaType.parse("text/plain");
RequestBody body = RequestBody.create(mediaType, "");
Request request = new Request.Builder()
.url("http://openapi.akool.com/api/open/v3/liveAvatar/session/list?page=1&size=10&status=1")
.method("GET", body)
.addHeader("Authorization", "Bearer token")
.build();
Response response = client.newCall(request).execute();
```
```js Javascript
const myHeaders = new Headers();
myHeaders.append("Authorization", "Bearer token");
const requestOptions = {
method: "GET",
headers: myHeaders,
redirect: "follow",
};
fetch(
"http://openapi.akool.com/api/open/v3/liveAvatar/session/list?page=1&size=10&status=1",
requestOptions
)
.then((response) => response.text())
.then((result) => console.log(result))
.catch((error) => console.error(error));
```
```php PHP
'Bearer token'
];
$request = new Request('GET', 'http://openapi.akool.com/api/open/v3/liveAvatar/session/list?page=1&size=10&status=1', $headers);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();
```
```python Python
import requests
url = "http://openapi.akool.com/api/open/v3/liveAvatar/session/list?page=1&size=10&status=1"
payload = {}
headers = {
'Authorization': 'Bearer token'
}
response = requests.request("GET", url, headers=headers, data=payload)
print(response.text)
```
**Response**
```json
{
"code": 1000,
"msg": "OK",
"data": {
"count": 18,
"result": [
{
"stream_urls": {
"client_pull_stream_url": "https://stream-open.akool.io:8443/final_openapi_live/20240615060910789_3712.flv",
"client_push_stream_url": "https://stream-open.akool.io:8443/openapi_live/20240615060910789_3712.whip"
},
"_id": "666d3006247f07725af0f884",
"uid": 100010,
"type": 1,
"status": 1,
"task_id": "666d300635d473f81c8be7b1"
}
]
}
}
```
### Live Avatar WebSocket
```
WSS client_chat_room_url
```
{" "}
you can get the url *client\_chat\_room\_url* from the interface 【Create session】.
like *wss\://stream-open.akool.io:8443/final\_open\_live/client\_3835.chat*
**Receive Data**
| **Parameter** | **Type** | **Value** | **Description** |
| ---------------------- | -------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| type | String | chat | default *chat*. |
| payload | String | | To pass in content, you need to serialize the json content. |
| payload.message\_id | String | | Message id. The same id indicates that the incoming data belongs to the same message. |
| payload.voice\_id | String | | Voice model id, you can get the field *voice\_id* from the interface 【Get Voice List Result】. |
| payload.language | String | | Language code, you can get the field *lang\_code* from the interface 【Get Language List Result】. |
| payload.mode\_type | String | 1 | default *1*. |
| payload.question | String | | The text content passed in, such as 'Hello'. |
| payload.prompt | Object | | Regarding the custom description of the digital person. |
| payload.prompt.from | String | text | the value range of from is 【text, url】. The default type="text" |
| payload.prompt.content | String | | When type is text, content is the text description of the avatar role. When type is url, content is the pdf link of the description of the avatar role. The link size limit is 50M. The default type="text" and content="" |
| to | String | | Server ID, you can get from *server\_chat\_room\_url* link address, The address suffix such as server\_8898 is the server id. |
**Example**
**Send Data**
The payload here is not serialized. When using it, you need to use JSON.stringify() to convert the object into a json string. If it is other types, you can convert it to base64 first.
```json
{
"type": "chat", // default 'chat'.
"payload": {
"message_id":"msg-1723629433573", // Message id. The same id indicates that the incoming data belongs to the same message.
"voice_id":"21m00Tcm4TlvDq8ikWAM", // Voice model id, you can get the field *voice_id* from the interface 【Get Voice List Result】.
"language":"en", // Language code, you can get the field 'lang_code' from the interface 【Get Language List Result】
"mode_type":1, // 1 Retelling 2 Dialogue， default *1*.
"prompt":{
"from": "text",
"content": ""
},
"question":"Hello" // The text content passed in, such as 'Hello'.
},
"to": "server_8898" // Server ID, you can get from *server_chat_room_url* link address, The address suffix such as server_8898 is the server id.
}
```
**Receive Data**
The payload has been parsed here. In actual use, you need to perform JSON.parse() to restore it first.
```json
{
"type": "chat", // default 'chat'.
"from": "server_8898", // Current server id.
"to": "client_8898", // Current client id.
"payload": {
"message_id": "msg-1723629433573", // Message id. The same id indicates that the incoming data belongs to the same message.
"voice_id": "21m00Tcm4TlvDq8ikWAM", // Voice model id, you can get the field *voice_id* from the interface 【Get Voice List Result】.
"language": "English", // Language
"mode_type": 1, // default *1*.
"prompt": {
"from": "text",
"content": ""
},
"question": "", // Current input question
"answer": "Hello! How can I assist you today? " // avatar's answer
}
}
```
```bash Javascript
const WebSocket = require('ws')
const ws = new WebSocket('wss://stream-open-test.akool.io:8443/final_[stream_name]/client_[stream_name].chat');
ws.on('open', function open() {
let message = {
"type": "chat",
"payload": JSON.stringify({
"message_id":"1",
"voice_id":"21m00Tcm4TlvDq8ikWAM",
"language":"en",
"mode_type": 1,
"prompt":{
"from": "text",
"content": ""
},
"question": "hello"
}),
"to": "server_8898"
};
ws.send(JSON.stringify(message));
});
ws.on('message', function message(data) {
console.log('received: %s', data);
});
```
**Response Code Description**
{" "}
Please note that if the value of the response code is not equal to 1000, the request
is failed or wrong
| **Parameter** | **Value** | **Description** |
| ------------- | --------- | --------------------------------------------------------------------------------- |
| code | 1000 | Success |
| code | 1003 | Parameter error or Parameter can not beempty |
| code | 1008 | The content you get does not exist |
| code | 1009 | Youdo not have permission to operate |
| code | 1101 | Invalid authorization or Therequest token has expired |
| code | 1102 | Authorization cannot be empty |
| code | 1200 | The account has been banned |
| code | 1201 | create audio error, pleasetry again later |
| code | 1202 | The same video cannot be translated lipSync inthe same language more than 1 times |
| code | 1203 | video should be with audio |
| code | 1204 | Your video duration is exceed 60s! |
| code | 1205 | Create videoerror, please try again later |
| code | 1207 | The video you are using exceeds thesize limit allowed by the system by 300M |
| code | 1209 | Please upload a videoin another encoding format |
| code | 1210 | The video you are using exceeds thevalue allowed by the system by 60fp |
| code | 1211 | Create lipsync error, pleasetry again later |
# Live Face Swap
Source: https://docstest.akool.io/ai-tools-suite/live-faceswap
Real-time Face Swap API Documentation
Generated resources (images, videos) are valid for 7 days. Please save related resources promptly to prevent expiration.
## Overview
Live Face Swap API provides real-time face swap functionality, supporting real-time face swap operations during live streaming.
## Get Access Token
Before calling other APIs, you need to obtain an access token first.
```bash
POST https://openapi.akool.com/api/open/v3/getToken
```
**Request Headers**
| **Parameter** | **Value** | **Description** |
| ------------- | ---------------- | -------------------- |
| Content-Type | application/json | Request content type |
**Request Body**
| **Parameter** | **Type** | **Description** |
| ------------- | -------- | --------------- |
| clientId | String | Client ID |
| clientSecret | String | Client secret |
**Example Request**
```json
{
"clientId": "AKX5brZQ***XBQSk=",
"clientSecret": "tcMhvgV0fY***WQ2eIoEY70rNi"
}
```
## Face Detection
Detect faces in an image and get facial landmarks coordinates.
```bash
POST https://sg3.akool.com/detect
```
**Request Headers**
| **Parameter** | **Value** | **Description** |
| ------------- | ---------------- | --------------------------------- |
| Authorization | Bearer token | API key for request authorization |
| Content-Type | application/json | Request content type |
**Request Body**
| **Parameter** | **Type** | **Description** |
| ------------- | -------- | ---------------------------------- |
| single\_face | Boolean | Whether to detect single face only |
| image\_url | String | Image URL for face detection |
| img | String | Base64 encoded image (optional) |
**Example Request**
```json
{
"single_face": false,
"image_url": "https://d21ksh0k4smeql.cloudfront.net/1745579943557-yr5w-crop_1728989585247-3239-0-1728989585409-9277.png"
}
```
**Response**
| **Parameter** | **Type** | **Description** |
| -------------- | -------- | ----------------------------------------- |
| error\_code | int | Error code (0: success) |
| error\_msg | String | Error message |
| landmarks | Array | Facial landmarks coordinates array |
| landmarks\_str | Array | Facial landmarks coordinates string array |
| region | Array | Face region coordinates |
| seconds | float | Processing time in seconds |
| trx\_id | String | Transaction ID |
**Response Example**
```json
{
"error_code": 0,
"error_msg": "SUCCESS",
"landmarks": [
[
[249, 510],
[460, 515],
[343, 657],
[255, 740],
[0, 0],
[0, 0]
]
],
"landmarks_str": [
"249,510:460,515:343,657:255,740"
],
"region": [
[150, 264, 437, 657]
],
"seconds": 0.6554102897644043,
"trx_id": "64498285-446f-462d-9470-fe36c36c6eac"
}
```
## Create Real-time Face Swap Session
Create a new real-time face swap session.
```bash
POST https://openapi.akool.com/api/open/v3/faceswap/live/create
```
**Request Headers**
| **Parameter** | **Value** | **Description** |
| ------------- | ---------------- | --------------------------------- |
| Authorization | Bearer token | API key for request authorization |
| Content-Type | application/json | Request content type |
**Request Body**
| **Parameter** | **Type** | **Description** |
| ------------- | -------- | ------------------------------------------------------------------------------ |
| sourceImage | Array | Source image information array, each element contains path and opts properties |
**Example Request**
```json
{
"sourceImage": [
{
"path": "https://d21ksh0k4smeql.cloudfront.net/crop_1695201165222-7514-0-1695201165485-8149.png",
"opts": "262,175:363,175:313,215:272,279"
}
]
}
```
**Response**
| **Parameter** | **Type** | **Description** |
| ------------- | -------- | ------------------------------------------------- |
| code | int | API response business status code (1000: success) |
| msg | String | API response status information |
| data | Object | Response data object |
**Response Example**
```json
{
"code": 1000,
"msg": "OK",
"data": {
"_id": "684f8fb744b8795862e45cbe",
"faceswap_status": 1,
"front_user_id": "1",
"algorithm_user_id": "3",
"front_rtc_token": "007eJxTYFj/uGvaue3C3/VlOLdFmM5UuffmzHGhszbnTSqs3or94HNRYEhNNElJM0oxMkg1MTYxMklMMkm0MDCySDW0sDBOMjRP297vnyHAx8Bw6YAZIyMDIwMLAyMDiM8EJpnBJAuYFGMwMjAyNTAzNDMwNrI0tTQ0MIy3MDIyYWQwBADtwSJM",
"channel_id": "20250616032959101_8224",
"app_id": ""
}
}
```
**Status Code Description**
* `faceswap_status`:
* 1: Queuing
* 2: Processing (when this value is 2, the frontend can connect to Agora's server)
* 3: Success
* 4: Failed
## Update Real-time Face Swap Session
Update existing real-time face swap session configuration.
```bash
POST https://openapi.akool.com/api/open/v3/faceswap/live/update
```
**Request Headers**
| **Parameter** | **Value** | **Description** |
| ------------- | ---------------- | --------------------------------- |
| Authorization | Bearer token | API key for request authorization |
| Content-Type | application/json | Request content type |
**Request Body**
| **Parameter** | **Type** | **Description** |
| ------------- | -------- | ------------------------------------------------------------------------------ |
| \_id | String | Session ID |
| sourceImage | Array | Source image information array, each element contains path and opts properties |
**Example Request**
```json
{
"sourceImage": [
{
"path": "https://d21ksh0k4smeql.cloudfront.net/1745579943557-yr5w-crop_1728989585247-3239-0-1728989585409-9277.png",
"opts": "249,510:460,515:343,657:255,740"
}
],
"_id": "685ea0bb5aa150dd8b7116b1"
}
```
**Response Example**
```json
{
"code": 1000,
"msg": "OK"
}
```
## Close Real-time Face Swap Session
Close the specified real-time face swap session.
```bash
POST https://openapi.akool.com/api/open/v3/faceswap/live/close
```
**Request Headers**
| **Parameter** | **Value** | **Description** |
| ------------- | ---------------- | --------------------------------- |
| Authorization | Bearer token | API key for request authorization |
| Content-Type | application/json | Request content type |
**Request Body**
| **Parameter** | **Type** | **Description** |
| ------------- | -------- | --------------- |
| \_id | String | Session ID |
**Example Request**
```json
{
"_id": "685ea0bb5aa150dd8b7116b1"
}
```
**Response Example**
```json
{
"code": 1000,
"msg": "OK"
}
```
## Code Examples
```bash cURL
# Get token
curl -X POST "https://openapi.akool.com/api/open/v3/getToken" \
-H "Content-Type: application/json" \
-d '{
"clientId": "AKX5brZQ***XBQSk=",
"clientSecret": "tcMhvgV0fY***WQ2eIoEY70rNi"
}'
# Face detection
curl -X POST "https://sg3.akool.com/detect" \
-H "Authorization: Bearer token" \
-H "Content-Type: application/json" \
-d '{
"single_face": false,
"image_url": "https://d21ksh0k4smeql.cloudfront.net/1745579943557-yr5w-crop_1728989585247-3239-0-1728989585409-9277.png"
}'
# Create session
curl -X POST "https://openapi.akool.com/api/open/v3/faceswap/live/create" \
-H "Authorization: Bearer token" \
-H "Content-Type: application/json" \
-d '{
"sourceImage": [
{
"path": "https://d21ksh0k4smeql.cloudfront.net/crop_1695201165222-7514-0-1695201165485-8149.png",
"opts": "262,175:363,175:313,215:272,279"
}
]
}'
# Update session
curl -X POST "https://openapi.akool.com/api/open/v3/faceswap/live/update" \
-H "Authorization: Bearer token" \
-H "Content-Type: application/json" \
-d '{
"sourceImage": [
{
"path": "https://d21ksh0k4smeql.cloudfront.net/1745579943557-yr5w-crop_1728989585247-3239-0-1728989585409-9277.png",
"opts": "249,510:460,515:343,657:255,740"
}
],
"_id": "685ea0bb5aa150dd8b7116b1"
}'
# Close session
curl -X POST "https://openapi.akool.com/api/open/v3/faceswap/live/close" \
-H "Authorization: Bearer token" \
-H "Content-Type: application/json" \
-d '{
"_id": "685ea0bb5aa150dd8b7116b1"
}'
```
```javascript JavaScript
// Get token
const getToken = async () => {
const response = await fetch('https://openapi.akool.com/api/open/v3/getToken', {
method: 'POST',
headers: {
'Content-Type': 'application/json'
},
body: JSON.stringify({
clientId: 'AKX5brZQ***XBQSk=',
clientSecret: 'tcMhvgV0fY***WQ2eIoEY70rNi'
})
});
return response.json();
};
// Face detection
const detectFace = async (token, imageUrl) => {
const response = await fetch('https://sg3.akool.com/detect', {
method: 'POST',
headers: {
'Authorization': `Bearer ${token}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
single_face: false,
image_url: imageUrl
})
});
return response.json();
};
// Create session
const createSession = async (token, sourceImage) => {
const response = await fetch('https://openapi.akool.com/api/open/v3/faceswap/live/create', {
method: 'POST',
headers: {
'Authorization': `Bearer ${token}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
sourceImage: sourceImage
})
});
return response.json();
};
// Update session
const updateSession = async (token, sessionId, sourceImage) => {
const response = await fetch('https://openapi.akool.com/api/open/v3/faceswap/live/update', {
method: 'POST',
headers: {
'Authorization': `Bearer ${token}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
_id: sessionId,
sourceImage: sourceImage
})
});
return response.json();
};
// Close session
const closeSession = async (token, sessionId) => {
const response = await fetch('https://openapi.akool.com/api/open/v3/faceswap/live/close', {
method: 'POST',
headers: {
'Authorization': `Bearer ${token}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
_id: sessionId
})
});
return response.json();
};
```
```python Python
import requests
import json
# Get token
def get_token():
url = "https://openapi.akool.com/api/open/v3/getToken"
payload = {
"clientId": "AKX5brZQ***XBQSk=",
"clientSecret": "tcMhvgV0fY***WQ2eIoEY70rNi"
}
headers = {'Content-Type': 'application/json'}
response = requests.post(url, headers=headers, json=payload)
return response.json()
# Face detection
def detect_face(token, image_url):
url = "https://sg3.akool.com/detect"
payload = {
"single_face": False,
"image_url": image_url
}
headers = {
'Authorization': f'Bearer {token}',
'Content-Type': 'application/json'
}
response = requests.post(url, headers=headers, json=payload)
return response.json()
# Create session
def create_session(token, source_image):
url = "https://openapi.akool.com/api/open/v3/faceswap/live/create"
payload = {
"sourceImage": source_image
}
headers = {
'Authorization': f'Bearer {token}',
'Content-Type': 'application/json'
}
response = requests.post(url, headers=headers, json=payload)
return response.json()
# Update session
def update_session(token, session_id, source_image):
url = "https://openapi.akool.com/api/open/v3/faceswap/live/update"
payload = {
"_id": session_id,
"sourceImage": source_image
}
headers = {
'Authorization': f'Bearer {token}',
'Content-Type': 'application/json'
}
response = requests.post(url, headers=headers, json=payload)
return response.json()
# Close session
def close_session(token, session_id):
url = "https://openapi.akool.com/api/open/v3/faceswap/live/close"
payload = {
"_id": session_id
}
headers = {
'Authorization': f'Bearer {token}',
'Content-Type': 'application/json'
}
response = requests.post(url, headers=headers, json=payload)
return response.json()
```
## Response Code Description
> **Note:** If the `code` value in the response is not `1000`, the request has failed or is incorrect.
| **Parameter** | **Value** | **Description** |
| ------------- | --------- | ------------------------------------------------------ |
| code | 1000 | Success |
| code | 1003 | Parameter error or parameter cannot be empty |
| code | 1101 | Invalid authorization or the request token has expired |
| code | 1102 | Authorization cannot be empty |
| code | 1104 | Insufficient quota |
## Important Notes
1. **Resource Validity**: Generated resources are valid for 7 days, please save them promptly
2. **Face Detection**: Use the face-detect API to get face landmarks coordinates before creating face swap sessions
3. **Status Monitoring**: After creating a session, you need to monitor the `faceswap_status` status
4. **Real-time Connection**: When the status is 2, you can connect to Agora's server for real-time face swap
5. **Session Management**: Please close sessions promptly after use to release resources
6. **Error Handling**: Please handle API error codes and error messages properly
## Push and pull stream Demo References
For implementing real-time video communication with Agora SDK, you can refer to the following resources:
### Basic Video Calling Demo Parameter Description
As shown in the figure above, `channel_id`, `front_user_id`, and `front_rtc_token` correspond to the Channel, User ID, and Token input fields on the page respectively.
These parameters can be obtained after creating a session through the Live Face Swap API. After filling them in, you can experience push/pull streaming and real-time face swap effects.
### Demo Page
* **Live Demo**: [https://webdemo-global.agora.io/example/basic/basicVideoCall/index.html](https://webdemo-global.agora.io/example/basic/basicVideoCall/index.html)
### Source Code
* **GitHub Repository**: [https://github.com/AgoraIO/API-Examples-Web/tree/main/src/example/basic/basicVideoCall](https://github.com/AgoraIO/API-Examples-Web/tree/main/src/example/basic/basicVideoCall)
### Recommended Track Configuration
For optimal performance in live face swap scenarios, it's recommended to use the following track configurations:
#### Audio Track Configuration
```javascript
const audioTrack = await AgoraRTC.createMicrophoneAudioTrack({
encoderConfig: "music_standard",
});
```
#### Video Track Configuration
```javascript
const videoTrack = await AgoraRTC.createCameraVideoTrack({
encoderConfig: {
width: 640,
height: 480,
frameRate: {max: 20, min: 20},
bitrateMin: 5000,
bitrateMax: 5000,
},
});
```
These configurations are optimized for:
* **Audio**: Using `music_standard` encoder for better audio quality
* **Video**: Fixed frame rate at 20fps with controlled bitrate for stable performance
* **Resolution**: 640x480 resolution suitable for face swap processing
These resources provide complete examples of how to integrate Agora's real-time video communication SDK, which can be used as a reference for implementing the video streaming part of the live face swap functionality.
# Reage
Source: https://docstest.akool.io/ai-tools-suite/reage
The resources (image, video, voice) generated by our API are valid for 7 days. Please save the relevant resources as soon as possible to prevent expiration.
### Image Reage
```
POST https://openapi.akool.com/api/open/v3/faceswap/highquality/imgreage
```
**Request Headers**
| **Parameter** | **Value** | **Description** |
| ------------- | ------------ | ------------------------------------------- |
| Authorization | Bearer token | Your API Key used for request authorization |
**Body Attributes**
| Parameter | Type | Value | Description |
| ----------- | ------ | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| targetImage | Array | `[{path:"",opts:""}]` | Replacement target image information(Each array element is an object, and the object contains 2 properties, path:Links to faces detected in target images. opts: Key information of the face detected in the target image【You can get it through the face [https://sg3.akool.com/detect](https://sg3.akool.com/detect) API, You can get the landmarks\_str value returned by the api interface as the value of opts) |
| face\_reage | Int | \[-30, 30] | Reage ranges |
| modifyImage | String | | Modify the link address of the image |
| webhookUrl | String | | Callback url address based on HTTP request |
**Response Attributes**
| Parameter | Type | Value | Description |
| --------- | ------ | ----------------------------- | ------------------------------------------------------------------------------------------ |
| code | int | 1000 | Interface returns business status code(1000:success) |
| msg | String | | Interface returns status information |
| data | Object | `{_id:"",url: "",job_id: ""}` | `_id`: Interface returns data url: faceswwap result url job\_id: Task processing unique id |
**Example**
**Body**
```json
{
"targetImage": [ // Replacement target image information
{
"path": "https://d21ksh0k4smeql.cloudfront.net/crop_1695201103793-0234-0-1695201106985-2306.png", // Links to faces detected in target images
"opts": "2804,2182:3607,1897:3341,2566:3519,2920" // Key information of the face detected in the target image【You can get it through the face https://sg3.akool.com/detect API,You can get the landmarks_str value returned by the api interface as the value of opts
}
],
"face_reage":10,// [-30,30]
"modifyImage": "https://d3t6pcz7y7ey7x.cloudfront.net/material1__a92671d0-7960-4028-b2fc-aadd3541f32d.jpg", // Modify the link address of the image
"webhookUrl":"http://localhost:3007/api/webhook" // Callback url address based on HTTP request
}
```
**Request**
```bash cURL
curl --location 'https://openapi.akool.com/api/open/v3/faceswap/highquality/imgreage' \
--header 'Authorization: Bearer token' \
--header 'Content-Type: application/json' \
--data '{
"targetImage": [
{
"path": "https://d21ksh0k4smeql.cloudfront.net/crop_1695201103793-0234-0-1695201106985-2306.png",
"opts": "2804,2182:3607,1897:3341,2566:3519,2920"
}
],
"face_reage":10,
"modifyImage": "https://d3t6pcz7y7ey7x.cloudfront.net/material1__a92671d0-7960-4028-b2fc-aadd3541f32d.jpg",
"webhookUrl":"http://localhost:3007/api/webhook"
}'
```
```java Java
OkHttpClient client = new OkHttpClient().newBuilder()
.build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n \"targetImage\": [ \n {\n \"path\": \"https://d21ksh0k4smeql.cloudfront.net/crop_1695201103793-0234-0-1695201106985-2306.png\", \n \"opts\": \"2804,2182:3607,1897:3341,2566:3519,2920\" \n }\n ],\n \"face_reage\":10,\n \"modifyImage\": \"https://d3t6pcz7y7ey7x.cloudfront.net/material1__a92671d0-7960-4028-b2fc-aadd3541f32d.jpg\", \n \"webhookUrl\":\"http://localhost:3007/api/webhook\" \n}");
Request request = new Request.Builder()
.url("https://openapi.akool.com/api/open/v3/faceswap/highquality/imgreage")
.method("POST", body)
.addHeader("Authorization", "Bearer token")
.addHeader("Content-Type", "application/json")
.build();
Response response = client.newCall(request).execute();
```
```js Javascript
const myHeaders = new Headers();
myHeaders.append("Authorization", "Bearer token");
myHeaders.append("Content-Type", "application/json");
const raw = JSON.stringify({
"targetImage": [
{
"path": "https://d21ksh0k4smeql.cloudfront.net/crop_1695201103793-0234-0-1695201106985-2306.png",
"opts": "2804,2182:3607,1897:3341,2566:3519,2920"
}
],
"face_reage": 10,
"modifyImage": "https://d3t6pcz7y7ey7x.cloudfront.net/material1__a92671d0-7960-4028-b2fc-aadd3541f32d.jpg",
"webhookUrl": "http://localhost:3007/api/webhook"
});
const requestOptions = {
method: "POST",
headers: myHeaders,
body: raw,
redirect: "follow"
};
fetch("https://openapi.akool.com/api/open/v3/faceswap/highquality/imgreage", requestOptions)
.then((response) => response.text())
.then((result) => console.log(result))
.catch((error) => console.error(error));
```
```php PHP
'Bearer token',
'Content-Type' => 'application/json'
];
$body = '{
"targetImage": [
{
"path": "https://d21ksh0k4smeql.cloudfront.net/crop_1695201103793-0234-0-1695201106985-2306.png",
"opts": "2804,2182:3607,1897:3341,2566:3519,2920"
}
],
"face_reage": 10,
"modifyImage": "https://d3t6pcz7y7ey7x.cloudfront.net/material1__a92671d0-7960-4028-b2fc-aadd3541f32d.jpg",
"webhookUrl": "http://localhost:3007/api/webhook"
}';
$request = new Request('POST', 'https://openapi.akool.com/api/open/v3/faceswap/highquality/imgreage', $headers, $body);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();
```
```python Python
import requests
import json
url = "https://openapi.akool.com/api/open/v3/faceswap/highquality/imgreage"
payload = json.dumps({
"targetImage": [
{
"path": "https://d21ksh0k4smeql.cloudfront.net/crop_1695201103793-0234-0-1695201106985-2306.png",
"opts": "2804,2182:3607,1897:3341,2566:3519,2920"
}
],
"face_reage": 10,
"modifyImage": "https://d3t6pcz7y7ey7x.cloudfront.net/material1__a92671d0-7960-4028-b2fc-aadd3541f32d.jpg",
"webhookUrl": "http://localhost:3007/api/webhook"
})
headers = {
'Authorization': 'Bearer token',
'Content-Type': 'application/json'
}
response = requests.request("POST", url, headers=headers, data=payload)
print(response.text)
```
**Response**
```json
{
"code": 1000, // Interface returns business status code
"msg": "Please be patient! If your results are not generated in three hours, please check your input image.", // Interface returns status information
"data": {
"_id": "6593c94c0ef703e8c055e3c8", // Interface returns data
"url": "https://***.cloudfront.net/final_71688047459_.pic-1704184129269-4947-f8abc658-fa82-420f-b1b3-c747d7f18e14-8535.jpg", // faceswwap result url
"job_id": "20240102082900592-5653" // Task processing unique id
}
}
```
### Video Reage
```
POST https://openapi.akool.com/api/open/v3/faceswap/highquality/vidreage
```
**Request Headers**
| **Parameter** | **Value** | **Description** |
| ------------- | ------------ | ------------------------------------------- |
| Authorization | Bearer token | Your API Key used for request authorization |
**Body Attributes**
| Parameter | Type | Value | Description |
| ----------- | ------ | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| targetImage | Array | `[]` | Replacement target image information(Each array element is an object, and the object contains 2 properties, path:Links to faces detected in target images. opts: Key information of the face detected in the target image【You can get it through the face [https://sg3.akool.com/detect](https://sg3.akool.com/detect) API, You can get the landmarks\_str value returned by the api interface as the value of opts) |
| face\_reage | Int | `[-30,30]` | Reage ranges |
| modifyVideo | String | | Modify the link address of the video |
| webhookUrl | String | | Callback url address based on HTTP request |
**Response Attributes**
| Parameter | Type | Value | Description |
| --------- | ------ | ---------------------------------- | ------------------------------------------------------------------------------------------- |
| code | int | 1000 | Interface returns business status code (1000: success) |
| msg | String | | Interface returns status information |
| data | Object | `{ _id: "", url: "", job_id: "" }` | `_id`: Interface returns data, url: faceswap result url, job\_id: Task processing unique id |
**Example**
**Body**
```json
{
"targetImage": [ // Replacement target image information
{
"path": "https://d21ksh0k4smeql.cloudfront.net/crop_1695200391486-4662-0-1695200392027-6110.png", // Links to faces detected in target images
"opts": "1622,759:2149,776:1869,1085:1875,1345" // Key information of the face detected in the target image【You can get it through the face https://sg3.akool.com/detect API,You can get the landmarks_str value returned by the api interface as the value of opts
}
],
"face_reage":10,// [-30,30]
"modifyVideo": "https://d3t6pcz7y7ey7x.cloudfront.net/Video10__d2a8cf85-10ae-4c2d-8f4b-d818c0a2e4a4.mp4", // Modify the link address of the video
"webhookUrl":"http://localhost:3007/api/webhook" // Callback url address based on HTTP request
}
```
**Request**
```bash cURL
curl --location 'https://openapi.akool.com/api/open/v3/faceswap/highquality/vidreage' \
--header 'Authorization: Bearer token' \
--header 'Content-Type: application/json' \
--data '{
"targetImage": [
{
"path": "https://d21ksh0k4smeql.cloudfront.net/crop_1695200391486-4662-0-1695200392027-6110.png",
"opts": "1622,759:2149,776:1869,1085:1875,1345"
}
],
"face_reage":10,
"modifyVideo": "https://d3t6pcz7y7ey7x.cloudfront.net/Video10__d2a8cf85-10ae-4c2d-8f4b-d818c0a2e4a4.mp4",
"webhookUrl":"http://localhost:3007/api/webhook"
}'
```
```java Java
OkHttpClient client = new OkHttpClient().newBuilder()
.build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n \"targetImage\": [ \n {\n \"path\": \"https://d21ksh0k4smeql.cloudfront.net/crop_1695200391486-4662-0-1695200392027-6110.png\", \n \"opts\": \"1622,759:2149,776:1869,1085:1875,1345\" \n }\n ],\n \"face_reage\":10,\n \"modifyVideo\": \"https://d3t6pcz7y7ey7x.cloudfront.net/Video10__d2a8cf85-10ae-4c2d-8f4b-d818c0a2e4a4.mp4\", \n \"webhookUrl\":\"http://localhost:3007/api/webhook\" \n}");
Request request = new Request.Builder()
.url("https://openapi.akool.com/api/open/v3/faceswap/highquality/vidreage")
.method("POST", body)
.addHeader("Authorization", "Bearer token")
.addHeader("Content-Type", "application/json")
.build();
Response response = client.newCall(request).execute();
```
```js Javascript
const myHeaders = new Headers();
myHeaders.append("Authorization", "Bearer token");
myHeaders.append("Content-Type", "application/json");
const raw = JSON.stringify({
"targetImage": [
{
"path": "https://d21ksh0k4smeql.cloudfront.net/crop_1695200391486-4662-0-1695200392027-6110.png",
"opts": "1622,759:2149,776:1869,1085:1875,1345"
}
],
"face_reage": 10,
"modifyVideo": "https://d3t6pcz7y7ey7x.cloudfront.net/Video10__d2a8cf85-10ae-4c2d-8f4b-d818c0a2e4a4.mp4",
"webhookUrl": "http://localhost:3007/api/webhook"
});
const requestOptions = {
method: "POST",
headers: myHeaders,
body: raw,
redirect: "follow"
};
fetch("https://openapi.akool.com/api/open/v3/faceswap/highquality/vidreage", requestOptions)
.then((response) => response.text())
.then((result) => console.log(result))
.catch((error) => console.error(error));
```
```php PHP
'Bearer token',
'Content-Type' => 'application/json'
];
$body = '{
"targetImage": [
{
"path": "https://d21ksh0k4smeql.cloudfront.net/crop_1695200391486-4662-0-1695200392027-6110.png",
"opts": "1622,759:2149,776:1869,1085:1875,1345"
}
],
"face_reage": 10,
"modifyVideo": "https://d3t6pcz7y7ey7x.cloudfront.net/Video10__d2a8cf85-10ae-4c2d-8f4b-d818c0a2e4a4.mp4",
"webhookUrl": "http://localhost:3007/api/webhook"
}';
$request = new Request('POST', 'https://openapi.akool.com/api/open/v3/faceswap/highquality/vidreage', $headers, $body);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();
```
```python Python
import requests
import json
url = "https://openapi.akool.com/api/open/v3/faceswap/highquality/vidreage"
payload = json.dumps({
"targetImage": [
{
"path": "https://d21ksh0k4smeql.cloudfront.net/crop_1695200391486-4662-0-1695200392027-6110.png",
"opts": "1622,759:2149,776:1869,1085:1875,1345"
}
],
"face_reage": 10,
"modifyVideo": "https://d3t6pcz7y7ey7x.cloudfront.net/Video10__d2a8cf85-10ae-4c2d-8f4b-d818c0a2e4a4.mp4",
"webhookUrl": "http://localhost:3007/api/webhook"
})
headers = {
'Authorization': 'Bearer token',
'Content-Type': 'application/json'
}
response = requests.request("POST", url, headers=headers, data=payload)
print(response.text)
```
**Response**
```json
{
"code": 1000, // Interface returns business status code
"msg": "Please be patient! If your results are not generated in three hours, please check your input image.", // Interface returns status information
"data": {
"_id": "6593c94c0ef703e8c055e3c8", // Interface returns data
"url": "https://***.cloudfront.net/final_71688047459_.pic-1704184129269-4947-f8abc658-fa82-420f-b1b3-c747d7f18e14-8535.jpg", // faceswwap result url
"job_id": "20240102082900592-5653" // Task processing unique id
}
}
```
### Get Reage Result List Byids
```
GET https://openapi.akool.com/api/open/v3/faceswap/result/listbyids?_ids=64ef2f27b33f466877701c6a
```
**Request Headers**
| **Parameter** | **Value** | **Description** |
| ------------- | ------------ | ------------------------------------------- |
| Authorization | Bearer token | Your API Key used for request authorization |
**Query Attributes**
| Parameter | Type | Value | Description |
| --------- | ------ | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `_ids` | String | | Result ids are strings separated by commas. You can get it by returning the `_id` field from [https://openapi.akool.com/api/open/v3/faceswap/highquality/imgreage](https://openapi.akool.com/api/open/v3/faceswap/highquality/imgreage) or [https://openapi.akool.com/api/open/v3/faceswap/highquality/vidreage](https://openapi.akool.com/api/open/v3/faceswap/highquality/vidreage) api. |
**Response Attributes**
| Parameter | Type | Value | Description |
| --------- | ------ | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| code | int | 1000 | Interface returns business status code (1000: success) |
| msg | String | | Interface returns status information |
| data | Object | `result: [{ faceswap_status: "", url: "", createdAt: "" }]` | faceswap\_status: faceswap result status (1 In Queue, 2 Processing, 3 Success, 4 Failed), url: faceswap result url, createdAt: current faceswap action created time |
**Example**
**Request**
```bash cURL
curl --location 'https://openapi.akool.com/api/open/v3/faceswap/result/listbyids?_ids=64ef2f27b33f466877701c6a' \
--header 'Authorization: Bearer token'
```
```java Java
OkHttpClient client = new OkHttpClient().newBuilder()
.build();
MediaType mediaType = MediaType.parse("text/plain");
RequestBody body = RequestBody.create(mediaType, "");
Request request = new Request.Builder()
.url("https://openapi.akool.com/api/open/v3/faceswap/result/listbyids?_ids=64ef2f27b33f466877701c6a")
.method("GET", body)
.addHeader("Authorization", "Bearer token")
.build();
Response response = client.newCall(request).execute();
```
```js Javascript
const myHeaders = new Headers();
myHeaders.append("Authorization", "Bearer token");
const requestOptions = {
method: "GET",
headers: myHeaders,
redirect: "follow"
};
fetch("https://openapi.akool.com/api/open/v3/faceswap/result/listbyids?_ids=64ef2f27b33f466877701c6a", requestOptions)
.then((response) => response.text())
.then((result) => console.log(result))
.catch((error) => console.error(error));
```
```php PHP
'Bearer token'
];
$request = new Request('GET', 'https://openapi.akool.com/api/open/v3/faceswap/result/listbyids?_ids=64ef2f27b33f466877701c6a', $headers);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();
```
```python Python
import requests
url = "https://openapi.akool.com/api/open/v3/faceswap/result/listbyids?_ids=64ef2f27b33f466877701c6a"
payload = {}
headers = {
'Authorization': 'Bearer token'
}
response = requests.request("GET", url, headers=headers, data=payload)
print(response.text)
```
**Response**
```json
{
"code": 1000, // error code
"msg": "OK", // api message
"data": {
"result": [
{
"faceswap_type": 1,
"faceswap_quality": 2,
"faceswap_status": 1, // faceswap result status: 1 In Queue 2 Processing 3 Success 4 failed
"deduction_status": 1,
"image": 1,
"video_duration": 0,
"deduction_duration": 0,
"update_time": 0,
"_id": "64dae65af6e250d4fb2bca63",
"userId": "64d985c5571729d3e2999477",
"uid": 378337,
"url": "https://d21ksh0k4smeql.cloudfront.net/final_material__d71fad6e-a464-43a5-9820-6e4347dce228-80554b9d-2387-4b20-9288-e939952c0ab4-0356.jpg", // faceswwap result url
"createdAt": "2023-08-15T02:43:38.536Z" // current faceswap action created time
}
]
}
}
```
### Reage Task cancel
```
POST https://openapi.akool.com/api/open/v3/faceswap/job/del
```
**Request Headers**
| **Parameter** | **Value** | **Description** |
| ------------- | ------------ | ------------------------------------------- |
| Authorization | Bearer token | Your API Key used for request authorization |
**Body Attributes**
| Parameter | Type | Value | Description |
| --------- | ------ | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| job\_ids | String | | Task id, You can get it by returning the job\_id field based on [https://openapi.akool.com/api/open/v3/faceswap/highquality/imgreage](https://openapi.akool.com/api/open/v3/faceswap/highquality/imgreage) or [https://openapi.akool.com/api/open/v3/faceswap/highquality/vidreage](https://openapi.akool.com/api/open/v3/faceswap/highquality/vidreage) api. |
**Response Attributes**
| Parameter | Type | Value | Description |
| --------- | ------ | ----- | ------------------------------------------------------ |
| code | int | 1000 | Interface returns business status code (1000: success) |
| msg | String | | Interface returns status information |
**Example**
**Body**
```json
{
"job_ids":"" // task id, You can get it by returning the job_id field based on https://openapi.akool.com/api/open/v3/faceswap/highquality/specifyimage or https://openapi.akool.com/api/open/v3/faceswap/highquality/specifyvideo api.
}
```
**Request**
```bash cURL
curl --location 'https://openapi.akool.com/api/open/v3/faceswap/job/del' \
--header 'Authorization: Bearer token' \
--header 'Content-Type: application/json' \
--data '{
"job_ids":""
}'
```
```java Java
OkHttpClient client = new OkHttpClient().newBuilder()
.build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n \"job_ids\":\"\" \n}");
Request request = new Request.Builder()
.url("https://openapi.akool.com/api/open/v3/faceswap/job/del")
.method("POST", body)
.addHeader("Authorization", "Bearer token")
.addHeader("Content-Type", "application/json")
.build();
Response response = client.newCall(request).execute();
```
```js Javascript
const myHeaders = new Headers();
myHeaders.append("Authorization", "Bearer token");
myHeaders.append("Content-Type", "application/json");
const raw = JSON.stringify({
"job_ids": ""
});
const requestOptions = {
method: "POST",
headers: myHeaders,
body: raw,
redirect: "follow"
};
fetch("https://openapi.akool.com/api/open/v3/faceswap/job/del", requestOptions)
.then((response) => response.text())
.then((result) => console.log(result))
.catch((error) => console.error(error));
```
```php PHP
'Bearer token',
'Content-Type' => 'application/json'
];
$body = '{
"job_ids": ""
}';
$request = new Request('POST', 'https://openapi.akool.com/api/open/v3/faceswap/job/del', $headers, $body);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();
```
```python Python
import requests
import json
url = "https://openapi.akool.com/api/open/v3/faceswap/job/del"
payload = json.dumps({
"job_ids": ""
})
headers = {
'Authorization': 'Bearer token',
'Content-Type': 'application/json'
}
response = requests.request("POST", url, headers=headers, data=payload)
print(response.text)
```
**Response**
```json
{
"code": 1000, // Business status code
"msg": "OK" // The interface returns status information
}
```
**Response Code Description**
Please note that if the value of the response code is not equal to 1000, the request is failed or wrong
| **Parameter** | **Value** | **Description** |
| ------------- | --------- | --------------------------------------------------------------------- |
| code | 1000 | Success |
| code | 1003 | Parameter error or Parameter can not be empty |
| code | 1005 | Operation is too frequent |
| code | 1006 | Your quota is not enough |
| code | 1007 | The number of people who can have their faces changed cannot exceed 8 |
| code | 1101 | Invalid authorization or The request token has expired |
| code | 1102 | Authorization cannot be empty |
| code | 1200 | The account has been banned |
# Talking Photo
Source: https://docstest.akool.io/ai-tools-suite/talking-photo
The resources (image, video, voice) generated by our API are valid for 7 days. Please save the relevant resources as soon as possible to prevent expiration.
### Talking Photo
```
POST https://openapi.akool.com/api/open/v3/content/video/createbytalkingphoto
```
**Request Headers**
| **Parameter** | **Value** | **Description** |
| ------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Authorization | Bearer token | Your API Key used for request authorization. You can get from [https://openapi.akool.com/api/open/v3/getToken](https://openapi.akool.com/api/open/v3/getToken) api. |
**Body Attributes**
| Parameter | Type | Value | Description |
| ------------------- | ------ | ----- | ------------------------------------------ |
| talking\_photo\_url | String | | resource address of the talking picture |
| audio\_url | String | | resource address of the talking audio |
| webhookUrl | String | | Callback url address based on HTTP request |
**Response Attributes**
| Parameter | Type | Value | Description |
| --------- | ------ | ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| code | int | 1000 | Interface returns business status code (1000:success) |
| msg | String | | Interface returns status information |
| data | Object | `{ _id:"", video_status:3, video:"" }` | `_id`: Interface returns data status: the status of video: \[1:queueing, 2:processing, 3:completed, 4:failed], `video`: the url of Generated video |
**Example**
**Body**
```json
{
"talking_photo_url":"https://drz0f01yeq1cx.cloudfront.net/1688098804494-e7ca71c3-4266-4ee4-bcbb-ddd1ea490e75-9907.jpg",
"audio_url":"https://drz0f01yeq1cx.cloudfront.net/1710752141387-e7867802-0a92-41d4-b899-9bfb23144929-4946.mp3",
"webhookUrl":"http://localhost:3007/api/open/v3/test/webhook"
}
```
**Request**
```bash cURL
curl --location 'https://openapi.akool.com/api/open/v3/content/video/createbytalkingphoto' \
--header 'Authorization: Bearer token' \
--header 'Content-Type: application/json' \
--data '{
"talking_photo_url":"https://drz0f01yeq1cx.cloudfront.net/1688098804494-e7ca71c3-4266-4ee4-bcbb-ddd1ea490e75-9907.jpg",
"audio_url":"https://drz0f01yeq1cx.cloudfront.net/1710752141387-e7867802-0a92-41d4-b899-9bfb23144929-4946.mp3",
"webhookUrl":"http://localhost:3007/api/open/v3/test/webhook"
}'
```
```java Java
OkHttpClient client = new OkHttpClient().newBuilder()
.build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n \"talking_photo_url\":\"https://drz0f01yeq1cx.cloudfront.net/1688098804494-e7ca71c3-4266-4ee4-bcbb-ddd1ea490e75-9907.jpg\",\n \"audio_url\":\"https://drz0f01yeq1cx.cloudfront.net/1710752141387-e7867802-0a92-41d4-b899-9bfb23144929-4946.mp3\",\n \"webhookUrl\":\"http://localhost:3007/api/open/v3/test/webhook\" \n}");
Request request = new Request.Builder()
.url("https://openapi.akool.com/api/open/v3/content/video/createbytalkingphoto")
.method("POST", body)
.addHeader("Authorization", "Bearer token")
.addHeader("Content-Type", "application/json")
.build();
Response response = client.newCall(request).execute();
```
```js Javascript
const myHeaders = new Headers();
myHeaders.append("Authorization", "Bearer token");
myHeaders.append("Content-Type", "application/json");
const raw = JSON.stringify({
"talking_photo_url": "https://drz0f01yeq1cx.cloudfront.net/1688098804494-e7ca71c3-4266-4ee4-bcbb-ddd1ea490e75-9907.jpg",
"audio_url": "https://drz0f01yeq1cx.cloudfront.net/1710752141387-e7867802-0a92-41d4-b899-9bfb23144929-4946.mp3",
"webhookUrl": "http://localhost:3007/api/open/v3/test/webhook"
});
const requestOptions = {
method: "POST",
headers: myHeaders,
body: raw,
redirect: "follow"
};
fetch("https://openapi.akool.com/api/open/v3/content/video/createbytalkingphoto", requestOptions)
.then((response) => response.text())
.then((result) => console.log(result))
.catch((error) => console.error(error));
```
```php PHP
'Bearer token',
'Content-Type' => 'application/json'
];
$body = '{
"talking_photo_url": "https://drz0f01yeq1cx.cloudfront.net/1688098804494-e7ca71c3-4266-4ee4-bcbb-ddd1ea490e75-9907.jpg",
"audio_url": "https://drz0f01yeq1cx.cloudfront.net/1710752141387-e7867802-0a92-41d4-b899-9bfb23144929-4946.mp3",
"webhookUrl": "http://localhost:3007/api/open/v3/test/webhook"
}';
$request = new Request('POST', 'https://openapi.akool.com/api/open/v3/content/video/createbytalkingphoto', $headers, $body);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();
```
```python Python
import requests
import json
url = "https://openapi.akool.com/api/open/v3/content/video/createbytalkingphoto"
payload = json.dumps({
"talking_photo_url": "https://drz0f01yeq1cx.cloudfront.net/1688098804494-e7ca71c3-4266-4ee4-bcbb-ddd1ea490e75-9907.jpg",
"audio_url": "https://drz0f01yeq1cx.cloudfront.net/1710752141387-e7867802-0a92-41d4-b899-9bfb23144929-4946.mp3",
"webhookUrl": "http://localhost:3007/api/open/v3/test/webhook"
})
headers = {
'Authorization': 'Bearer token',
'Content-Type': 'application/json'
}
response = requests.request("POST", url, headers=headers, data=payload)
print(response.text)
```
**Response**
```json
{
"code": 1000, // API code
"msg": "OK",
"data": {
"faceswap_quality": 2,
"storage_loc": 1,
"_id": "64dd90f9f0b6684651e90d60",
"create_time": 1692242169057,
"uid": 378337,
"type": 5,
"from": 2,
"video_lock_duration": 0.8,
"deduction_lock_duration": 10,
"external_video": "",
"talking_photo": "https://***.cloudfront.net/1692242161763-4fb8c3c2-018b-4b84-82e9-413c81f26b3a-6613.jpeg",
"video": "", // the url of Generated video
"__v": 0,
"video_status": 1 // current status of video： 【1：queueing（The requested operation is being processed），2：processing（The requested operation is being processing），3：completed（The request operation has been processed successfully），4：failed（The request operation processing failed, the reason for the failure can be viewed in the talkingphoto details.）】
}
}
```
### Get Video Info Result
```
GET https://openapi.akool.com/api/open/v3/content/video/infobymodelid?video_model_id=64dd838cf0b6684651e90217
```
**Request Headers**
| **Parameter** | **Value** | **Description** |
| ------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Authorization | Bearer token | Your API Key used for request authorization. You can get from [https://openapi.akool.com/api/open/v3/getToken](https://openapi.akool.com/api/open/v3/getToken) api. |
**Query Attributes**
| **Parameter** | **Type** | **Value** | **Description** |
| ---------------- | -------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| video\_model\_id | String | | video db id：You can get it based on the \_id field returned by [https://openapi.akool.com/api/open/v3/content/video/createbytalkingphoto](https://openapi.akool.com/api/open/v3/content/video/createbytalkingphoto) api. |
**Response Attributes**
| **Parameter** | **Type** | **Value** | **Description** |
| ------------- | -------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| code | int | 1000 | Interface returns business status code (1000:success) |
| msg | String | OK | Interface returns status information |
| data | Object | `{ video_status:1, _id:"", video:"" }` | `video_status`: the status of video: \[1:queueing, 2:processing, 3:completed, 4:failed], `video`: Generated video resource url, `_id`: Interface returns data |
**Example**
**Request**
```bash cURL
curl --location 'https://openapi.akool.com/api/open/v3/content/video/infobymodelid?video_model_id=64dd838cf0b6684651e90217' \
--header 'Authorization: Bearer token'
```
```java Java
OkHttpClient client = new OkHttpClient().newBuilder()
.build();
MediaType mediaType = MediaType.parse("text/plain");
RequestBody body = RequestBody.create(mediaType, "");
Request request = new Request.Builder()
.url("https://openapi.akool.com/api/open/v3/content/video/infobymodelid?video_model_id=64dd838cf0b6684651e90217")
.method("GET", body)
.addHeader("Authorization", "Bearer token")
.build();
Response response = client.newCall(request).execute();
```
```js Javascript
const myHeaders = new Headers();
myHeaders.append("Authorization", "Bearer token");
const requestOptions = {
method: "GET",
headers: myHeaders,
redirect: "follow"
};
fetch("https://openapi.akool.com/api/open/v3/content/video/infobymodelid?video_model_id=64dd838cf0b6684651e90217", requestOptions)
.then((response) => response.text())
.then((result) => console.log(result))
.catch((error) => console.error(error));
```
```php PHP
'Bearer token'
];
$request = new Request('GET', 'https://openapi.akool.com/api/open/v3/content/video/infobymodelid?video_model_id=64dd838cf0b6684651e90217', $headers);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();
```
```python Python
import requests
url = "https://openapi.akool.com/api/open/v3/content/video/infobymodelid?video_model_id=64dd838cf0b6684651e90217"
payload = {}
headers = {
'Authorization': 'Bearer token'
}
response = requests.request("GET", url, headers=headers, data=payload)
print(response.text)
```
**Response**
```json
{
"code": 1000,
"msg": "OK",
"data": {
"faceswap_quality": 2,
"storage_loc": 1,
"_id": "64dd92c1f0b6684651e90e09",
"create_time": 1692242625334,
"uid": 378337,
"type": 2,
"from": 1,
"video_id": "0acfed62e24f4cfd8801c9e846347b1d",
"video_lock_duration": 7.91,
"deduction_lock_duration": 10,
"video_status": 2, // current status of video： 【1：queueing（The requested operation is being processed），2：processing（The requested operation is being processing），3：completed（The request operation has been processed successfully），4：failed（The request operation processing failed, the reason for the failure can be viewed in the talkingphoto details.）】
"external_video": "",
"video": "" // Generated video resource url
}
}
```
**Response Code Description**
Please note that if the value of the response code is not equal to 1000, the request is failed or wrong
| **Parameter** | **Value** | **Description** |
| ------------- | --------- | ------------------------------------------------------ |
| code | 1000 | Success |
| code | 1003 | Parameter error or Parameter can not be empty |
| code | 1008 | The content you get does not exist |
| code | 1009 | You do not have permission to operate |
| code | 1015 | Create video error, please try again later |
| code | 1101 | Invalid authorization or The request token has expired |
| code | 1102 | Authorization cannot be empty |
| code | 1200 | The account has been banned |
| code | 1201 | Create audio error, please try again later |
# Talking Avatar
Source: https://docstest.akool.io/ai-tools-suite/talkingavatar
Talking Avatar API documentation
The resources (image, video, voice) generated by our API are valid for 7 days. Please save the relevant resources as soon as possible to prevent expiration.
### Description
* First you need to generate the voice through the following method or directly provide a link to the available voice file
* If you want to use the system's sound model to generate speech, you need to generate a link by calling the interface [Create TTS](https://docs.akool.com/ai-tools-suite/voiceLab#create-text-to-speech)
* If you want to use the sound model you provide to generate speech, you need to generate a link by calling the interface [Create Voice Clone](https://docs.akool.com/ai-tools-suite/voiceLab#create-voice-clone)
* Secondly, you need to provide an avatar link, which can be a picture or video.
* If you want to use the avatar provided by the system, you can obtain it through the interface [Get Avatar List](https://docs.akool.com/ai-tools-suite/talking-avatar#get-talking-avatar-list) .Or provide your own avatar url.
* Then, you need to generate an avatar video by calling the API [Create Talking Avatar](https://docs.akool.com/ai-tools-suite/talking-avatar#create-talking-avatar)
* Finally,The processing status will be returned promptly through the provided callback address, or you can also query it by calling the interface [Get Video Info](https://docs.akool.com/ai-tools-suite/talking-avatar#get-video-info)
### Get Talking Avatar List
```http
GET https://openapi.akool.com/api/open/v3/avatar/list
```
**Request Headers**
| **Parameter** | **Value** | **Description** |
| ------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------ |
| Authorization | Bearer `{token}` | Your API Key used for request authorization. [getToken](https://docs.akool.com/authentication/usage#get-the-token) |
**Query Attributes**
| **Parameter** | **Type** | **Value** | **Description** |
| ------------- | -------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| from | Number | 2、3 | 2 represents the official avatar of Akool, 3 represents the avatar uploaded by the user themselves，If empty, returns all avatars by default. |
| type | Number | 1、2 | 1 represents the talking avatar of Akool, 2 represents the streaming avatar of Akool，If empty, returns all avatars by default. |
| page | Number | 1 | Current number of pages，Default is 1. |
| size | Number | 10 | Current number of returns per page，Default is 100. |
**Response Attributes**
| **Parameter** | **Type** | **Value** | **Description** |
| ------------- | -------- | -------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| code | int | 1000 | Interface returns business status code(1000:success) |
| msg | String | OK | Interface returns status information |
| data | Array | `[{ avatar_id: "xx", url: "" }]` | avatar\_id: Used by avatar interface and creating avatar interface. url: You can preview the avatar via the link. |
**Example**
**Request**
```bash cURL
curl --location 'https://openapi.akool.com/api/open/v3/avatar/list?from=2&page=1&size=100' \
--header 'Authorization: Bearer {{Authorization}}'
```
```java Java
OkHttpClient client = new OkHttpClient().newBuilder()
.build();
MediaType mediaType = MediaType.parse("text/plain");
RequestBody body = RequestBody.create(mediaType, "");
Request request = new Request.Builder()
.url("https://openapi.akool.com/api/open/v3/avatar/list?from=2&page=1&size=100")
.method("GET", body)
.addHeader("Authorization", "Bearer {{Authorization}}")
.build();
Response response = client.newCall(request).execute();
```
```js Javascript
const myHeaders = new Headers();
myHeaders.append("Authorization", "Bearer {{Authorization}}");
const requestOptions = {
method: "GET",
headers: myHeaders,
redirect: "follow",
};
fetch(
"https://openapi.akool.com/api/open/v3/avatar/list?from=2&page=1&size=100",
requestOptions
)
.then((response) => response.text())
.then((result) => console.log(result))
.catch((error) => console.error(error));
```
```php PHP
'{{Authorization}}'
];
$request = new Request('GET', 'https://openapi.akool.com/api/open/v3/avatar/list?from=2&page=1&size=100', $headers);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();
```
```python Python
import requests
url = "https://openapi.akool.com/api/open/v3/avatar/list?from=2&page=1&size=100"
payload = {}
headers = {
'Authorization': 'Bearer {{Authorization}}'
}
response = requests.request("GET", url, headers=headers, data=payload)
print(response.text)
```
**Response**
```json
{
"code": 1000,
"msg": "ok",
"data": [
{
"name": "Yasmin in White shirt", // avatar name
"avatar_id": "Yasmin_in_White_shirt_20231121", // parameter values required to create talkingavatar
"url": "https://drz0f01yeq1cx.cloudfront.net/1700786304161-b574407f-f926-4b3e-bba7-dc77d1742e60-8169.png", // avatar url
"gender": "female", // avatar gender
"thumbnailUrl": "https://drz0f01yeq1cx.cloudfront.net/avatar/thumbnail/1700786304161-b574407f-f926-4b3e-bba7-dc77d1742e60-8169.png", // avatar thumbnail
"from": 2 // parameter values required to create talkingavatar
}
]
}
```
### Create Talking avatar
```
POST https://openapi.akool.com/api/open/v3/talkingavatar/create
```
**Request Headers**
| **Parameter** | **Value** | **Description** |
| ------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------ |
| Authorization | Bearer `{token}` | Your API Key used for request authorization.[getToken](https://docs.akool.com/authentication/usage#get-the-token). |
**Body Attributes**
| Parameter | Type | Value | Description |
| ----------------------- | --------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| width | Number | 3840 | Set the output video width,must be 3840 |
| height | Number | 2160 | Set the output video height,must be 2160 |
| avatar\_from | Number | 2 or 3 | You use the avatar from of the avatar model, and you can get from [https://openapi.akool.com/api/open/v3/avatar/list](https://docs.akool.com/ai-tools-suite/talking-avatar#get-avatar-list) api, you will obtain the field 【from】 and pass it here. If you provide an avatar URL yourself, avatar\_from must be 3. |
| webhookUrl | String | | Callback url address based on HTTP request. |
| elements | \[Object] | | Collection of elements passed in in the video |
| \[elements].url | String | | Link to element(When type is equal to image, url can be either a link or a Hexadecimal Color Code). When avatar\_from =2, you don't need to pass this parameter. The image formats currently only support ".png", ".jpg", ".jpeg", ".webp", and the video formats currently only support ".mp4", ".mov", ".avi" |
| \[elements].scale\_x | Number | 1 | Horizontal scaling ratio(Required when type is equal to image or avatar) |
| \[elements].scale\_y | Number | 1 | Vertical scaling ratio (Required when type is equal to image or avatar) |
| \[elements].offset\_x | Number | | Horizontal offset of the upper left corner of the element from the video setting area (in pixels)(Required when type is equal to image or avatar) |
| \[elements].offset\_y | Number | | Vertical offset of the upper left corner of the element from the video setting area (in pixels)(Required when type is equal to image or avatar) |
| \[elements].height | Number | | The height of the element |
| \[elements].width | Number | | The width of the element |
| \[elements].type | String | | Element type（avatar、image、audio） |
| \[elements].avatar\_id | String | | When type is equal to avatar, you use the avatar\_id of the avatar model, and you can get from [https://openapi.akool.com/api/open/v3/avatar/list](https://docs.akool.com/ai-tools-suite/talking-avatar#get-avatar-list) api, you will obtain the field 【avatar\_id】 and pass it here。 If you provide an avatar URL yourself, you don't need to pass this parameter. |
| \[elements].input\_text | String | | Audio element support, for input text, the per-request character limit depends on the subscription plan: Pro – 5,000, Pro Max – 10,000, Business – 50,000. If both the URL and the input text fields are passed, the URL takes precedence. The "input\_text" and "voice\_id" fields must both be present. |
| \[elements].voice\_id | String | | Audio element support. [getVoiceId](https://docs.akool.com/ai-tools-suite/voiceLab#get-voice-list) |
**Response Attributes**
| Parameter | Type | Value | Description |
| --------- | ------ | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| code | int | 1000 | Interface returns business status code (1000:success) |
| msg | String | | Interface returns status information |
| data | Object | `{ _id:"", video_status:3, video:"" }` | `_id`: Interface returns data status: the status of video: 【1:queueing, 2:processing, 3:completed, 4:failed】, `video`: the url of Generated video |
Please note that the generated video link can only be obtained when video\_status is equal to 3.
We provide 2 methods:
1. Obtain through [webhook](https://docs.akool.com/ai-tools-suite/webhook#encryption-and-decryption-technology-solution)
2. Obtain by polling the following interface [Get Video Info](https://docs.akool.com/ai-tools-suite/avatar#get-video-info)
**Example**
**Body**
```json
{
"width": 3840,
"height": 2160,
"avatar_from": 3,
"elements": [
{
"type": "image",
"url": "https://drz0f01yeq1cx.cloudfront.net/1729480978805-talkingAvatarbg.png",
"width": 780,
"height": 438,
"scale_x": 1,
"scale_y": 1,
"offset_x": 1920,
"offset_y": 1080
},
{
"type": "avatar",
"url": "https://drz0f01yeq1cx.cloudfront.net/1735009621724-7ce105c6-ed9a-4d13-9061-7e3df59d9798-7953.mp4",
"scale_x": 1,
"scale_y": 1,
"width": 1080,
"height": 1080,
"offset_x": 1920,
"offset_y": 1080
},
{
"type": "audio",
"url": "https://drz0f01yeq1cx.cloudfront.net/1729666642023-bd6ad5f1-d558-40c7-b720-ad729688f814-6403.mp3",
"input_text": "A military parade is a formation of military personnels whose movement is restricted by close-order manoeuvering known as drilling or marching. Large military parades are today held on major holidays and military events around the world.A military parade is a formation of military personnels whose movement is restricted by close-order manoeuvering known as drilling or marching. Large military parades are today held on major holidays and military events around the world.A military parade is a formation of military personnels whose movement is restricted by close-order manoeuvering known as drilling or marching. Large military parades are today held on major holidays and military events around the world.",
"voice_id": "6889b628662160e2caad5dbc"
}
],
"webhookUrl": ""
}
```
**Request**
```bash cURL
curl --location 'https://openapi.akool.com/api/open/v3/talkingavatar/create' \
--header 'Authorization: Bearer token' \
--header 'Content-Type: application/json' \
--data '{
"width": 3840,
"height": 2160,
"avatar_from": 3,
"elements": [
{
"type": "image",
"url": "https://drz0f01yeq1cx.cloudfront.net/1729480978805-talkingAvatarbg.png",
"width": 780,
"height": 438,
"scale_x": 1,
"scale_y": 1,
"offset_x": 1920,
"offset_y": 1080
},
{
"type": "avatar",
"url": "https://drz0f01yeq1cx.cloudfront.net/1735009621724-7ce105c6-ed9a-4d13-9061-7e3df59d9798-7953.mp4",
"scale_x": 1,
"scale_y": 1,
"width": 1080,
"height": 1080,
"offset_x": 1920,
"offset_y": 1080
},
{
"type": "audio",
"url": "https://drz0f01yeq1cx.cloudfront.net/1729666642023-bd6ad5f1-d558-40c7-b720-ad729688f814-6403.mp3",
"input_text": "A military parade is a formation of military personnels whose movement is restricted by close-order manoeuvering known as drilling or marching. Large military parades are today held on major holidays and military events around the world.A military parade is a formation of military personnels whose movement is restricted by close-order manoeuvering known as drilling or marching. Large military parades are today held on major holidays and military events around the world.A military parade is a formation of military personnels whose movement is restricted by close-order manoeuvering known as drilling or marching. Large military parades are today held on major holidays and military events around the world.",
"voice_id": "6889b628662160e2caad5dbc"
}
]
}'
```
```java Java
OkHttpClient client = new OkHttpClient().newBuilder()
.build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n \"width\": 3840,\n \"height\": 2160,\n \"avatar_from\": 3,\n \"elements\": [\n {\n \"type\": \"image\",\n \"url\": \"https://drz0f01yeq1cx.cloudfront.net/1729480978805-talkingAvatarbg.png\",\n \"width\": 780,\n \"height\": 438,\n \"scale_x\": 1,\n \"scale_y\": 1,\n \"offset_x\": 1920,\n \"offset_y\": 1080\n },\n {\n \"type\": \"avatar\",\n \"url\": \"https://drz0f01yeq1cx.cloudfront.net/1735009621724-7ce105c6-ed9a-4d13-9061-7e3df59d9798-7953.mp4\",\n \"scale_x\": 1,\n \"scale_y\": 1,\n \"width\": 1080,\n \"height\": 1080,\n \"offset_x\": 1920,\n \"offset_y\": 1080\n },\n {\n \"type\": \"audio\",\n \"url\": \"https://drz0f01yeq1cx.cloudfront.net/1729666642023-bd6ad5f1-d558-40c7-b720-ad729688f814-6403.mp3\"\n }\n ]\n}");
Request request = new Request.Builder()
.url("https://openapi.akool.com/api/open/v3/talkingavatar/create")
.method("POST", body)
.addHeader("Authorization", "Bearer token")
.addHeader("Content-Type", "application/json")
.build();
Response response = client.newCall(request).execute();
```
```js Javascript
const myHeaders = new Headers();
myHeaders.append("Authorization", "Bearer token");
myHeaders.append("Content-Type", "application/json");
const raw = JSON.stringify({
"width": 3840,
"height": 2160,
"avatar_from": 3,
"elements": [
{
"type": "image",
"url": "https://drz0f01yeq1cx.cloudfront.net/1729480978805-talkingAvatarbg.png",
"width": 780,
"height": 438,
"scale_x": 1,
"scale_y": 1,
"offset_x": 1920,
"offset_y": 1080
},
{
"type": "avatar",
"url": "https://drz0f01yeq1cx.cloudfront.net/1735009621724-7ce105c6-ed9a-4d13-9061-7e3df59d9798-7953.mp4",
"scale_x": 1,
"scale_y": 1,
"width": 1080,
"height": 1080,
"offset_x": 1920,
"offset_y": 1080
},
{
"type": "audio",
"url": "https://drz0f01yeq1cx.cloudfront.net/1729666642023-bd6ad5f1-d558-40c7-b720-ad729688f814-6403.mp3",
"input_text": "A military parade is a formation of military personnels whose movement is restricted by close-order manoeuvering known as drilling or marching. Large military parades are today held on major holidays and military events around the world.A military parade is a formation of military personnels whose movement is restricted by close-order manoeuvering known as drilling or marching. Large military parades are today held on major holidays and military events around the world.A military parade is a formation of military personnels whose movement is restricted by close-order manoeuvering known as drilling or marching. Large military parades are today held on major holidays and military events around the world.",
"voice_id": "6889b628662160e2caad5dbc"
}
]
});
const requestOptions = {
method: "POST",
headers: myHeaders,
body: raw,
redirect: "follow"
};
fetch("https://openapi.akool.com/api/open/v3/talkingavatar/create", requestOptions)
.then((response) => response.text())
.then((result) => console.log(result))
.catch((error) => console.error(error));
```
```php PHP
'Bearer token',
'Content-Type' => 'application/json'
];
$body = '{
"width": 3840,
"height": 2160,
"avatar_from": 3,
"elements": [
{
"type": "image",
"url": "https://drz0f01yeq1cx.cloudfront.net/1729480978805-talkingAvatarbg.png",
"width": 780,
"height": 438,
"scale_x": 1,
"scale_y": 1,
"offset_x": 1920,
"offset_y": 1080
},
{
"type": "avatar",
"url": "https://drz0f01yeq1cx.cloudfront.net/1735009621724-7ce105c6-ed9a-4d13-9061-7e3df59d9798-7953.mp4",
"scale_x": 1,
"scale_y": 1,
"width": 1080,
"height": 1080,
"offset_x": 1920,
"offset_y": 1080
},
{
"type": "audio",
"url": "https://drz0f01yeq1cx.cloudfront.net/1729666642023-bd6ad5f1-d558-40c7-b720-ad729688f814-6403.mp3"
}
]
}';
$request = new Request('POST', 'https://openapi.akool.com/api/open/v3/talkingavatar/create', $headers, $body);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();
```
```python Python
import requests
import json
url = "https://openapi.akool.com/api/open/v3/talkingavatar/create"
payload = json.dumps({
"width": 3840,
"height": 2160,
"avatar_from": 3,
"elements": [
{
"type": "image",
"url": "https://drz0f01yeq1cx.cloudfront.net/1729480978805-talkingAvatarbg.png",
"width": 780,
"height": 438,
"scale_x": 1,
"scale_y": 1,
"offset_x": 1920,
"offset_y": 1080
},
{
"type": "avatar",
"url": "https://drz0f01yeq1cx.cloudfront.net/1735009621724-7ce105c6-ed9a-4d13-9061-7e3df59d9798-7953.mp4",
"scale_x": 1,
"scale_y": 1,
"width": 1080,
"height": 1080,
"offset_x": 1920,
"offset_y": 1080
},
{
"type": "audio",
"url": "https://drz0f01yeq1cx.cloudfront.net/1729666642023-bd6ad5f1-d558-40c7-b720-ad729688f814-6403.mp3"
}
]
})
headers = {
'Authorization': 'Bearer token',
'Content-Type': 'application/json'
}
response = requests.request("POST", url, headers=headers, data=payload)
print(response.text)
```
**Response**
```json
{
"code": 1000,
"msg": "OK",
"data": {
"_id": "67491cdb4d9d1664a9782292",
"uid": 100002,
"video_id": "f1a489f4-0cca-4723-843b-e42003dc9f32",
"task_id": "67491cdb1acd9d0ce2cc8998",
"video_status": 1,
"video": "",
"create_time": 1732844763774
}
}
```
### Get Video Info
```
GET https://openapi.akool.com/api/open/v3/content/video/infobymodelid?video_model_id=64dd838cf0b6684651e90217
```
**Request Headers**
| **Parameter** | **Value** | **Description** |
| ------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------ |
| Authorization | Bearer `{token}` | Your API Key used for request authorization.[getToken](https://docs.akool.com/authentication/usage#get-the-token). |
**Query Attributes**
| **Parameter** | **Type** | **Value** | **Description** |
| ---------------- | -------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| video\_model\_id | String | NULL | video db id: You can get it based on the `_id` field returned by [https://openapi.akool.com/api/open/v3/talkingavatar/create](https://docs.akool.com/ai-tools-suite/talking-avatar#create-talking-avatar) . |
**Response Attributes**
| **Parameter** | **Type** | **Value** | **Description** |
| ------------- | -------- | -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| code | int | 1000 | Interface returns business status code(1000:success) |
| msg | String | OK | Interface returns status information |
| data | Object | `{ video_status:1, _id:"", video:"" }` | video\_status: the status of video：【1:queueing, 2:processing, 3:completed, 4:failed】 video: Generated video resource url \_id: Interface returns data |
**Example**
**Request**
```bash cURL
curl --location 'https://openapi.akool.com/api/open/v3/content/video/infobymodelid?video_model_id=64b126c4a680e8edea44f02b' \
--header 'Authorization: Bearer token'
```
```java Java
OkHttpClient client = new OkHttpClient().newBuilder()
.build();
MediaType mediaType = MediaType.parse("text/plain");
RequestBody body = RequestBody.create(mediaType, "");
Request request = new Request.Builder()
.url("https://openapi.akool.com/api/open/v3/content/video/infobymodelid?video_model_id=64b126c4a680e8edea44f02b")
.method("GET", body)
.addHeader("Authorization", "Bearer token")
.build();
Response response = client.newCall(request).execute();
```
```js Javascript
const myHeaders = new Headers();
myHeaders.append("Authorization", "Bearer token");
const requestOptions = {
method: "GET",
headers: myHeaders,
redirect: "follow",
};
fetch(
"https://openapi.akool.com/api/open/v3/content/video/infobymodelid?video_model_id=64b126c4a680e8edea44f02b",
requestOptions
)
.then((response) => response.text())
.then((result) => console.log(result))
.catch((error) => console.error(error));
```
```php PHP
'Bearer token'
];
$request = new Request('GET', 'https://openapi.akool.com/api/open/v3/content/video/infobymodelid?video_model_id=64b126c4a680e8edea44f02b', $headers);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();
```
```python Python
import requests
url = "https://openapi.akool.com/api/open/v3/content/video/infobymodelid?video_model_id=64b126c4a680e8edea44f02b"
payload = {}
headers = {
'Authorization': 'Bearer token'
}
response = requests.request("GET", url, headers=headers, data=payload)
print(response.text)
```
**Response**
```json
{
"code": 1000,
"msg": "OK",
"data": {
"_id": "64dd92c1f0b6684651e90e09",
"create_time": 1692242625334, // content creation time
"uid": 378337,
"video_id": "0acfed62e24f4cfd8801c9e846347b1d", // video id
"deduction_duration": 10, // credits consumed by the final result
"video_status": 2, // current status of video： 【1：queueing（The requested operation is being processed），2：processing（The requested operation is being processing），3：completed（The request operation has been processed successfully），4：failed（The request operation processing failed, the reason for the failure can be viewed in the video translation details.）】
"video": "" // Generated video resource url
}
}
```
### Get Avatar Detail
```
GET https://openapi.akool.com/api/open/v3/avatar/detail
```
**Request Headers**
| **Parameter** | **Value** | **Description** |
| ------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------ |
| Authorization | Bearer `{token}` | Your API Key used for request authorization. [getToken](https://docs.akool.com/authentication/usage#get-the-token) |
**Query Attributes**
| **Parameter** | **Type** | **Value** | **Description** |
| ------------- | -------- | --------- | ----------------- |
| id | String | | avatar record id. |
**Response Attributes**
| **Parameter** | **Type** | **Value** | **Description** |
| ------------- | -------- | -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| code | int | 1000 | Interface returns business status code(1000:success) |
| msg | String | OK | Interface returns status information |
| data | Array | `[{ avatar_id: "xx", url: "", status: "" }]` | avatar\_id: Used by avatar interface and creating avatar interface. url: You can preview the avatar via the link. status: 1-queueing 2-processing），3：completed 4-failed |
**Example**
**Request**
```bash cURL
curl --location 'https://openapi.akool.com/api/open/v3/avatar/detail?id=66a1a02d591ad336275eda62' \
--header 'Authorization: Bearer {{Authorization}}'
```
```java Java
OkHttpClient client = new OkHttpClient().newBuilder()
.build();
MediaType mediaType = MediaType.parse("text/plain");
RequestBody body = RequestBody.create(mediaType, "");
Request request = new Request.Builder()
.url("https://openapi.akool.com/api/open/v3/avatar/detail?id=66a1a02d591ad336275eda62")
.method("GET", body)
.addHeader("Authorization", "Bearer {{Authorization}}")
.build();
Response response = client.newCall(request).execute();
```
```js Javascript
const myHeaders = new Headers();
myHeaders.append("Authorization", "Bearer {{Authorization}}");
const requestOptions = {
method: "GET",
headers: myHeaders,
redirect: "follow",
};
fetch(
"https://openapi.akool.com/api/open/v3/avatar/detail?id=66a1a02d591ad336275eda62,
requestOptions
)
.then((response) => response.text())
.then((result) => console.log(result))
.catch((error) => console.error(error));
```
```php PHP
'{{Authorization}}'
];
$request = new Request('GET', 'https://openapi.akool.com/api/open/v3/avatar/detail?66a1a02d591ad336275eda62', $headers);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();
```
```python Python
import requests
url = "https://openapi.akool.com/api/open/v3/avatar/detail?id=66a1a02d591ad336275eda62"
payload = {}
headers = {
'Authorization': 'Bearer {{Authorization}}'
}
response = requests.request("GET", url, headers=headers, data=payload)
print(response.text)
```
**Response**
```json
{
"code": 1000,
"msg": "ok",
"data": [
{
"_id": "66a1a02d591ad336275eda62",
"uid": 100010,
"type": 2,
"from": 3,
"status": 3,
"name": "30870eb0",
"url": "https://drz0f01yeq1cx.cloudfront.net/1721868487350-6b4cc614038643eb9f842f4ddc3d5d56.mp4"
}
]
}
```
### Upload Talking Avatar
```
POST https://openapi.akool.com/api/open/v3/avatar/create
```
**Request Headers**
| **Parameter** | **Value** | **Description** |
| ------------- | ------------ | ------------------------------------------------------------------------------------------------------------------ |
| Authorization | Bearer token | Your API Key used for request authorization. [getToken](https://docs.akool.com/authentication/usage#get-the-token) |
**Body Attributes**
| **Parameter** | **Type** | **Value** | **Description** |
| ------------- | -------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| url | String | | Avatar resource link. It is recommended that the video be about one minute long, and the avatar in the video content should rotate at a small angle and be clear. |
| avatar\_id | String | | avatar unique ID，Can only contain /^a-zA-Z0-9/. |
| name | String | | Avatar display name for easier identification and management. |
| type | String | 1 | Avatar type, 1 represents talking avatar |
**Response Attributes**
| **Parameter** | **Type** | **Value** | **Description** |
| ------------- | -------- | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| code | int | 1000 | Interface returns business status code(1000:success) |
| msg | String | OK | Interface returns status information |
| data | Array | `[{ avatar_id: "xx", url: "", status: 1 }]` | avatar\_id: Used by creating live avatar interface. url: You can preview the avatar via the link. status: 1-queueing, 2-processing, 3-success, 4-failed |
**Example**
**Request**
```bash cURL
curl --location 'https://openapi.akool.com/api/open/v3/avatar/create' \
--header 'authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjY0ZDk4NWM1NTcxNzI5ZDNlMjk5OTQ3NyIsInVpZCI6Mzc4MzM3LCJlbWFpbCI6Imh1Y2hlbkBha29vbC5jb20iLCJjcmVkZW50aWFsSWQiOiI2NjE1MGZmM2Q5MWRmYjc4OWYyNjFmNjEiLCJmaXJzdE5hbWUiOiJjaGVuIiwiZnJvbSI6InRvTyIsInR5cGUiOiJ1c2VyIiwiaWF0IjoxNzEyNzE0ODI4LCJleHAiOjIwMjM3NTQ4Mjh9.e050LbczNhUx-Gprqb1NSYhBCKKH2xMqln3cMnAABmE' \
--header 'Content-Type: application/json' \
--data '{
"url": "https://drz0f01yeq1cx.cloudfront.net/1721197444322-leijun000.mp4",
"avatar_id": "HHdEKhn7k7vVBlR5FSi0e",
"name": "My Talking Avatar",
"type": 1
}'
```
```java Java
OkHttpClient client = new OkHttpClient().newBuilder()
.build();
MediaType mediaType = MediaType.parse("text/plain");
RequestBody body = RequestBody.create(mediaType, "{\n \n \"url\": \"https://drz0f01yeq1cx.cloudfront.net/1721197444322-leijun000.mp4\",\n \"avatar_id\": \"HHdEKhn7k7vVBlR5FSi0e\",\n \"name\": \"My Talking Avatar\",\n \"type\": 1\n}");
Request request = new Request.Builder()
.url("https://openapi.akool.com/api/open/v3/avatar/create")
.method("POST", body)
.addHeader("Authorization", "Bearer {{Authorization}}")
.build();
Response response = client.newCall(request).execute();
```
```js Javascript
const myHeaders = new Headers();
myHeaders.append("Authorization", "Bearer {{Authorization}}");
const raw = JSON.stringify({
"url": "https://drz0f01yeq1cx.cloudfront.net/1721197444322-leijun000.mp4",
"avatar_id": "HHdEKhn7k7vVBlR5FSi0e",
"name": "My Talking Avatar",
"type": 1
});
const requestOptions = {
method: "POST",
headers: myHeaders,
redirect: "follow",
body: raw
};
fetch(
"https://openapi.akool.com/api/open/v3/avatar/create",
requestOptions
)
.then((response) => response.text())
.then((result) => console.log(result))
.catch((error) => console.error(error));
```
```php PHP
'{{Authorization}}'
];
$body = '{
"url": "https://drz0f01yeq1cx.cloudfront.net/1721197444322-leijun000.mp4",
"avatar_id": "HHdEKhn7k7vVBlR5FSi0e",
"name": "My Talking Avatar",
"type": 1
}';
$request = new Request('POST', 'https://openapi.akool.com/api/open/v3/avatar/create', $headers, $body);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();
```
```python Python
import requests
url = "https://openapi.akool.com/api/open/v3/avatar/create"
payload = json.dumps({
"url": "https://drz0f01yeq1cx.cloudfront.net/1721197444322-leijun000.mp4",
"avatar_id": "HHdEKhn7k7vVBlR5FSi0e",
"name": "My Talking Avatar",
"type": 1
});
headers = {
'Authorization': 'Bearer {{Authorization}}'
}
response = requests.request("POST", url, headers=headers, data=payload)
print(response.text)
```
**Response**
```json
{
"code": 1000,
"msg": "ok",
"data": [
{
"_id": "655ffeada6976ea317087193",
"disabled": false,
"uid": 1,
"type": 1,
"from": 2,
"status": 1,
"sort": 12,
"create_time": 1700788730000,
"name": "Yasmin in White shirt",
"avatar_id": "Yasmin_in_White_shirt_20231121",
"url": "https://drz0f01yeq1cx.cloudfront.net/1700786304161-b574407f-f926-4b3e-bba7-dc77d1742e60-8169.png",
"modify_url": "https://drz0f01yeq1cx.cloudfront.net/1700786304161-b574407f-f926-4b3e-bba7-dc77d1742e60-8169.png",
"gender": "female",
"thumbnailUrl": "https://drz0f01yeq1cx.cloudfront.net/avatar/thumbnail/1700786304161-b574407f-f926-4b3e-bba7-dc77d1742e60-8169.png",
"crop_arr": []
}
]
}
```
**Response Code Description**
Please note that if the value of the response code is not equal to 1000, the
request is failed or wrong
| **Parameter** | **Value** | **Description** |
| ------------- | --------- | --------------------------------------------- |
| code | 1000 | Success |
| code | 1003 | Parameter error or Parameter can not be empty |
| code | 1006 | Your quota is not enough |
| code | 1109 | create avatar video error |
| code | 1102 | Authorization cannot be empty |
| code | 1200 | The account has been banned |
| code | 1201 | Create audio error, please try again later |
# Video Translation
Source: https://docstest.akool.io/ai-tools-suite/video-translation
The resources (image, video, voice) generated by our API are valid for 7 days.
Please save the relevant resources as soon as possible to prevent expiration.
Experience our video translation technology in action by exploring our interactive demo on GitHub: [AKool Video Translation Demo](https://github.com/AKOOL-Official/akool-video-translation-demo).
### Get Language List Result
```
GET https://openapi.akool.com/api/open/v3/language/list
```
**Request Headers**
| **Parameter** | **Value** | **Description** |
| ------------- | ---------------- | --------------------------------------------------------------------------------------------- |
| Authorization | Bearer `{token}` | Your API Key used for request authorization. [Get Token](/authentication/usage#get-the-token) |
**Response Attributes**
| **Parameter** | **Type** | **Value** | **Description** |
| ------------- | -------- | -------------------------------------------------------------- | ---------------------------------------------------- |
| code | int | 1000 | Interface returns business status code(1000:success) |
| msg | String | OK | Interface returns status information |
| data | Array | `{ lang_list:[ {"lang_code":"en", "lang_name": "English" } ]}` | lang\_code: Lang code supported by video translation |
**Example**
**Request**
```bash cURL
curl --location 'https://openapi.akool.com/api/open/v3/language/list' \
--header 'Authorization: Bearer {{Authorization}}'
```
```java Java
OkHttpClient client = new OkHttpClient().newBuilder()
.build();
MediaType mediaType = MediaType.parse("text/plain");
RequestBody body = RequestBody.create(mediaType, "");
Request request = new Request.Builder()
.url("https://openapi.akool.com/api/open/v3/language/list")
.method("GET", body)
.addHeader("Authorization", "Bearer {{Authorization}}")
.build();
Response response = client.newCall(request).execute();
```
```js Javascript
const myHeaders = new Headers();
myHeaders.append("Authorization", "Bearer {{Authorization}}");
const requestOptions = {
method: "GET",
headers: myHeaders,
redirect: "follow",
};
fetch("https://openapi.akool.com/api/open/v3/language/list", requestOptions)
.then((response) => response.text())
.then((result) => console.log(result))
.catch((error) => console.error(error));
```
```php PHP
'{{Authorization}}'
];
$request = new Request('GET', 'https://openapi.akool.com/api/open/v3/language/list', $headers);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();
```
```python Python
import requests
url = "https://openapi.akool.com/api/open/v3/language/list"
payload = {}
headers = {
'Authorization': 'Bearer {{Authorization}}'
}
response = requests.request("GET", url, headers=headers, data=payload)
print(response.text)
```
**Response**
```json
{
"code": 1000,
"msg": "OK",
"data": {
"lang_list": [
{
"lang_code": "en",
"lang_name": "English",
"url": "https://d11fbe263bhqij.cloudfront.net/agicontent/video/icons/En.png"
},
{
"lang_code": "fr",
"lang_name": "French",
"url": "https://d11fbe263bhqij.cloudfront.net/agicontent/video/icons/Fr.png"
},
{
"lang_code": "zh",
"lang_name": "Chinese (Simplified)",
"url": "https://d11fbe263bhqij.cloudfront.net/agicontent/video/icons/Zh.png"
}
]
}
```
### Create video translation
```
POST https://openapi.akool.com/api/open/v3/content/video/createbytranslate
```
**Request Headers**
| **Parameter** | **Value** | **Description** |
| ------------------- | ---------------- | --------------------------------------------------------------------------------------------- |
| Authorization | Bearer `{token}` | Your API Key used for request authorization. [Get Token](/authentication/usage#get-the-token) |
| **Body Attributes** | | |
| **Parameter** | **Type** | **Value** | **Description** |
| ------------------- | -------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------ |
| url | String | | The video url address you want to translate. |
| source\_language | String | | The original language of the video. |
| language | String | | The language you want to translate into. |
| lipsync | Boolean | true/false | Get synchronized mouth movements with the audio track in a translated video. |
| ~~merge\_interval~~ | Number | 1 | The segmentation interval of video translation, the default is 1 second. ***This field is deprecated*** |
| ~~face\_enhance~~ | Boolean | true/false | Whether to facial process the translated video, this parameter only works when lipsync is true. ***This field is deprecated*** |
| webhookUrl | String | | Callback url address based on HTTP request. |
| speaker\_num | Number | 0 | Number of speakers in the video, the default is 0 (Auto Detect). |
**Response Attributes**
| **Parameter** | **Type** | **Value** | **Description** |
| ------------- | -------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| code | int | 1000 | Interface returns business status code(1000:success) |
| msg | String | | Interface returns status information |
| data | Object | `{ "_id": "", "video_status": 1, "video": "" }` | `id`: Interface returns data, video\_status: the status of video： \[1:queueing, 2:processing, 3:completed, 4:failed], video: the url of Generated video |
**Example**
**Body**
```json
{
"url": "https://drz0f01yeq1cx.cloudfront.net/1710470596011-facebook.mp4", // The video address you want to translate
"language": "hi", // The language you want to translate into
"source_language": "zh", // The original language of the video.
"lipsync": true, // Get synchronized mouth movements with the audio track in a translated video.
//"merge_interval": 1, // This field is deprecated
//"face_enhance": true, // Whether to facial process the translated video, this parameter only works when lipsync is true. This field is deprecated
"webhookUrl": "", // Callback url address based on HTTP request
"speaker_num": 1
}
```
**Request**
```bash cURL
curl --location 'https://openapi.akool.com/api/open/v3/content/video/createbytranslate' \
--header 'Authorization: Bearer token' \
--header 'Content-Type: application/json' \
--data '{
"url": "https://drz0f01yeq1cx.cloudfront.net/1710470596011-facebook.mp4",
"source_language": "zh",
"language": "hi",
"lipsync":true,
"speaker_num": 1,
"webhookUrl":""
}'
```
```java Java
OkHttpClient client = new OkHttpClient().newBuilder()
.build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n \"url\": \"https://drz0f01yeq1cx.cloudfront.net/1710470596011-facebook.mp4\", \n \"language\": \"hi\", \n \"source_language\": \"zh\", \n \"lipsync\":true, \n \"speaker_num\":1, \n \"webhookUrl\":\"\" \n}");
Request request = new Request.Builder()
.url("https://openapi.akool.com/api/open/v3/content/video/createbytranslate")
.method("POST", body)
.addHeader("Authorization", "Bearer token")
.addHeader("Content-Type", "application/json")
.build();
Response response = client.newCall(request).execute();
```
```js Javascript
const myHeaders = new Headers();
myHeaders.append("Authorization", "Bearer token");
myHeaders.append("Content-Type", "application/json");
const raw = JSON.stringify({
url: "https://drz0f01yeq1cx.cloudfront.net/1710470596011-facebook.mp4",
language: "hi",
source_language: "zh",
lipsync: true,
webhookUrl: "",
speaker_num: 1,
});
const requestOptions = {
method: "POST",
headers: myHeaders,
body: raw,
redirect: "follow",
};
fetch(
"https://openapi.akool.com/api/open/v3/content/video/createbytranslate",
requestOptions
)
.then((response) => response.text())
.then((result) => console.log(result))
.catch((error) => console.error(error));
```
```php PHP
'Bearer token',
'Content-Type' => 'application/json'
];
$body = '{
"url": "https://drz0f01yeq1cx.cloudfront.net/1710470596011-facebook.mp4",
"language": "hi",
"source_language": "zh",
"lipsync": true,
"speaker_num": 1,
"webhookUrl": ""
}';
$request = new Request('POST', 'https://openapi.akool.com/api/open/v3/content/video/createbytranslate', $headers, $body);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();
```
```python Python
import requests
import json
url = "https://openapi.akool.com/api/open/v3/content/video/createbytranslate"
payload = json.dumps({
"url": "https://drz0f01yeq1cx.cloudfront.net/1710470596011-facebook.mp4",
"language": "hi",
"source_language": "zh",
"lipsync": true,
"speaker_num": 1,
"webhookUrl": ""
})
headers = {
'Authorization': 'Bearer token',
'Content-Type': 'application/json'
}
response = requests.request("POST", url, headers=headers, data=payload)
print(response.text)
```
**Response**
```json
{
"code": 1000,
"msg": "OK",
"data": {
"_id": "68ccee42e267570255824ab5",
"create_time": 1758260802773,
"uid": 101400,
"team_id": "6805fb69e92d9edc7ca0b409",
"target_video": "https://d11fbe263bhqij.cloudfront.net/agicontent/video/translate/cut3_content_create_EN_01.mp4",
"language": "zh",
"source_language": "en",
"video_id": "68ccee42f392598dae31999b",
"video_status": 1, // current status of video： 【1：queueing（The requested operation is being processed），2：processing（The requested operation is being processing），3：completed（The request operation has been processed successfully），4：failed（The request operation processing failed, the reason for the failure can be viewed in the video translation details.）】
"video_lock_duration": 16.44,
"deduction_lock_duration": 4,
"video": "",
"credentialId": "6823024be0c8e98471611c72",
"task_id": "68ccee42f392598dae31999b",
"target_video_md5": "md5_1758260802301",
"lipsync": false,
"lipSyncType": 0,
"speaker_num": 1,
"webhookUrl": ""
}
}
```
### Get Video Info Result
```
GET https://openapi.akool.com/api/open/v3/content/video/infobymodelid?video_model_id=64dd838cf0b6684651e90217
```
**Request Headers**
| **Parameter** | **Value** | **Description** |
| ------------- | ---------------- | -------------------------------------------------------------------------------------------- |
| Authorization | Bearer `{token}` | Your API Key used for request authorization.[Get Token](/authentication/usage#get-the-token) |
**Query Attributes**
| **Parameter** | **Type** | **Value** | **Description** |
| ---------------- | -------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| video\_model\_id | String | NULL | video db id: You can get it based on the `_id` field returned by [Create By Translate API](/ai-tools-suite/video-translation#create-video-translation) . |
**Response Attributes**
| **Parameter** | **Type** | **Value** | **Description** |
| ------------- | -------- | -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| code | int | 1000 | Interface returns business status code(1000:success) |
| msg | String | OK | Interface returns status information |
| data | Object | `{ video_status:1, _id:"", video:"" }` | video\_status: the status of video：【1:queueing, 2:processing, 3:completed, 4:failed】 video: Generated video resource url \_id: Interface returns data |
**Example**
**Request**
```bash cURL
curl --location 'http://openapi.akool.com/api/open/v3/content/video/infobymodelid?video_model_id=64b126c4a680e8edea44f02b' \
--header 'Authorization: Bearer token'
```
```java Java
OkHttpClient client = new OkHttpClient().newBuilder()
.build();
MediaType mediaType = MediaType.parse("text/plain");
RequestBody body = RequestBody.create(mediaType, "");
Request request = new Request.Builder()
.url("http://openapi.akool.com/api/open/v3/content/video/infobymodelid?video_model_id=64b126c4a680e8edea44f02b")
.method("GET", body)
.addHeader("Authorization", "Bearer token")
.build();
Response response = client.newCall(request).execute();
```
```js Javascript
const myHeaders = new Headers();
myHeaders.append("Authorization", "Bearer token");
const requestOptions = {
method: "GET",
headers: myHeaders,
redirect: "follow",
};
fetch(
"http://openapi.akool.com/api/open/v3/content/video/infobymodelid?video_model_id=64b126c4a680e8edea44f02b",
requestOptions
)
.then((response) => response.text())
.then((result) => console.log(result))
.catch((error) => console.error(error));
```
```php PHP
'Bearer token'
];
$request = new Request('GET', 'http://openapi.akool.com/api/open/v3/content/video/infobymodelid?video_model_id=64b126c4a680e8edea44f02b', $headers);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();
```
```python Python
import requests
url = "http://openapi.akool.com/api/open/v3/content/video/infobymodelid?video_model_id=64b126c4a680e8edea44f02b"
payload = {}
headers = {
'Authorization': 'Bearer token'
}
response = requests.request("GET", url, headers=headers, data=payload)
print(response.text)
```
**Response**
```json
{
"code": 1000,
"msg": "OK",
"data": {
"faceswap_quality": 2,
"storage_loc": 1,
"_id": "64dd92c1f0b6684651e90e09",
"create_time": 1692242625334,
"uid": 378337,
"type": 2,
"from": 1,
"video_id": "0acfed62e24f4cfd8801c9e846347b1d",
"video_lock_duration": 7.91,
"deduction_lock_duration": 10,
"video_status": 2, // current status of video： 【1：queueing（The requested operation is being processed），2：processing（The requested operation is being processing），3：completed（The request operation has been processed successfully），4：failed（The request operation processing failed, the reason for the failure can be viewed in the video translation details.）】
"external_video": "",
"lipsync_video_url": "", //if you set lipsync = true, you can use lipsync_video_url
"video": "" // Generated video resource url
}
}
```
**Response Code Description**
{" "}
Please note that if the value of the response code is not equal to 1000, the request
is failed or wrong
| **Parameter** | **Value** | **Description** |
| ------------- | --------- | ---------------------------------------------------------------------------------- |
| code | 1000 | Success |
| code | 1003 | Parameter error or Parameter can not be empty |
| code | 1008 | The content you get does not exist |
| code | 1009 | You do not have permission to operate |
| code | 1101 | Invalid authorization or The request token has expired |
| code | 1102 | Authorization cannot be empty |
| code | 1200 | The account has been banned |
| code | 1201 | create audio error, please try again later |
| code | 1202 | The same video cannot be translated lipSync in the same language more than 1 times |
| code | 1203 | video should be with audio |
| code | 1204 | Your video duration is exceed 60s! |
| code | 1205 | Create video error, please try again later |
| code | 1207 | The video you are using exceeds the size limit allowed by the system by 300M |
| code | 1209 | Please upload a video in another encoding format |
| code | 1210 | The video you are using exceeds the value allowed by the system by 30fp |
# VoiceLab
Source: https://docstest.akool.io/ai-tools-suite/voiceLab
VoiceLab API documentation
You can use the following APIs to create voice clones, text-to-speech, voice changer, and manage voice resources.
The resources (image, video, voice) generated by our API are valid for 7 days. Please save the relevant resources as soon as possible to prevent expiration.
## Rates
| **Plan** | **Pro** | **Max** | **Business** | **Enterprise** |
| ------------------- | --------------------------- | --------------------------- | --------------------------- | -------------- |
| Text-to-Speech | 4.4 credits/1000 characters | 3.2 credits/1000 characters | 2.4 credits/1000 characters | Customized |
| Instant voice clone | 30 voices | 180 voices | 500 voices | Customized |
| Voice changer | 4.4 credits/minute | 3.2 credits/minute | 2.4 credits/minute | Customized |
## Models
Voice Model Overview:
The following multilingual voice models are available for text-to-speech synthesis, each with strong performance across different language families.
| Model Name |
Description |
| Akool Multilingual 1 |
Performs well on English, Spanish, French, German, Italian, European Portuguese, Dutch, Russian, and other Western languages |
| Akool Multilingual 2 |
Excels at text-to-speech across various languages, but does not support voice cloning. |
| Akool Multilingual 3 |
Performs well on Chinese (Mandarin), Chinese (Cantonese ), Japanese, Korean, as well as English, Spanish, French, and other major Western languages |
| Akool Multilingual 4 |
Performs well on Portuguese (Brazil). |
## Create Voice Clone
```
POST https://openapi.akool.com/api/open/v4/voice/clone
```
**Request Headers**
| **Parameter** | **Value** | **Description** |
| ------------- | ---------------- | ------------------------------------------------------------------------------------------- |
| Authorization | Bearer `{token}` | Your API Key used for request authorization.[getToken](/authentication/usage#get-the-token) |
**Body Attributes**
| **Parameter** | **Type** | **Required** | **Value** | **Description** |
| ----------------------------- | -------- | ------------ | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| source\_voice\_file | String | true | | Original audio file URL, supports mp3, mp4, wav, etc. Must be a public accessible URL, The maximum file size is 30MB. |
| voice\_options | Object | false | | Audio tagging options |
| - style | Array | false | | Voice style tags (e.g., \["Authoritative", "Calm"]) |
| - gender | Array | false | | Gender tags (e.g., \["Male", "Female"]) |
| - age | Array | false | | Age tags (e.g., \["Young", "Middle", "Elderly"]) |
| - scenario | Array | false | | Use case tags (e.g., \["Advertisement", "Education"]) |
| - remove\_background\_noise | Boolean | false | false | Remove background noise, disabled by default |
| - language | String | false | en | Language code (ISO 639-1) of the audio file. Defaults to "en" if not specified |
| - clone\_prompt | String | false | | Must match the audio content exactly, including punctuation, to enhance clone quality. Sound reproduction example audio. Providing this parameter will help enhance the similarity and stability of the voice synthesis's sound quality. If using this parameter, a small sample audio segment must also be uploaded. The audio file uploaded must comply with the following specifications: The format of the uploaded audio file should be: mp3 or wav format; The duration of the uploaded audio file should be less than 8 seconds; The size of the uploaded audio file should not exceed 20 MB; |
| - need\_volume\_normalization | Boolean | false | false | Audio cloning parameter: Enable volume normalization, defaults to false |
| name | String | false | | Audio name |
| webhookUrl | String | false | | Callback url address based on HTTP request |
| voice\_model\_name | String | false | | The designated model for Clone, Supported voice models: Akool Multilingual 1, Akool Multilingual 3, Akool Multilingual 4. [getVoiceModelName](https://docs.akool.com/ai-tools-suite/voiceLab#get-voice-list) |
**Response Attributes**
| **Parameter** | **Type** | **Value** | **Description** |
| --------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| - code | Integer | 1000
| API returns status code(1000:success) |
| - msg | String | | API returns status message |
| - data | Object | | Response data object |
| - uid | Integer | 101400
| User ID |
| - team\_id | String | "6805fb69e92d9edc7ca0b409"
| Team ID |
| - voice\_id | String | null
| Voice ID, This voice\_id can be obtained from your cloned voices or the Akool voice list. Use the [getVoiceList](https://docs.akool.com/ai-tools-suite/voiceLab#get-voice-list) function to retrieve it |
| - gender | String | "Male"
| Voice gender |
| - name | String | "MyVoice0626-01"
| Voice name |
| - preview | String | null
| Preview audio URL, this value will be updated after task completion, you can view it in the voiceList.[getVoiceList](https://docs.akool.com/ai-tools-suite/voiceLab#get-voice-list) |
| - text | String | "This is a comic style model..."
| Preview text content |
| - duration | Number | 8064
| Audio duration in milliseconds |
| - status | Integer | 1
| Voice clone status: 【1:queueing, 2:processing, 3:completed, 4:failed】 |
| - create\_time | Long | 1751349718268
| Creation timestamp |
| - style | Array | \["Authoritative", "Calm"]
| Voice style tags |
| - scenario | Array | \["Advertisenment"]
| Use case scenario tags |
| - age | Array | \["Elderly", "Middle"]
| Age category tags |
| - deduction\_credit | Integer | 0
| Deducted credits |
| - webhookUrl | String | "Callback URL"
| Callback URL |
| - \_id | String | "686379d641e5eb74bb8dfe3f"
| Document ID |
| - source\_voice\_file | String | "[https://drz0f01yeq1cx.cloudfront.net/1751363983518-9431-audio1751363981879.webm](https://drz0f01yeq1cx.cloudfront.net/1751363983518-9431-audio1751363981879.webm)" | Original audio file URL |
### Example
**Body**
```json
{
"source_voice_file": "https://drz0f01yeq1cx.cloudfront.net/1755534706613-000a30e917d848d9bd166b636530ae21-38a696952ca94b9eb9ecf07ced494a58.mp3",
"name": "My Voice",
"voice_options": {
"remove_background_noise": true,
"style": ["Authoritative","Calm","Confident","Enthusiastic"],
"gender": ["Male"],
"age": ["Elderly"],
"scenario": ["Advertisenment"],
"language": "en",
"clone_prompt": "暮春时节，牡丹园内千层叠瓣的姚黄魏紫次第苏醒。晨露未晞时，花瓣边缘凝着水晶般的珠光，内里丝绸质地的绛红由浅及深晕染开来，如同将晚霞裁作衣裳。风过处，花浪翻涌，金蕊颤动间暗香浮动，引得蜂蝶在花心盘旋出金色的漩涡。最是那株绿牡丹，初绽时青玉雕琢似的瓣尖泛着月白，待全盛时竟如翡翠盏中盛着冰酿，教人疑心是王母瑶池遗落的仙品。偶有花瓣飘落，便成了绣毯上滚动的玛瑙珠，连泥土都浸染了雍容的芬芳。这般倾国之色，难怪刘禹锡咏道唯有牡丹真国色，花开时节动京城——它用整季的绚烂，诠释了何为花中魁首的盛大气象。",
"need_volume_normalization": true
},
"voice_model_name": "Akool Multilingual 3",
"webhookUrl": ""
}
```
**Request**
```bash cURL
curl --location 'https://openapi.akool.com/api/open/v4/voice/clone' \
--header 'Authorization: Bearer {{token}}' \
--header 'Content-Type: application/json' \
--data '{
"source_voice_file": "https://drz0f01yeq1cx.cloudfront.net/1755534706613-000a30e917d848d9bd166b636530ae21-38a696952ca94b9eb9ecf07ced494a58.mp3",
"name": "My Voice",
"voice_options": {
"remove_background_noise": true,
"style": ["Authoritative","Calm","Confident","Enthusiastic"],
"gender": ["Male"],
"age": ["Elderly"],
"scenario": ["Advertisenment"],
"language": "en",
"clone_prompt": "暮春时节，牡丹园内千层叠瓣的姚黄魏紫次第苏醒。晨露未晞时，花瓣边缘凝着水晶般的珠光，内里丝绸质地的绛红由浅及深晕染开来，如同将晚霞裁作衣裳。风过处，花浪翻涌，金蕊颤动间暗香浮动，引得蜂蝶在花心盘旋出金色的漩涡。最是那株绿牡丹，初绽时青玉雕琢似的瓣尖泛着月白，待全盛时竟如翡翠盏中盛着冰酿，教人疑心是王母瑶池遗落的仙品。偶有花瓣飘落，便成了绣毯上滚动的玛瑙珠，连泥土都浸染了雍容的芬芳。这般倾国之色，难怪刘禹锡咏道唯有牡丹真国色，花开时节动京城——它用整季的绚烂，诠释了何为花中魁首的盛大气象。",
"need_volume_normalization": true
},
"voice_model_name": "Akool Multilingual 3",
"webhookUrl": ""
}'
```
```java Java
OkHttpClient client = new OkHttpClient().newBuilder()
.build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n \"source_voice_file\": \"https://drz0f01yeq1cx.cloudfront.net/1755534706613-000a30e917d848d9bd166b636530ae21-38a696952ca94b9eb9ecf07ced494a58.mp3\",\n \"name\": \"Specify Voice Model\",\n \"voice_options\": {\n \"remove_background_noise\": true,\n \"style\": [\"Authoritative\",\"Calm\",\"Confident\",\"Enthusiastic\"],\n \"gender\": [\"Male\"],\n \"age\": [\"Elderly\"],\n \"scenario\": [\"Advertisenment\"],\n \"language\": \"en\",\n \"clone_prompt\": \"暮春时节，牡丹园内千层叠瓣的姚黄魏紫次第苏醒。晨露未晞时，花瓣边缘凝着水晶般的珠光，内里丝绸质地的绛红由浅及深晕染开来，如同将晚霞裁作衣裳。风过处，花浪翻涌，金蕊颤动间暗香浮动，引得蜂蝶在花心盘旋出金色的漩涡。最是那株绿牡丹，初绽时青玉雕琢似的瓣尖泛着月白，待全盛时竟如翡翠盏中盛着冰酿，教人疑心是王母瑶池遗落的仙品。偶有花瓣飘落，便成了绣毯上滚动的玛瑙珠，连泥土都浸染了雍容的芬芳。这般倾国之色，难怪刘禹锡咏道唯有牡丹真国色，花开时节动京城——它用整季的绚烂，诠释了何为花中魁首的盛大气象。\",\n \"need_volume_normalization\": true\n },\n \"voice_model_name\": \"Akool Multilingual 3\"\n,\n \"webhookUrl\": \"\"\n}");
Request request = new Request.Builder()
.url("https://openapi.akool.com/api/open/v4/voice/clone")
.method("POST", body)
.addHeader("Authorization", "Bearer {{token}}")
.addHeader("Content-Type", "application/json")
.build();
Response response = client.newCall(request).execute();
```
```js Javascript
const myHeaders = new Headers();
myHeaders.append("Authorization", "Bearer {{token}}");
myHeaders.append("Content-Type", "application/json");
const raw = JSON.stringify({
"source_voice_file": "https://drz0f01yeq1cx.cloudfront.net/1755534706613-000a30e917d848d9bd166b636530ae21-38a696952ca94b9eb9ecf07ced494a58.mp3",
"name": "Specify Voice Model",
"voice_options": {
"remove_background_noise": true,
"style": ["Authoritative","Calm","Confident","Enthusiastic"],
"gender": ["Male"],
"age": ["Elderly"],
"scenario": ["Advertisenment"],
"language": "en",
"clone_prompt": "暮春时节，牡丹园内千层叠瓣的姚黄魏紫次第苏醒。晨露未晞时，花瓣边缘凝着水晶般的珠光，内里丝绸质地的绛红由浅及深晕染开来，如同将晚霞裁作衣裳。风过处，花浪翻涌，金蕊颤动间暗香浮动，引得蜂蝶在花心盘旋出金色的漩涡。最是那株绿牡丹，初绽时青玉雕琢似的瓣尖泛着月白，待全盛时竟如翡翠盏中盛着冰酿，教人疑心是王母瑶池遗落的仙品。偶有花瓣飘落，便成了绣毯上滚动的玛瑙珠，连泥土都浸染了雍容的芬芳。这般倾国之色，难怪刘禹锡咏道唯有牡丹真国色，花开时节动京城——它用整季的绚烂，诠释了何为花中魁首的盛大气象。",
"need_volume_normalization": true
},
"voice_model_name": "Akool Multilingual 3",
"webhookUrl": "",
});
const requestOptions = {
method: "POST",
headers: myHeaders,
body: raw,
redirect: "follow"
};
fetch("https://openapi.akool.com/api/open/v4/voice/clone", requestOptions)
.then((response) => response.text())
.then((result) => console.log(result))
.catch((error) => console.error(error));
```
```php PHP
'Bearer {{token}}',
'Content-Type' => 'application/json'
];
$body = '{
"source_voice_file": "https://drz0f01yeq1cx.cloudfront.net/1755534706613-000a30e917d848d9bd166b636530ae21-38a696952ca94b9eb9ecf07ced494a58.mp3",
"name": "Specify Voice Model",
"voice_options": {
"remove_background_noise": true,
"style": ["Authoritative","Calm","Confident","Enthusiastic"],
"gender": ["Male"],
"age": ["Elderly"],
"scenario": ["Advertisenment"],
"language": "en",
"clone_prompt": "暮春时节，牡丹园内千层叠瓣的姚黄魏紫次第苏醒。晨露未晞时，花瓣边缘凝着水晶般的珠光，内里丝绸质地的绛红由浅及深晕染开来，如同将晚霞裁作衣裳。风过处，花浪翻涌，金蕊颤动间暗香浮动，引得蜂蝶在花心盘旋出金色的漩涡。最是那株绿牡丹，初绽时青玉雕琢似的瓣尖泛着月白，待全盛时竟如翡翠盏中盛着冰酿，教人疑心是王母瑶池遗落的仙品。偶有花瓣飘落，便成了绣毯上滚动的玛瑙珠，连泥土都浸染了雍容的芬芳。这般倾国之色，难怪刘禹锡咏道唯有牡丹真国色，花开时节动京城——它用整季的绚烂，诠释了何为花中魁首的盛大气象。",
"need_volume_normalization": true,
"webhookUrl": "",
},
"voice_model_name": "Akool Multilingual 3"
}';
$request = new Request('POST', 'https://openapi.akool.com/api/open/v4/voice/clone', $headers, $body);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();
?>
```
```python Python
import requests
import json
url = "https://openapi.akool.com/api/open/v4/voice/clone"
payload = json.dumps({
"source_voice_file": "https://drz0f01yeq1cx.cloudfront.net/1755534706613-000a30e917d848d9bd166b636530ae21-38a696952ca94b9eb9ecf07ced494a58.mp3",
"name": "Specify Voice",
"voice_options": {
"remove_background_noise": true,
"style": ["Authoritative","Calm","Confident","Enthusiastic"],
"gender": ["Male"],
"age": ["Elderly"],
"scenario": ["Advertisenment"],
"language": "en",
"clone_prompt": "暮春时节，牡丹园内千层叠瓣的姚黄魏紫次第苏醒。晨露未晞时，花瓣边缘凝着水晶般的珠光，内里丝绸质地的绛红由浅及深晕染开来，如同将晚霞裁作衣裳。风过处，花浪翻涌，金蕊颤动间暗香浮动，引得蜂蝶在花心盘旋出金色的漩涡。最是那株绿牡丹，初绽时青玉雕琢似的瓣尖泛着月白，待全盛时竟如翡翠盏中盛着冰酿，教人疑心是王母瑶池遗落的仙品。偶有花瓣飘落，便成了绣毯上滚动的玛瑙珠，连泥土都浸染了雍容的芬芳。这般倾国之色，难怪刘禹锡咏道唯有牡丹真国色，花开时节动京城——它用整季的绚烂，诠释了何为花中魁首的盛大气象。",
"need_volume_normalization": true
},
"voice_model_name": "Akool Multilingual 3",
"webhookUrl": "",
})
headers = {
'Authorization': 'Bearer {{token}}',
'Content-Type': 'application/json'
}
response = requests.request("POST", url, headers=headers, data=payload)
print(response.text)
```
**Response**
```json
{
"code": 1000,
"msg": "OK",
"data": {
"uid": 101400,
"team_id": "6805fb69e92d9edc7ca0b409",
"voice_id": null,
"gender": "Male",
"name": "MyVoice0626-01",
"preview": null,
"text": "This is a comic style model, this is a comic style model, this is a comic style model, this is a comic style model",
"duration": 8064,
"status": 1,
"create_time": 1751349718268,
"style": [
"Authoritative",
"Calm"
],
"scenario": [
"Advertisenment"
],
"age": [
"Elderly",
"Middle"
],
"deduction_credit": 0,
"webhookUrl": "",
"source_voice_file": "https://drz0f01yeq1cx.cloudfront.net/1751363983518-9431-audio1751363981879.webm",
"_id": "686379d641e5eb74bb8dfe3f"
}
}
```
## Create Text to Speech
```
POST https://openapi.akool.com/api/open/v4/voice/tts
```
**Request Headers**
| **Parameter** | **Value** | **Description** |
| ------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------- |
| Authorization | Bearer `{token}` | Your API Key used for request authorization.[getToken](https://docs.akool.com/authentication/usage#get-the-token) |
**Body Attributes**
| **Parameter** | **Type** | **Required** | **Value** | **Description** |
| -------------------------------------- | -------- | ----------------------------------------- | --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| input\_text | String | true | | For input text, the per-request character limit depends on the subscription plan: Pro – 5,000, Pro Max – 10,000, Business – 50,000. |
| voice\_id | String | true | | Voice ID, Voice synthesis ID. If both timber\_weights and voice\_id fields have values, timber\_weights will not take effect.get this voice\_id from your cloned voices or akool voice list.[getVoiceId](https://docs.akool.com/ai-tools-suite/voiceLab#get-voice-list) |
| voice\_options | Object | false | | Audio settings |
| - stability | Number | false | | Voice stability (0-1) , Supported voice models: Akool Multilingual 1, [getVoiceModelName](https://docs.akool.com/ai-tools-suite/voiceLab#get-voice-list) |
| - similarity\_boost | Number | false | | Similarity boost (0-1) , Supported voice models: Akool Multilingual 1, [getVoiceModelName](https://docs.akool.com/ai-tools-suite/voiceLab#get-voice-list) |
| - style | Number | false | | Voice style (0-1) , Supported voice models: Akool Multilingual 1, Akool Multilingual 2. Style examples: cheerful, [getVoiceModelName](https://docs.akool.com/ai-tools-suite/voiceLab#get-voice-list) |
| - speed | Number | false | | Speech speed (0.7-1.2) , Supported voice models: Akool Multilingual 1, Akool Multilingual 2, Akool Multilingual 3, [getVoiceModelName](https://docs.akool.com/ai-tools-suite/voiceLab#get-voice-list) |
| - speaker\_boost | Boolean | false | | Speaker boost, Supported voice models: Akool Multilingual 1, [getVoiceModelName](https://docs.akool.com/ai-tools-suite/voiceLab#get-voice-list) |
| - emotion | String | false | | Emotion (happy, sad, angry, fearful, disgusted, surprised, neutral) , It only supports Chinese voice. Supported voice models: Akool Multilingual 2, Akool Multilingual 3, [getVoiceModelName](https://docs.akool.com/ai-tools-suite/voiceLab#get-voice-list) |
| - volume | Integer | false | | Volume (0-100) , Supported voice models: Akool Multilingual 2, Akool Multilingual 3, [getVoiceModelName](https://docs.akool.com/ai-tools-suite/voiceLab#get-voice-list) |
| webhookUrl | String | false | | Callback url address based on HTTP request |
| language\_code | String | false | | Currently supported: Akool Multilingual 1, Akool Multilingual 3 and Akool Multilingual 4. When passing in, only Language code (ISO 639-1) such as "zh", "pt" is supported. This parameter is designed to enhance the use of minority languages. Adding audio effects will make it better, but it cannot achieve the effect of translation. |
| extra\_options | Object | false | | Additional parameter settings |
| - previous\_text | String | false | | Supported voice models: Akool Multilingual 1, [getVoiceModelName](https://docs.akool.com/ai-tools-suite/voiceLab#get-voice-list). The text that came before the text of the current request. Can be used to improve the speech's continuity when concatenating together multiple generations or to influence the speech's continuity in the current generation. |
| - next\_text | String | false | | Supported voice models: Akool Multilingual 1, [getVoiceModelName](https://docs.akool.com/ai-tools-suite/voiceLab#get-voice-list). The text that comes after the text of the current request. Can be used to improve the speech's continuity when concatenating together multiple generations or to influence the speech's continuity in the current generation. |
| - apply\_text\_normalization | String | false | | Supported voice models: Akool Multilingual 1, [getVoiceModelName](https://docs.akool.com/ai-tools-suite/voiceLab#get-voice-list). This parameter controls text normalization with three modes: ‘auto’, ‘on’, and ‘off’. When set to ‘auto’, the system will automatically decide whether to apply text normalization (e.g., spelling out numbers). With ‘on’, text normalization will always be applied, while with ‘off’, it will be skipped. |
| - apply\_language\_text\_normalization | Boolean | false | false | Supported voice models: Akool Multilingual 1, [getVoiceModelName](https://docs.akool.com/ai-tools-suite/voiceLab#get-voice-list). This parameter controls language text normalization. This helps with proper pronunciation of text in some supported languages. WARNING: This parameter can heavily increase the latency of the request. Currently only supported for Japanese. |
| - latex\_read | Boolean | false | false | Supported voice models: Akool Multilingual 3, [getVoiceModelName](https://docs.akool.com/ai-tools-suite/voiceLab#get-voice-list). Controls whether to read LaTeX formulas, defaults to false. Note: 1. Formulas in the request must be enclosed with \$\$ 2. Backslashes () in formulas must be escaped as \\ |
| - text\_normalization | Boolean | false | false | Supported voice models: Akool Multilingual 3, [getVoiceModelName](https://docs.akool.com/ai-tools-suite/voiceLab#get-voice-list). This parameter supports Chinese and English text normalization, improving performance in number reading scenarios but slightly increasing latency. Defaults to false if not provided. |
| - audio\_setting | Object | false | | Supported voice models: Akool Multilingual 3, [getVoiceModelName](https://docs.akool.com/ai-tools-suite/voiceLab#get-voice-list). Audio generation parameter settings |
| -- sample\_rate | Integer | false | 32000 | Supported voice models: Akool Multilingual 3, [getVoiceModelName](https://docs.akool.com/ai-tools-suite/voiceLab#get-voice-list). Audio sampling rate. Available range \[8000, 16000, 22050, 24000, 32000, 44100], defaults to 32000 |
| -- bitrate | Integer | false | 128000 | Supported voice models: Akool Multilingual 3, [getVoiceModelName](https://docs.akool.com/ai-tools-suite/voiceLab#get-voice-list). Audio bitrate. Available range \[32000, 64000, 128000, 256000], defaults to 128000. This parameter only affects mp3 format audio |
| -- format | String | false | mp3 | Supported voice models: Akool Multilingual 3, [getVoiceModelName](https://docs.akool.com/ai-tools-suite/voiceLab#get-voice-list). Audio format. Available options \[mp3, wav], defaults to mp3. WAV format is only supported in non-streaming output |
| -- channel | Integer | false | 1 | Supported voice models: Akool Multilingual 3, [getVoiceModelName](https://docs.akool.com/ai-tools-suite/voiceLab#get-voice-list). Number of audio channels. Available options: \[1,2], where 1 is mono and 2 is stereo, defaults to 1 |
| - timber\_weights | Array | false | | Supported voice models: Akool Multilingual 3, [getVoiceModelName](https://docs.akool.com/ai-tools-suite/voiceLab#get-voice-list). List of mixed timbres, supporting up to 4 voice timbres. The higher the weight of a single timbre, the more similar the synthesized voice will be to that timbre. If both timber\_weights and voice\_id fields have values, timber\_weights will not take effect. |
| -- voice\_id | String | Required within timber\_weights parameter | | Supported voice models: Akool Multilingual 3, [getVoiceModelName](https://docs.akool.com/ai-tools-suite/voiceLab#get-voice-list). Voice timbre ID, must be filled in together with the weight parameter. Get this voice\_id from your cloned voices or akool voice list.[getVoiceId](https://docs.akool.com/ai-tools-suite/voiceLab#get-voice-list) |
| -- weight | Integer | Required within timber\_weights parameter | | Supported voice models: Akool Multilingual 3, [getVoiceModelName](https://docs.akool.com/ai-tools-suite/voiceLab#get-voice-list). Weight of each voice timbre, must be filled in together with voice\_id. Available range \[1, 100], the higher the weight, the more similar the synthesized voice will be to that timbre |
| - pronunciation\_dict | Object | false | | Supported voice models: Akool Multilingual 3, [getVoiceModelName](https://docs.akool.com/ai-tools-suite/voiceLab#get-voice-list). Pronunciation rules |
| -- tone | Array | false | \["燕少飞/(yan4)(shao3)(fei1)", "omg/oh my god"] | Supported voice models: Akool Multilingual 3, [getVoiceModelName](https://docs.akool.com/ai-tools-suite/voiceLab#get-voice-list). Define special pronunciation rules for characters or symbols. For Chinese text, tones are represented by numbers: 1 for first tone, 2 for second tone, 3 for third tone, 4 for fourth tone, 5 for neutral tone |
| - voice\_modify | Object | false | | Supported voice models: Akool Multilingual 3, [getVoiceModelName](https://docs.akool.com/ai-tools-suite/voiceLab#get-voice-list). Voice parameter adjustments |
| -- pitch | Integer | false | | Supported voice models: Akool Multilingual 3, [getVoiceModelName](https://docs.akool.com/ai-tools-suite/voiceLab#get-voice-list). Pitch adjustment (deep/bright), range \[-100,100]. Values closer to -100 make the voice deeper; closer to 100 make it brighter |
| -- intensity | Integer | false | | Supported voice models: Akool Multilingual 3, [getVoiceModelName](https://docs.akool.com/ai-tools-suite/voiceLab#get-voice-list). Intensity adjustment (powerful/soft), range \[-100,100]. Values closer to -100 make the voice more powerful; closer to 100 make it softer |
| -- timbre | Integer | false | | Timbre adjustment (resonant/crisp), range \[-100,100]. Values closer to -100 make the voice more resonant; closer to 100 make it crisper |
| -- sound\_effects | String | false | | Supported voice models: Akool Multilingual 3, [getVoiceModelName](https://docs.akool.com/ai-tools-suite/voiceLab#get-voice-list). Sound effects settings, only one can be selected at a time. Available options: spacious\_echo (spacious echo), auditorium\_echo (auditorium broadcast), lofi\_telephone (telephone distortion), robotic (electronic voice) |
| - subtitle\_enable | Boolean | false | | Supported voice models: Akool Multilingual 3, [getVoiceModelName](https://docs.akool.com/ai-tools-suite/voiceLab#get-voice-list). Controls whether to enable subtitle service, defaults to false. This parameter is only effective in non-streaming output scenarios |
| - pitch | Integer | false | | Supported voice models: Akool Multilingual 3, [getVoiceModelName](https://docs.akool.com/ai-tools-suite/voiceLab#get-voice-list). Voice pitch, range \[-12, 12], where 0 outputs the original timbre. Value must be an integer. |
**Response Attributes**
| **Parameter** | **Type** | **Value** | **Description** |
| ------------------- | -------- | ------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| - code | Integer | 1000
| API returns status code(1000:success) |
| - msg | String | | API returns status message |
| - data | Object | | Response data object |
| - create\_time | Long | 1751350015709
| Creation timestamp |
| - uid | Integer | 101400
| User ID |
| - team\_id | String | "6805fb69e92d9edc7ca0b409"
| Team ID |
| - input\_text | String | "Welcome to the Akool..."
| Input text content |
| - preview | String | null
| Generated audio URL, this value will be updated after task completion, you can view it in the resourceList. [getResourceList](https://docs.akool.com/ai-tools-suite/voiceLab#get-voice-results-list) |
| - status | Integer | 1
| TTS status: 【1:queueing, 2:processing, 3:completed, 4:failed】 |
| - webhookUrl | String | ""
| Callback URL |
| - duration | Integer | 0
| Audio duration in milliseconds |
| - file\_name | String | "1ef1d76ebfc244f7a30430f7049d6ebc.mp3"
| Generated file name |
| - gender | String | "Male"
| Voice gender |
| - deduction\_credit | Float | 1.9295
| Deducted credits |
| - name | String | "27fec311afd743aa889a057e17e93c13"
| Generated name |
| - \_id | String | "68637aff41e5eb74bb8dfe73"
| Document ID |
| - voice\_model\_id | String | "686379d641e5eb74bb8dfe3f"
| Voice document ID |
| - voice\_id | String | "Tq06jbVyFH4l6R-Gjvo\_V-p\_nVYk5DRrYJZsxeDmlhEtyhcFKKLQODmgngI9llKw"
| Voice ID |
| - voice\_options | Object | | Voice options object |
| - stability | Number | 0.7
| Voice stability setting |
| - similarity\_boost | Number | 0.5
| Similarity boost setting |
| - style | Number | 0.6
| Voice style setting |
| - speed | Number | 0.8
| Speech speed setting |
| - speaker\_boost | Boolean | false
| Speaker boost setting |
| - emotion | String | "happy"
| Emotion setting |
| - volume | Integer | 50
| Volume setting |
### Example
**Body**
```json
{
"input_text": "暮春时节，牡丹园内千层叠瓣的姚黄魏紫次第苏醒。晨露未晞时，花瓣边缘凝着水晶般的珠光，内里丝绸质地的绛红由浅及深晕染开来，如同将晚霞裁作衣裳。风过处，花浪翻涌，金蕊颤动间暗香浮动，引得蜂蝶在花心盘旋出金色的漩涡。最是那株绿牡丹，初绽时青玉雕琢似的瓣尖泛着月白，待全盛时竟如翡翠盏中盛着冰酿，教人疑心是王母瑶池遗落的仙品。偶有花瓣飘落，便成了绣毯上滚动的玛瑙珠，连泥土都浸染了雍容的芬芳。这般倾国之色，难怪刘禹锡咏道唯有牡丹真国色，花开时节动京城——它用整季的绚烂，诠释了何为花中魁首的盛大气象。",
"voice_id": "6889b628662160e2caad5dbc",
"voice_options": {
"stability": 0.6,
"similarity_boost": 0.8,
"style": 1,
"speed": 1.0,
"speaker_boost": true,
"emotion": "happy",
"volume": 80
},
"pitch": -5,
"webhookUrl": "",
"language_code": "zh",
"extra_options": {
"previous_text": "暮春时节，牡丹园内千层叠瓣的姚黄魏紫次第苏醒。晨露未晞时，花瓣边缘凝着水晶般的珠光，内里丝绸质地的绛红由浅及深晕染开来，如同将晚霞裁作衣裳。风过处，花浪翻涌，金蕊颤动间暗香浮动，引得蜂蝶在花心盘旋出金色的漩涡。最是那株绿牡丹，初绽时青玉雕琢似的瓣尖泛着月白，待全盛时竟如翡翠盏中盛着冰酿，教人疑心是王母瑶池遗落的仙品。偶有花瓣飘落，便成了绣毯上滚动的玛瑙珠，连泥土都浸染了雍容的芬芳。这般倾国之色，难怪刘禹锡咏道唯有牡丹真国色，花开时节动京城——它用整季的绚烂，诠释了何为花中魁首的盛大气象。",
"next_text": "暮春时节，牡丹园内千层叠瓣的姚黄魏紫次第苏醒。晨露未晞时，花瓣边缘凝着水晶般的珠光，内里丝绸质地的绛红由浅及深晕染开来，如同将晚霞裁作衣裳。风过处，花浪翻涌，金蕊颤动间暗香浮动，引得蜂蝶在花心盘旋出金色的漩涡。最是那株绿牡丹，初绽时青玉雕琢似的瓣尖泛着月白，待全盛时竟如翡翠盏中盛着冰酿，教人疑心是王母瑶池遗落的仙品。偶有花瓣飘落，便成了绣毯上滚动的玛瑙珠，连泥土都浸染了雍容的芬芳。这般倾国之色，难怪刘禹锡咏道唯有牡丹真国色，花开时节动京城——它用整季的绚烂，诠释了何为花中魁首的盛大气象。",
"apply_text_normalization": "auto",
"apply_language_text_normalization": true,
"latex_read": true,
"text_normalization": true,
"audio_setting": {
"sample_rate": 24000,
"bitrate": 32000,
"format": "mp3",
"channel": 2
},
"timber_weights": [
{
"voice_id": "6889b7f4662160e2caad60e9",
"weight": 80
},
{
"voice_id": "6889b7f3662160e2caad60e8",
"weight": 60
},
{
"voice_id": "6889b7f3662160e2caad60e7",
"weight": 30
},
{
"voice_id": "6889b7f2662160e2caad60e6",
"weight": 10
}
],
"pronunciation_dict": {
"tone" : [
"雍容/(yong3)(neng4)",
"牡丹/(mu4)(dan3)"
]
},
"voice_modify": {
"pitch": 50,
"intensity": 30,
"timbre": -50,
"sound_effects": "robotic"
},
"subtitle_enable": true
}
}
```
**Request**
```bash cURL
curl --location 'https://openapi.akool.com/api/open/v4/voice/tts' \
--header 'Authorization: Bearer {{token}}' \
--header 'Content-Type: application/json' \
--data '{
"input_text": "暮春时节，牡丹园内千层叠瓣的姚黄魏紫次第苏醒。晨露未晞时，花瓣边缘凝着水晶般的珠光，内里丝绸质地的绛红由浅及深晕染开来，如同将晚霞裁作衣裳。风过处，花浪翻涌，金蕊颤动间暗香浮动，引得蜂蝶在花心盘旋出金色的漩涡。最是那株绿牡丹，初绽时青玉雕琢似的瓣尖泛着月白，待全盛时竟如翡翠盏中盛着冰酿，教人疑心是王母瑶池遗落的仙品。偶有花瓣飘落，便成了绣毯上滚动的玛瑙珠，连泥土都浸染了雍容的芬芳。这般倾国之色，难怪刘禹锡咏道唯有牡丹真国色，花开时节动京城——它用整季的绚烂，诠释了何为花中魁首的盛大气象。",
"voice_id": "6889b628662160e2caad5dbc",
"voice_options": {
"stability": 0.6,
"similarity_boost": 0.8,
"style": 1,
"speed": 1.0,
"speaker_boost": true,
"emotion": "happy",
"volume": 80
},
"pitch": -5,
"webhookUrl": "",
"language_code": "zh",
"extra_options": {
"previous_text": "暮春时节，牡丹园内千层叠瓣的姚黄魏紫次第苏醒。晨露未晞时，花瓣边缘凝着水晶般的珠光，内里丝绸质地的绛红由浅及深晕染开来，如同将晚霞裁作衣裳。风过处，花浪翻涌，金蕊颤动间暗香浮动，引得蜂蝶在花心盘旋出金色的漩涡。最是那株绿牡丹，初绽时青玉雕琢似的瓣尖泛着月白，待全盛时竟如翡翠盏中盛着冰酿，教人疑心是王母瑶池遗落的仙品。偶有花瓣飘落，便成了绣毯上滚动的玛瑙珠，连泥土都浸染了雍容的芬芳。这般倾国之色，难怪刘禹锡咏道唯有牡丹真国色，花开时节动京城——它用整季的绚烂，诠释了何为花中魁首的盛大气象。",
"next_text": "暮春时节，牡丹园内千层叠瓣的姚黄魏紫次第苏醒。晨露未晞时，花瓣边缘凝着水晶般的珠光，内里丝绸质地的绛红由浅及深晕染开来，如同将晚霞裁作衣裳。风过处，花浪翻涌，金蕊颤动间暗香浮动，引得蜂蝶在花心盘旋出金色的漩涡。最是那株绿牡丹，初绽时青玉雕琢似的瓣尖泛着月白，待全盛时竟如翡翠盏中盛着冰酿，教人疑心是王母瑶池遗落的仙品。偶有花瓣飘落，便成了绣毯上滚动的玛瑙珠，连泥土都浸染了雍容的芬芳。这般倾国之色，难怪刘禹锡咏道唯有牡丹真国色，花开时节动京城——它用整季的绚烂，诠释了何为花中魁首的盛大气象。",
"apply_text_normalization": "auto",
"apply_language_text_normalization": true,
"latex_read": true,
"text_normalization": true,
"audio_setting": {
"sample_rate": 24000,
"bitrate": 32000,
"format": "mp3",
"channel": 2
},
"timber_weights": [
{
"voice_id": "6889b7f4662160e2caad60e9",
"weight": 80
},
{
"voice_id": "6889b7f3662160e2caad60e8",
"weight": 60
},
{
"voice_id": "6889b7f3662160e2caad60e7",
"weight": 30
},
{
"voice_id": "6889b7f2662160e2caad60e6",
"weight": 10
}
],
"pronunciation_dict": {
"tone" : [
"雍容/(yong3)(neng4)",
"牡丹/(mu4)(dan3)"
]
},
"voice_modify": {
"pitch": 50,
"intensity": 30,
"timbre": -50,
"sound_effects": "robotic"
},
"subtitle_enable": true
}
}'
```
```java Java
OkHttpClient client = new OkHttpClient().newBuilder()
.build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n \"input_text\": \"暮春时节，牡丹园内千层叠瓣的姚黄魏紫次第苏醒。晨露未晞时，花瓣边缘凝着水晶般的珠光，内里丝绸质地的绛红由浅及深晕染开来，如同将晚霞裁作衣裳。风过处，花浪翻涌，金蕊颤动间暗香浮动，引得蜂蝶在花心盘旋出金色的漩涡。最是那株绿牡丹，初绽时青玉雕琢似的瓣尖泛着月白，待全盛时竟如翡翠盏中盛着冰酿，教人疑心是王母瑶池遗落的仙品。偶有花瓣飘落，便成了绣毯上滚动的玛瑙珠，连泥土都浸染了雍容的芬芳。这般倾国之色，难怪刘禹锡咏道唯有牡丹真国色，花开时节动京城——它用整季的绚烂，诠释了何为花中魁首的盛大气象。\",\n \"voice_id\": \"6889b628662160e2caad5dbc\",\n \"voice_options\": {\n \"stability\": 0.6,\n \"similarity_boost\": 0.8,\n \"style\": 1,\n \"speed\": 1.0,\n \"speaker_boost\": true,\n \"emotion\": \"happy\",\n \"volume\": 80\n },\n \"pitch\": -5,\n \"webhookUrl\": \"\",\n \"language_code\": \"zh\",\n \"extra_options\": {\n \"previous_text\": \"暮春时节，牡丹园内千层叠瓣的姚黄魏紫次第苏醒。晨露未晞时，花瓣边缘凝着水晶般的珠光，内里丝绸质地的绛红由浅及深晕染开来，如同将晚霞裁作衣裳。风过处，花浪翻涌，金蕊颤动间暗香浮动，引得蜂蝶在花心盘旋出金色的漩涡。最是那株绿牡丹，初绽时青玉雕琢似的瓣尖泛着月白，待全盛时竟如翡翠盏中盛着冰酿，教人疑心是王母瑶池遗落的仙品。偶有花瓣飘落，便成了绣毯上滚动的玛瑙珠，连泥土都浸染了雍容的芬芳。这般倾国之色，难怪刘禹锡咏道唯有牡丹真国色，花开时节动京城——它用整季的绚烂，诠释了何为花中魁首的盛大气象。\",\n \"next_text\": \"暮春时节，牡丹园内千层叠瓣的姚黄魏紫次第苏醒。晨露未晞时，花瓣边缘凝着水晶般的珠光，内里丝绸质地的绛红由浅及深晕染开来，如同将晚霞裁作衣裳。风过处，花浪翻涌，金蕊颤动间暗香浮动，引得蜂蝶在花心盘旋出金色的漩涡。最是那株绿牡丹，初绽时青玉雕琢似的瓣尖泛着月白，待全盛时竟如翡翠盏中盛着冰酿，教人疑心是王母瑶池遗落的仙品。偶有花瓣飘落，便成了绣毯上滚动的玛瑙珠，连泥土都浸染了雍容的芬芳。这般倾国之色，难怪刘禹锡咏道唯有牡丹真国色，花开时节动京城——它用整季的绚烂，诠释了何为花中魁首的盛大气象。\",\n \"apply_text_normalization\": \"auto\",\n \"apply_language_text_normalization\": true,\n \"latex_read\": true,\n \"text_normalization\": true,\n \"audio_setting\": {\n \"sample_rate\": 24000,\n \"bitrate\": 32000,\n \"format\": \"mp3\",\n \"channel\": 2\n },\n \"timber_weights\": [\n {\n \"voice_id\": \"6889b7f4662160e2caad60e9\",\n \"weight\": 80\n },\n {\n \"voice_id\": \"6889b7f3662160e2caad60e8\",\n \"weight\": 60\n },\n {\n \"voice_id\": \"6889b7f3662160e2caad60e7\",\n \"weight\": 30\n },\n {\n \"voice_id\": \"6889b7f2662160e2caad60e6\",\n \"weight\": 10\n }\n ],\n \"pronunciation_dict\": {\n \"tone\" : [\n \"雍容/(yong3)(neng4)\",\n \"牡丹/(mu4)(dan3)\"\n ]\n },\n \"voice_modify\": {\n \"pitch\": 50,\n \"intensity\": 30,\n \"timbre\": -50,\n \"sound_effects\": \"robotic\"\n },\n \"subtitle_enable\": true\n }\n}");
Request request = new Request.Builder()
.url("https://openapi.akool.com/api/open/v4/voice/tts")
.method("POST", body)
.addHeader("Authorization", "Bearer {{token}}")
.addHeader("Content-Type", "application/json")
.build();
Response response = client.newCall(request).execute();
```
```js Javascript
const myHeaders = new Headers();
myHeaders.append("Authorization", "Bearer {{token}}");
myHeaders.append("Content-Type", "application/json");
const raw = JSON.stringify({
"input_text": "暮春时节，牡丹园内千层叠瓣的姚黄魏紫次第苏醒。晨露未晞时，花瓣边缘凝着水晶般的珠光，内里丝绸质地的绛红由浅及深晕染开来，如同将晚霞裁作衣裳。风过处，花浪翻涌，金蕊颤动间暗香浮动，引得蜂蝶在花心盘旋出金色的漩涡。最是那株绿牡丹，初绽时青玉雕琢似的瓣尖泛着月白，待全盛时竟如翡翠盏中盛着冰酿，教人疑心是王母瑶池遗落的仙品。偶有花瓣飘落，便成了绣毯上滚动的玛瑙珠，连泥土都浸染了雍容的芬芳。这般倾国之色，难怪刘禹锡咏道唯有牡丹真国色，花开时节动京城——它用整季的绚烂，诠释了何为花中魁首的盛大气象。",
"voice_id": "6889b628662160e2caad5dbc",
"voice_options": {
"stability": 0.6,
"similarity_boost": 0.8,
"style": 1,
"speed": 1.0,
"speaker_boost": true,
"emotion": "happy",
"volume": 80
},
"pitch": -5,
"webhookUrl": "",
"language_code": "zh",
"extra_options": {
"previous_text": "暮春时节，牡丹园内千层叠瓣的姚黄魏紫次第苏醒。晨露未晞时，花瓣边缘凝着水晶般的珠光，内里丝绸质地的绛红由浅及深晕染开来，如同将晚霞裁作衣裳。风过处，花浪翻涌，金蕊颤动间暗香浮动，引得蜂蝶在花心盘旋出金色的漩涡。最是那株绿牡丹，初绽时青玉雕琢似的瓣尖泛着月白，待全盛时竟如翡翠盏中盛着冰酿，教人疑心是王母瑶池遗落的仙品。偶有花瓣飘落，便成了绣毯上滚动的玛瑙珠，连泥土都浸染了雍容的芬芳。这般倾国之色，难怪刘禹锡咏道唯有牡丹真国色，花开时节动京城——它用整季的绚烂，诠释了何为花中魁首的盛大气象。",
"next_text": "暮春时节，牡丹园内千层叠瓣的姚黄魏紫次第苏醒。晨露未晞时，花瓣边缘凝着水晶般的珠光，内里丝绸质地的绛红由浅及深晕染开来，如同将晚霞裁作衣裳。风过处，花浪翻涌，金蕊颤动间暗香浮动，引得蜂蝶在花心盘旋出金色的漩涡。最是那株绿牡丹，初绽时青玉雕琢似的瓣尖泛着月白，待全盛时竟如翡翠盏中盛着冰酿，教人疑心是王母瑶池遗落的仙品。偶有花瓣飘落，便成了绣毯上滚动的玛瑙珠，连泥土都浸染了雍容的芬芳。这般倾国之色，难怪刘禹锡咏道唯有牡丹真国色，花开时节动京城——它用整季的绚烂，诠释了何为花中魁首的盛大气象。",
"apply_text_normalization": "auto",
"apply_language_text_normalization": true,
"latex_read": true,
"text_normalization": true,
"audio_setting": {
"sample_rate": 24000,
"bitrate": 32000,
"format": "mp3",
"channel": 2
},
"timber_weights": [
{
"voice_id": "6889b7f4662160e2caad60e9",
"weight": 80
},
{
"voice_id": "6889b7f3662160e2caad60e8",
"weight": 60
},
{
"voice_id": "6889b7f3662160e2caad60e7",
"weight": 30
},
{
"voice_id": "6889b7f2662160e2caad60e6",
"weight": 10
}
],
"pronunciation_dict": {
"tone" : [
"雍容/(yong3)(neng4)",
"牡丹/(mu4)(dan3)"
]
},
"voice_modify": {
"pitch": 50,
"intensity": 30,
"timbre": -50,
"sound_effects": "robotic"
},
"subtitle_enable": true
}
});
const requestOptions = {
method: "POST",
headers: myHeaders,
body: raw,
redirect: "follow"
};
fetch("https://openapi.akool.com/api/open/v4/voice/tts", requestOptions)
.then((response) => response.text())
.then((result) => console.log(result))
.catch((error) => console.error(error));
```
```php PHP
'Bearer {{token}}',
'Content-Type' => 'application/json'
];
$body = '{
"input_text": "暮春时节，牡丹园内千层叠瓣的姚黄魏紫次第苏醒。晨露未晞时，花瓣边缘凝着水晶般的珠光，内里丝绸质地的绛红由浅及深晕染开来，如同将晚霞裁作衣裳。风过处，花浪翻涌，金蕊颤动间暗香浮动，引得蜂蝶在花心盘旋出金色的漩涡。最是那株绿牡丹，初绽时青玉雕琢似的瓣尖泛着月白，待全盛时竟如翡翠盏中盛着冰酿，教人疑心是王母瑶池遗落的仙品。偶有花瓣飘落，便成了绣毯上滚动的玛瑙珠，连泥土都浸染了雍容的芬芳。这般倾国之色，难怪刘禹锡咏道唯有牡丹真国色，花开时节动京城——它用整季的绚烂，诠释了何为花中魁首的盛大气象。",
"voice_id": "6889b628662160e2caad5dbc",
"voice_options": {
"stability": 0.6,
"similarity_boost": 0.8,
"style": 1,
"speed": 1.0,
"speaker_boost": true,
"emotion": "happy",
"volume": 80
},
"pitch": -5,
"webhookUrl": "",
"language_code": "zh",
"extra_options": {
"previous_text": "暮春时节，牡丹园内千层叠瓣的姚黄魏紫次第苏醒。晨露未晞时，花瓣边缘凝着水晶般的珠光，内里丝绸质地的绛红由浅及深晕染开来，如同将晚霞裁作衣裳。风过处，花浪翻涌，金蕊颤动间暗香浮动，引得蜂蝶在花心盘旋出金色的漩涡。最是那株绿牡丹，初绽时青玉雕琢似的瓣尖泛着月白，待全盛时竟如翡翠盏中盛着冰酿，教人疑心是王母瑶池遗落的仙品。偶有花瓣飘落，便成了绣毯上滚动的玛瑙珠，连泥土都浸染了雍容的芬芳。这般倾国之色，难怪刘禹锡咏道唯有牡丹真国色，花开时节动京城——它用整季的绚烂，诠释了何为花中魁首的盛大气象。",
"next_text": "暮春时节，牡丹园内千层叠瓣的姚黄魏紫次第苏醒。晨露未晞时，花瓣边缘凝着水晶般的珠光，内里丝绸质地的绛红由浅及深晕染开来，如同将晚霞裁作衣裳。风过处，花浪翻涌，金蕊颤动间暗香浮动，引得蜂蝶在花心盘旋出金色的漩涡。最是那株绿牡丹，初绽时青玉雕琢似的瓣尖泛着月白，待全盛时竟如翡翠盏中盛着冰酿，教人疑心是王母瑶池遗落的仙品。偶有花瓣飘落，便成了绣毯上滚动的玛瑙珠，连泥土都浸染了雍容的芬芳。这般倾国之色，难怪刘禹锡咏道唯有牡丹真国色，花开时节动京城——它用整季的绚烂，诠释了何为花中魁首的盛大气象。",
"apply_text_normalization": "auto",
"apply_language_text_normalization": true,
"latex_read": true,
"text_normalization": true,
"audio_setting": {
"sample_rate": 24000,
"bitrate": 32000,
"format": "mp3",
"channel": 2
},
"timber_weights": [
{
"voice_id": "6889b7f4662160e2caad60e9",
"weight": 80
},
{
"voice_id": "6889b7f3662160e2caad60e8",
"weight": 60
},
{
"voice_id": "6889b7f3662160e2caad60e7",
"weight": 30
},
{
"voice_id": "6889b7f2662160e2caad60e6",
"weight": 10
}
],
"pronunciation_dict": {
"tone" : [
"雍容/(yong3)(neng4)",
"牡丹/(mu4)(dan3)"
]
},
"voice_modify": {
"pitch": 50,
"intensity": 30,
"timbre": -50,
"sound_effects": "robotic"
},
"subtitle_enable": true
}
}';
$request = new Request('POST', 'https://openapi.akool.com/api/open/v4/voice/tts', $headers, $body);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();
?>
```
```python Python
import requests
import json
url = "https://openapi.akool.com/api/open/v4/voice/tts"
payload = json.dumps({
"input_text": "暮春时节，牡丹园内千层叠瓣的姚黄魏紫次第苏醒。晨露未晞时，花瓣边缘凝着水晶般的珠光，内里丝绸质地的绛红由浅及深晕染开来，如同将晚霞裁作衣裳。风过处，花浪翻涌，金蕊颤动间暗香浮动，引得蜂蝶在花心盘旋出金色的漩涡。最是那株绿牡丹，初绽时青玉雕琢似的瓣尖泛着月白，待全盛时竟如翡翠盏中盛着冰酿，教人疑心是王母瑶池遗落的仙品。偶有花瓣飘落，便成了绣毯上滚动的玛瑙珠，连泥土都浸染了雍容的芬芳。这般倾国之色，难怪刘禹锡咏道唯有牡丹真国色，花开时节动京城——它用整季的绚烂，诠释了何为花中魁首的盛大气象。",
"voice_id": "6889b628662160e2caad5dbc",
"voice_options": {
"stability": 0.6,
"similarity_boost": 0.8,
"style": 1,
"speed": 1.0,
"speaker_boost": true,
"emotion": "happy",
"volume": 80
},
"pitch": -5,
"webhookUrl": "",
"language_code": "zh",
"extra_options": {
"previous_text": "暮春时节，牡丹园内千层叠瓣的姚黄魏紫次第苏醒。晨露未晞时，花瓣边缘凝着水晶般的珠光，内里丝绸质地的绛红由浅及深晕染开来，如同将晚霞裁作衣裳。风过处，花浪翻涌，金蕊颤动间暗香浮动，引得蜂蝶在花心盘旋出金色的漩涡。最是那株绿牡丹，初绽时青玉雕琢似的瓣尖泛着月白，待全盛时竟如翡翠盏中盛着冰酿，教人疑心是王母瑶池遗落的仙品。偶有花瓣飘落，便成了绣毯上滚动的玛瑙珠，连泥土都浸染了雍容的芬芳。这般倾国之色，难怪刘禹锡咏道唯有牡丹真国色，花开时节动京城——它用整季的绚烂，诠释了何为花中魁首的盛大气象。",
"next_text": "暮春时节，牡丹园内千层叠瓣的姚黄魏紫次第苏醒。晨露未晞时，花瓣边缘凝着水晶般的珠光，内里丝绸质地的绛红由浅及深晕染开来，如同将晚霞裁作衣裳。风过处，花浪翻涌，金蕊颤动间暗香浮动，引得蜂蝶在花心盘旋出金色的漩涡。最是那株绿牡丹，初绽时青玉雕琢似的瓣尖泛着月白，待全盛时竟如翡翠盏中盛着冰酿，教人疑心是王母瑶池遗落的仙品。偶有花瓣飘落，便成了绣毯上滚动的玛瑙珠，连泥土都浸染了雍容的芬芳。这般倾国之色，难怪刘禹锡咏道唯有牡丹真国色，花开时节动京城——它用整季的绚烂，诠释了何为花中魁首的盛大气象。",
"apply_text_normalization": "auto",
"apply_language_text_normalization": true,
"latex_read": true,
"text_normalization": true,
"audio_setting": {
"sample_rate": 24000,
"bitrate": 32000,
"format": "mp3",
"channel": 2
},
"timber_weights": [
{
"voice_id": "6889b7f4662160e2caad60e9",
"weight": 80
},
{
"voice_id": "6889b7f3662160e2caad60e8",
"weight": 60
},
{
"voice_id": "6889b7f3662160e2caad60e7",
"weight": 30
},
{
"voice_id": "6889b7f2662160e2caad60e6",
"weight": 10
}
],
"pronunciation_dict": {
"tone" : [
"雍容/(yong3)(neng4)",
"牡丹/(mu4)(dan3)"
]
},
"voice_modify": {
"pitch": 50,
"intensity": 30,
"timbre": -50,
"sound_effects": "robotic"
},
"subtitle_enable": true
}
})
headers = {
'Authorization': 'Bearer {{token}}',
'Content-Type': 'application/json'
}
response = requests.request("POST", url, headers=headers, data=payload)
print(response.text)
```
**Response**
```json
{
"code": 1000,
"msg": "OK",
"data": {
"create_time": 1751350015709,
"uid": 101400,
"team_id": "6805fb69e92d9edc7ca0b409",
"input_text": "Welcome to the Akool generative AI content creation tool.",
"preview": null,
"status": 1,
"webhookUrl": "",
"duration": 0,
"file_name": "1ef1d76ebfc244f7a30430f7049d6ebc.mp3",
"gender": "Male",
"deduction_credit": 1.9295,
"name": "27fec311afd743aa889a057e17e93c13",
"_id": "68637aff41e5eb74bb8dfe73",
"voice_model_id": "686379d641e5eb74bb8dfe3f",
"voice_id": "Tq06jbVyFH4l6R-Gjvo_V-p_nVYk5DRrYJZsxeDmlhEtyhcFKKLQODmgngI9llKw",
"voice_options": {
"stability": 0.7,
"similarity_boost": 0.5,
"style": 0.6,
"speed": 0.8,
"speaker_boost": false,
"emotion": "happy",
"volume": 50
}
}
}
```
## Create Voice Changer
Only the Akool Multilingual 1 model supports Voice Change.
```
POST https://openapi.akool.com/api/open/v4/voice/change
```
**Request Headers**
| **Parameter** | **Value** | **Description** |
| ------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------ |
| Authorization | Bearer `{token}` | Your API Key used for request authorization. [getToken](https://docs.akool.com/authentication/usage#get-the-token) |
**Body Attributes**
| **Parameter** | **Type** | **Required** | **Value** | **Description** |
| --------------------------- | -------- | ------------ | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| voice\_id | String | true | | Voice ID， get this voice\_id from your cloned voices or akool voice list. [getVoiceId](https://docs.akool.com/ai-tools-suite/voiceLab#get-voice-list) |
| source\_voice\_file | String | true | | Audio file URL, supports mp3, mp4, wav, etc. Must be a public accessible URL, The maximum file size is 50MB. |
| voice\_options | Object | false | | Audio settings |
| - stability | Number | false | | Voice stability (0-1) , Supported voice models: Akool Multilingual 1, [getVoiceModelName](https://docs.akool.com/ai-tools-suite/voiceLab#get-voice-list) |
| - similarity\_boost | Number | false | | Similarity boost (0-1) , Supported voice models: Akool Multilingual 1, [getVoiceModelName](https://docs.akool.com/ai-tools-suite/voiceLab#get-voice-list) |
| - style | Number | false | | Voice style (0-1) , Supported voice models: Akool Multilingual 1, Akool Multilingual 2. Style examples: cheerful, [getVoiceModelName](https://docs.akool.com/ai-tools-suite/voiceLab#get-voice-list) |
| - speaker\_boost | Boolean | false | | Speaker boost, Supported voice models: Akool Multilingual 1, [getVoiceModelName](https://docs.akool.com/ai-tools-suite/voiceLab#get-voice-list) |
| - file\_format | String | false | mp3 | File format, supports mp3 and wav formats. |
| - remove\_background\_noise | Boolean | false | false | Remove background noise, disabled by default |
| - speed | Number | false | 1 | Controls the speed of generated audio, default value is 1, available range \[0.7, 1.2]. |
| webhookUrl | String | false | | Callback url address based on HTTP request |
| voice\_model\_name | String | false | | The designated model for Clone, Supported voice models: Akool Multilingual 1. [getVoiceModelName](https://docs.akool.com/ai-tools-suite/voiceLab#get-voice-list) |
**Response Attributes**
| **Parameter** | **Type** | **Value** | **Description** |
| --------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| - code | Integer | 1000
| API returns status code(1000:success) |
| - msg | String | | API returns status message |
| - data | Object | | Response data object |
| - create\_time | Long | 1751350363707
| Creation timestamp |
| - uid | Integer | 101400
| User ID |
| - team\_id | String | "6805fb69e92d9edc7ca0b409"
| Team ID |
| - preview | String | null
| Generated audio URL, this value will be updated after task completion, you can view it in the resourceList. [getResourceList](https://docs.akool.com/ai-tools-suite/voiceLab#get-voice-results-list) |
| - source\_voice\_file | String | "[https://drz0f01yeq1cx.cloudfront.net/1749098405491-5858-1749019840512audio.mp3](https://drz0f01yeq1cx.cloudfront.net/1749098405491-5858-1749019840512audio.mp3)" | Original audio file URL |
| - status | Integer | 1
| Voice changer status: 【1:queueing, 2:processing, 3:completed, 4:failed】 |
| - webhookUrl | String | ""
| Callback URL |
| - duration | Integer | 12800
| Audio duration in milliseconds |
| - file\_name | String | "1749098405491-5858-1749019840512audio.mp3"
| Generated file name |
| - gender | String | "Female"
| Voice gender |
| - deduction\_credit | Float | 0.512
| Deducted credits |
| - name | String | "3f591fc370c542fca9087f124b5ad82b"
| Generated name |
| - \_id | String | "68637c5b41e5eb74bb8dfec6"
| Document ID |
| - voice\_model\_id | String | "67a45479354b7c1fff7e943a"
| Voice document ID |
| - voice\_id | String | "hkfHEbBvdQFNX4uWHqRF"
| Voice ID |
| - voice\_options | Object | | Voice options object |
| - stability | Number | 0.7
| Voice stability setting |
| - similarity\_boost | Number | 0.5
| Similarity boost setting |
| - style | Number | 0.6
| Voice style setting |
| - speaker\_boost | Boolean | false
| Speaker boost setting |
### Example
**Body**
```json
{
"voice_id": "6889b628662160e2caad5dbc",
"source_voice_file": "https://drz0f01yeq1cx.cloudfront.net/1749098405491-5858-1749019840512audio.mp3",
"voice_options": {
"stability": 0.9,
"similarity_boost": 0.7,
"style": 1,
"speaker_boost": false,
"remove_background_noise": true,
"speed": 1,
"file_format": "mp3"
},
"voice_model_name": "Akool Multilingual 1",
"webhookUrl": ""
}
```
**Request**
```bash cURL
curl --location 'https://openapi.akool.com/api/open/v4/voice/change' \
--header 'Authorization: Bearer {{token}}' \
--header 'Content-Type: application/json' \
--data '{
"voice_id": "6889b628662160e2caad5dbc",
"source_voice_file": "https://drz0f01yeq1cx.cloudfront.net/1749098405491-5858-1749019840512audio.mp3",
"voice_options": {
"stability": 0.9,
"similarity_boost": 0.7,
"style": 1,
"speaker_boost": false,
"remove_background_noise": true,
"speed": 1,
"file_format": "mp3"
},
"voice_model_name": "Akool Multilingual 1",
"webhookUrl": ""
}'
```
```java Java
OkHttpClient client = new OkHttpClient().newBuilder()
.build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n \"voice_id\": \"6889b628662160e2caad5dbc\",\n \"source_voice_file\": \"https://drz0f01yeq1cx.cloudfront.net/1749098405491-5858-1749019840512audio.mp3\",\n \"voice_options\": {\n \"stability\": 0.9,\n \"similarity_boost\": 0.7,\n \"style\": 1,\n \"speaker_boost\": false,\n \"remove_background_noise\": true,\n \"speed\": 1,\n \"file_format\": \"mp3\"\n },\n \"voice_model_name\": \"Akool Multilingual 1\",\n \"webhookUrl\": \"\"\n}");
Request request = new Request.Builder()
.url("https://openapi.akool.com/api/open/v4/voice/change")
.method("POST", body)
.addHeader("Authorization", "Bearer {{token}}")
.addHeader("Content-Type", "application/json")
.build();
Response response = client.newCall(request).execute();
```
```js Javascript
const myHeaders = new Headers();
myHeaders.append("Authorization", "Bearer {{token}}");
myHeaders.append("Content-Type", "application/json");
const raw = JSON.stringify({
"voice_id": "6889b628662160e2caad5dbc",
"source_voice_file": "https://drz0f01yeq1cx.cloudfront.net/1749098405491-5858-1749019840512audio.mp3",
"voice_options": {
"stability": 0.9,
"similarity_boost": 0.7,
"style": 1,
"speaker_boost": false,
"remove_background_noise": true,
"speed": 1,
"file_format": "mp3"
},
"voice_model_name": "Akool Multilingual 1",
"webhookUrl": ""
});
const requestOptions = {
method: "POST",
headers: myHeaders,
body: raw,
redirect: "follow"
};
fetch("https://openapi.akool.com/api/open/v4/voice/change", requestOptions)
.then((response) => response.text())
.then((result) => console.log(result))
.catch((error) => console.error(error));
```
```php PHP
'Bearer {{token}}',
'Content-Type' => 'application/json'
];
$body = '{
"voice_id": "6889b628662160e2caad5dbc",
"source_voice_file": "https://drz0f01yeq1cx.cloudfront.net/1749098405491-5858-1749019840512audio.mp3",
"voice_options": {
"stability": 0.9,
"similarity_boost": 0.7,
"style": 1,
"speaker_boost": false,
"remove_background_noise": true,
"speed": 1,
"file_format": "mp3"
},
"voice_model_name": "Akool Multilingual 1",
"webhookUrl": ""
}';
$request = new Request('POST', 'https://openapi.akool.com/api/open/v4/voice/change', $headers, $body);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();
?>
```
```python Python
import requests
import json
url = "https://openapi.akool.com/api/open/v4/voice/change"
payload = json.dumps({
"voice_id": "6889b628662160e2caad5dbc",
"source_voice_file": "https://drz0f01yeq1cx.cloudfront.net/1749098405491-5858-1749019840512audio.mp3",
"voice_options": {
"stability": 0.9,
"similarity_boost": 0.7,
"style": 1,
"speaker_boost": false,
"remove_background_noise": true,
"speed": 1,
"file_format": "mp3"
},
"voice_model_name": "Akool Multilingual 1",
"webhookUrl": ""
})
headers = {
'Authorization': 'Bearer {{token}}',
'Content-Type': 'application/json'
}
response = requests.request("POST", url, headers=headers, data=payload)
print(response.text)
```
**Response**
```json
{
"code": 1000,
"msg": "OK",
"data": {
"create_time": 1751350363707,
"uid": 101400,
"team_id": "6805fb69e92d9edc7ca0b409",
"source_voice_file": "https://drz0f01yeq1cx.cloudfront.net/1749098405491-5858-1749019840512audio.mp3",
"preview": null,
"status": 1,
"webhookUrl": "",
"duration": 12800,
"file_name": "1749098405491-5858-1749019840512audio.mp3",
"gender": "Female",
"deduction_credit": 0.512,
"name": "3f591fc370c542fca9087f124b5ad82b",
"_id": "68637c5b41e5eb74bb8dfec6",
"voice_model_id": "67a45479354b7c1fff7e943a",
"voice_id": "hkfHEbBvdQFNX4uWHqRF",
"voice_options": {
"stability": 0.7,
"similarity_boost": 0.5,
"style": 0.6,
"speaker_boost": false
}
}
}
```
## Get Voice Results List
```
GET https://openapi.akool.com/api/open/v4/voice/resource/list
```
**Request Headers**
| **Parameter** | **Value** | **Description** |
| ------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------ |
| Authorization | Bearer `{token}` | Your API Key used for request authorization. [getToken](https://docs.akool.com/authentication/usage#get-the-token) |
**Query Attributes**
| **Parameter** | **Type** | **Required** | **Value** | **Description** |
| ------------- | -------- | ------------ | --------- | -------------------------- |
| type | String | true | 1,2 | 1-voiceTTS, 2-voiceChanger |
| page | String | false | 1 | Page number |
| size | String | false | 10 | Page size |
**Response Attributes**
| **Parameter** | **Type** | **Value** | **Description** |
| ------------------- | -------- | ---------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
| - code | Integer | 1000
| API returns status code(1000:success) |
| - msg | String | | API returns status message |
| - data | Object | | Response data object |
| - result | Array | | Voice resource list |
| - \_id | String | "68637c5b41e5eb74bb8dfec6"
| Document ID |
| - create\_time | Long | 1751350363707
| Creation timestamp |
| - update\_time | Long | 1751350368468
| Update timestamp |
| - uid | Integer | 101400
| User ID |
| - team\_id | String | "6805fb69e92d9edc7ca0b409"
| Team ID |
| - rate | String | "100%"
| Processing rate |
| - preview | String | "[https://drz0f01yeq1cx.cloudfront.net/](https://drz0f01yeq1cx.cloudfront.net/)..." | Generated audio URL |
| - status | Integer | 3
| Status: 【1:queueing, 2:processing, 3:completed, 4:failed】 |
| - webhookUrl | String | ""
| Callback URL |
| - duration | Integer | 12852
| Audio duration in milliseconds |
| - file\_name | String | "1749098405491-5858-1749019840512audio.mp3"
| File name |
| - gender | String | "Female"
| Voice gender |
| - deduction\_credit | Float | 0.9295
| Deducted credits |
| - name | String | "3f591fc370c542fca9087f124b5ad82b"
| Resource name |
| - input\_text | String | "Słyszę, że chcesz leżeć płasko? Gratulacje — przynajmniej zrozumiałeś grawitację! "
| Text to Speech trial listening text |
| - \_\_v | Integer | 0
| Version number |
| - count | Integer | 1
| Total count of resources |
| - page | Integer | 1
| Current page number |
| - size | Integer | 10
| Page size |
### Example
**Request**
```bash cURL
curl --location 'https://openapi.akool.com/api/open/v4/voice/resource/list?type=1&page=1&size=10' \
--header 'Authorization: Bearer {{token}}'
```
```java Java
OkHttpClient client = new OkHttpClient().newBuilder()
.build();
MediaType mediaType = MediaType.parse("text/plain");
RequestBody body = RequestBody.create(mediaType, "");
Request request = new Request.Builder()
.url("https://openapi.akool.com/api/open/v4/voice/resource/list?type=1&page=1&size=10")
.method("GET", body)
.addHeader("Authorization", "Bearer {{token}}")
.build();
Response response = client.newCall(request).execute();
```
```js Javascript
const myHeaders = new Headers();
myHeaders.append("Authorization", "Bearer {{token}}");
const requestOptions = {
method: "GET",
headers: myHeaders,
redirect: "follow"
};
fetch("https://openapi.akool.com/api/open/v4/voice/resource/list?type=1&page=1&size=10", requestOptions)
.then((response) => response.text())
.then((result) => console.log(result))
.catch((error) => console.error(error));
```
```php PHP
'Bearer {{token}}'
];
$request = new Request('GET', 'https://openapi.akool.com/api/open/v4/voice/resource/list?type=1&page=1&size=10', $headers);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();
?>
```
```python Python
import requests
url = "https://openapi.akool.com/api/open/v4/voice/resource/list?type=1&page=1&size=10"
payload = {}
headers = {
'Authorization': 'Bearer {{token}}'
}
response = requests.request("GET", url, headers=headers, data=payload)
print(response.text)
```
**Response**
```json
{
"code": 1000,
"msg": "OK",
"data": {
"result": [
{
"_id": "68637c5b41e5eb74bb8dfec6",
"create_time": 1751350363707,
"update_time": 1751350368468,
"uid": 101400,
"team_id": "6805fb69e92d9edc7ca0b409",
"rate": "100%",
"preview": "https://drz0f01yeq1cx.cloudfront.net/1751350368172-audio.mp3",
"status": 3,
"webhookUrl": "",
"duration": 12852,
"file_name": "1749098405491-5858-1749019840512audio.mp3",
"gender": "Female",
"deduction_credit": 0.9295,
"name": "3f591fc370c542fca9087f124b5ad82b",
"input_text": "Słyszę, że chcesz leżeć płasko? Gratulacje — przynajmniej zrozumiałeś grawitację! ",
"__v": 0
}
],
"count": 1,
"page": 1,
"size": 10
}
}
```
## Get Voice List
```
GET https://openapi.akool.com/api/open/v4/voice/list
```
**Request Headers**
| **Parameter** | **Value** | **Description** |
| ------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------ |
| Authorization | Bearer `{token}` | Your API Key used for request authorization. [getToken](https://docs.akool.com/authentication/usage#get-the-token) |
**Query Attributes**
| **Parameter** | **Type** | **Required** | **Value** | **Description** |
| --------------- | -------- | ------------ | --------------------------------------------- | ---------------------------------------------------------------- |
| type | String | true | 1,2
| 1-VoiceClone, 2-Akool Voices |
| page | String | false | 1
| Page number |
| size | String | false | 10
| Page size |
| style | String | false | Calm,Authoritative
| Voice style filters, separated by commas |
| gender | String | false | Male,Female
| Gender filters, separated by commas |
| age | String | false | Young,Middle,Elderly
| Age filters, separated by commas |
| scenario | String | false | Advertisement,Education
| Scenario filters, separated by commas |
| name | String | false | MyVoice
| Voice name, supports fuzzy search |
| support\_stream | Integer | false | 1
| 2-Voice does not support streaming.； 1-Voice supports streaming. |
**Response Attributes**
| **Parameter** | **Type** | **Value** | **Description** |
| -------------------- | -------- | ----------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| - code | Integer | 1000
| API returns status code(1000:success) |
| - msg | String | | API returns status message |
| - data | Object | | Response data object |
| - result | Array | | Voice list |
| - \_id | String | "68676e544439e3b8e246a077"
| Document ID |
| - uid | Integer | 101400
| User ID |
| - team\_id | String | "6805fb69e92d9edc7ca0b409"
| Team ID |
| - voice\_id | String | "zQAGCFElz23u6Brdj4L-NrbEmSxswXdoPN\_GBpYgUPHo1EGWgZgAnFJexONx\_jGy"
| Voice ID |
| - gender | String | "Male"
| Voice gender |
| - language | String | "Polish"
| Voice language |
| - locale | String | "pl"
| Voice locale |
| - name | String | "MyVoice0626-01"
| Voice name |
| - preview | String | "[https://d2qf6ukcym4kn9.cloudfront.net/](https://d2qf6ukcym4kn9.cloudfront.net/)..."
| Preview audio URL |
| - text | String | "This is a comic style model..."
| Preview text content |
| - duration | Integer | 9822
| Audio duration in milliseconds |
| - status | Integer | 3
| Voice status: 【1:queueing, 2:processing, 3:completed, 4:failed】 |
| - create\_time | Long | 1751608916162
| Creation timestamp |
| - update\_time | Long | 1751608916162
| Update timestamp |
| - style | Array | \["Authoritative", "Calm"]
| Voice style tags |
| - scenario | Array | \["Advertisement"]
| Scenario tags |
| - age | Array | \["Elderly", "Middle"]
| Age tags |
| - deduction\_credit | Integer | 0
| Deducted credits |
| - webhookUrl | String | ""
| Callback URL |
| - voice\_model\_name | String | "Akool Multilingual 3"
| Supported voice model name |
| - support\_stream | Boolean | true
| Supported stream: true/false, Akool Multilingual 1 & Akool Multilingual 3 only support stream. |
| - count | Integer | 9
| Total count of voices |
| - page | Integer | 1
| Current page number |
| - size | Integer | 1
| Page size |
### Example
**Request**
```bash cURL
curl --location 'https://openapi.akool.com/api/open/v4/voice/list?type=1&page=1&size=10&style=Calm,Authoritative&gender=Male&name=MyVoice' \
--header 'Authorization: Bearer {{token}}'
```
```java Java
OkHttpClient client = new OkHttpClient().newBuilder()
.build();
MediaType mediaType = MediaType.parse("text/plain");
RequestBody body = RequestBody.create(mediaType, "");
Request request = new Request.Builder()
.url("https://openapi.akool.com/api/open/v4/voice/list?type=1&page=1&size=10&style=Calm,Authoritative&gender=Male&name=MyVoice")
.method("GET", body)
.addHeader("Authorization", "Bearer {{token}}")
.build();
Response response = client.newCall(request).execute();
```
```js Javascript
const myHeaders = new Headers();
myHeaders.append("Authorization", "Bearer {{token}}");
const requestOptions = {
method: "GET",
headers: myHeaders,
redirect: "follow"
};
fetch("https://openapi.akool.com/api/open/v4/voice/list?type=1&page=1&size=10&style=Calm,Authoritative&gender=Male&name=MyVoice", requestOptions)
.then((response) => response.text())
.then((result) => console.log(result))
.catch((error) => console.error(error));
```
```php PHP
'Bearer {{token}}'
];
$request = new Request('GET', 'https://openapi.akool.com/api/open/v4/voice/list?type=1&page=1&size=10&style=Calm,Authoritative&gender=Male&name=MyVoice', $headers);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();
?>
```
```python Python
import requests
url = "https://openapi.akool.com/api/open/v4/voice/list"
payload = {}
headers = {
'Authorization': 'Bearer {{token}}'
}
params = {
'type': '1',
'page': '1',
'size': '10',
'style': 'Calm,Authoritative',
'gender': 'Male',
'name': 'MyVoice'
}
response = requests.request("GET", url, headers=headers, data=payload, params=params)
print(response.text)
```
**Response**
```json
{
"code": 1000,
"msg": "OK",
"data": {
"result": [
{
"_id": "68676e544439e3b8e246a077",
"uid": 101400,
"team_id": "6805fb69e92d9edc7ca0b409",
"voice_id": "zQAGCFElz23u6Brdj4L-NrbEmSxswXdoPN_GBpYgUPHo1EGWgZgAnFJexONx_jGy",
"gender": "Male",
"language": "Polish",
"locale": "pl",
"name": "MyVoice0626-01",
"preview": "https://d2qf6ukcym4kn9.cloudfront.net/1751608955706-c1cf1692-fd47-417c-b18a-dcbbb93360fa-2756.mp3",
"text": "This is a comic style model, this is a comic style model, this is a comic style model, this is a comic style model",
"duration": 9822,
"status": 3,
"create_time": 1751608916162,
"style": [
"Authoritative",
"Calm"
],
"scenario": [
"Advertisement"
],
"age": [
"Elderly",
"Middle"
],
"deduction_credit": 0,
"webhookUrl": "",
"voice_model_name": "Akool Multilingual 3",
"support_stream": true
}
],
"count": 9,
"page": 1,
"size": 1
}
}
```
## Delete Voice
```
POST https://openapi.akool.com/api/open/v4/voice/del
```
**Request Headers**
| **Parameter** | **Value** | **Description** |
| ------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------- |
| Authorization | Bearer `{token}` | Your API Key used for request authorization.[getToken](https://docs.akool.com/authentication/usage#get-the-token) |
**Body Attributes**
| **Parameter** | **Type** | **Required** | **Value** | **Description** |
| ------------- | -------- | ------------ | --------- | ----------------------------------------------------------------------------------------------------------- |
| \_ids | Array | true | | Voice list document IDs [getVoiceDocumentId](https://docs.akool.com/ai-tools-suite/voiceLab#get-voice-list) |
**Response Attributes**
| **Parameter** | **Type** | **Value** | **Description** |
| -------------------- | -------- | ------------------------------------------------------------------------- | ------------------------------------- |
| - code | integer | 1000
| API returns status code(1000:success) |
| - msg | String | | API returns status message |
| - data | Object | | Response data object |
| - successIds | Array | | Deleted voice document IDs |
| - noPermissionVoices | Array | | Delete failed voice document msg list |
| - \_id | String | 6881cd86618fa41c89557b0c
| Delete failed voice document ID |
| - msg | String | VoiceId:6881cd86618fa41c89557b0c resource not found
| Delete failed voice error msg |
### Example
**Body**
```json
{
"_ids": [
"6836b8183a59f36196bb9c52",
"6836ba935026505ab7a529ce"
]
}
```
**Request**
```bash cURL
curl --location --request DELETE 'https://openapi.akool.com/api/open/v4/voice/del' \
--header 'Authorization: Bearer {{token}}' \
--header 'Content-Type: application/json' \
--data '{
"_ids": [
"6836b8183a59f36196bb9c52",
"6836ba935026505ab7a529ce"
]
}'
```
```java Java
OkHttpClient client = new OkHttpClient().newBuilder()
.build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n \"_ids\": [\n \"6836b8183a59f36196bb9c52\",\n \"6836ba935026505ab7a529ce\"\n ]\n}");
Request request = new Request.Builder()
.url("https://openapi.akool.com/api/open/v4/voice/del")
.method("DELETE", body)
.addHeader("Authorization", "Bearer {{token}}")
.addHeader("Content-Type", "application/json")
.build();
Response response = client.newCall(request).execute();
```
```js Javascript
const myHeaders = new Headers();
myHeaders.append("Authorization", "Bearer {{token}}");
myHeaders.append("Content-Type", "application/json");
const raw = JSON.stringify({
"_ids": [
"6836b8183a59f36196bb9c52",
"6836ba935026505ab7a529ce"
]
});
const requestOptions = {
method: "DELETE",
headers: myHeaders,
body: raw,
redirect: "follow"
};
fetch("https://openapi.akool.com/api/open/v4/voice/del", requestOptions)
.then((response) => response.text())
.then((result) => console.log(result))
.catch((error) => console.error(error));
```
```php PHP
'Bearer {{token}}',
'Content-Type' => 'application/json'
];
$body = '{
"_ids": [
"6836b8183a59f36196bb9c52",
"6836ba935026505ab7a529ce"
]
}';
$request = new Request('DELETE', 'https://openapi.akool.com/api/open/v4/voice/del', $headers, $body);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();
?>
```
```python Python
import requests
import json
url = "https://openapi.akool.com/api/open/v4/voice/del"
payload = json.dumps({
"_ids": [
"6836b8183a59f36196bb9c52",
"6836ba935026505ab7a529ce"
]
})
headers = {
'Authorization': 'Bearer {{token}}',
'Content-Type': 'application/json'
}
response = requests.request("DELETE", url, headers=headers, data=payload)
print(response.text)
```
**Response**
```json
{
"code": 1000,
"msg": "Delete voice successfully",
"data": {
"successIds": [
"6882f4c10529ae771e71531d"
],
"noPermissionVoices": [
{
"_id": "6881cd86618fa41c89557b0c",
"msg": "VoiceId:6881cd86618fa41c89557b0c resource not found"
}
]
}
}
```
## Get Voice Detail
```
GET https://openapi.akool.com/api/open/v4/voice/detail/{_id}
```
**Request Headers**
| **Parameter** | **Value** | **Description** |
| ------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------- |
| Authorization | Bearer `{token}` | Your API Key used for request authorization.[getToken](https://docs.akool.com/authentication/usage#get-the-token) |
**Path Attributes**
| **Parameter** | **Type** | **Required** | **Value** | **Description** |
| ------------- | -------- | ------------ | --------- | ----------------------------------------------------------------------------------------------------------- |
| \_id | String | true | | Voice list document IDs [getVoiceDocumentId](https://docs.akool.com/ai-tools-suite/voiceLab#get-voice-list) |
**Response Attributes**
| **Parameter** | **Type** | **Value** | **Description** |
| -------------------- | -------- | ----------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| - code | Integer | 1000
| API returns status code(1000:success) |
| - msg | String | | API returns status message |
| - data | Object | | Response data object |
| - \_id | String | "6836bafb5026505ab7a529fa"
| Document ID |
| - uid | Integer | 101400
| User ID |
| - team\_id | String | "6805fb69e92d9edc7ca0b409"
| Team ID |
| - voice\_id | String | "yRBw4OM8YFm5pCNKxJQ7"
| Voice ID |
| - gender | String | "Male"
| Voice gender |
| - name | String | "Snow Peak 01"
| Voice name |
| - preview | String | "[https://drz0f01yeq1cx.cloudfront.net/](https://drz0f01yeq1cx.cloudfront.net/)..." | Preview audio URL |
| - text | String | "Hello, I'm your personalized AI voice..." | Preview text content |
| - duration | Integer | 7055
| Audio duration in milliseconds |
| - status | Integer | 3
| Voice status: 【1:queueing, 2:processing, 3:completed, 4:failed】 |
| - create\_time | Long | 1748417275493
| Creation timestamp |
| - style | Array | \["Authoritative", "Calm"]
| Voice style tags |
| - scenario | Array | \["Advertisement"]
| Scenario tags |
| - age | Array | \["Elderly", "Middle"]
| Age tags |
| - deduction\_credit | Integer | 0
| Deducted credits |
| - voice\_model\_name | String | "Akool Multilingual 1"
| Supported voice model name |
| - support\_stream | Boolean | true
| Supported stream: true/false, Akool Multilingual 1 & Akool Multilingual 3 only support stream. |
| - language | String | "Chinese"
| Voice language |
| - locale | String | "zh"
| Voice locale |
| - update\_time | Long | 1751608916162
| Update timestamp |
### Example
**Request**
```bash cURL
curl --location 'https://openapi.akool.com/api/open/v4/voice/detail/6836bafb5026505ab7a529fa' \
--header 'Authorization: Bearer {{token}}'
```
```java Java
OkHttpClient client = new OkHttpClient().newBuilder()
.build();
MediaType mediaType = MediaType.parse("text/plain");
RequestBody body = RequestBody.create(mediaType, "");
Request request = new Request.Builder()
.url("https://openapi.akool.com/api/open/v4/voice/detail/6836bafb5026505ab7a529fa")
.method("GET", body)
.addHeader("Authorization", "Bearer {{token}}")
.build();
Response response = client.newCall(request).execute();
```
```js Javascript
const myHeaders = new Headers();
myHeaders.append("Authorization", "Bearer {{token}}");
const requestOptions = {
method: "GET",
headers: myHeaders,
redirect: "follow"
};
fetch("https://openapi.akool.com/api/open/v4/voice/detail/6836bafb5026505ab7a529fa", requestOptions)
.then((response) => response.text())
.then((result) => console.log(result))
.catch((error) => console.error(error));
```
```php PHP
'Bearer {{token}}'
];
$request = new Request('GET', 'https://openapi.akool.com/api/open/v4/voice/detail/6836bafb5026505ab7a529fa', $headers);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();
?>
```
```python Python
import requests
url = "https://openapi.akool.com/api/open/v4/voice/detail/6836bafb5026505ab7a529fa"
payload = {}
headers = {
'Authorization': 'Bearer {{token}}'
}
response = requests.request("GET", url, headers=headers, data=payload)
print(response.text)
```
**Response**
```json
{
"code": 1000,
"msg": "OK",
"data": {
"_id": "6882f23c0529ae771e7152dc",
"uid": 101400,
"team_id": "6805fb69e92d9edc7ca0b409",
"voice_id": "kfr_1wGPuauzcSOZgpBGLd_ApviIHqMIZ5bS2OeMiMkvId0eAMkq1ii8rvInZ2pE",
"gender": "Male",
"name": "zhongwen-072501",
"preview": "https://drz0f01yeq1cx.cloudfront.net/1753412190380-sample.mp3",
"text": "人生就像登山，重要的不是顶峰的高度，而是攀登时的姿态。当你觉得脚步沉重时，请记住：竹子用四年时间仅生长3厘米，但从第五年开始，每天以30厘米的速度疯长。那些看似微不足道的积累，终将在某个转角绽放光芒。前路或许泥泞，但每个坚持的脚印都在书写传奇；黑夜也许漫长，但晨光总在咬牙坚持后准时降临。正如海明威所说：人可以被毁灭，但不能被打败。2025年的今天，愿你把挫折当作垫脚石，让汗水成为勋章，因为这个世界永远奖励那些在跌倒后依然选择起身奔跑的人。",
"duration": 55353,
"status": 3,
"create_time": 1753412156588,
"style": [
"Authoritative",
"Calm"
],
"scenario": [
"Advertisenment"
],
"age": [
"Elderly",
"Middle"
],
"deduction_credit": 0,
"webhookUrl": "",
"language": "Chinese",
"locale": "zh",
"voice_model_name": "Akool Multilingual 3",
"support_stream": true
}
}
```
## Get Voice Result Detail
```
GET https://openapi.akool.com/api/open/v4/voice/resource/detail/{_id}
```
**Request Headers**
| **Parameter** | **Value** | **Description** |
| ------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------- |
| Authorization | Bearer `{token}` | Your API Key used for request authorization.[getToken](https://docs.akool.com/authentication/usage#get-the-token) |
**Path Attributes**
| **Parameter** | **Type** | **Required** | **Value** | **Description** |
| ------------- | -------- | ------------ | --------- | ------------------------------------------------------------------------------------------------------------------ |
| \_id | String | true | | Voice result document ID [getVoiceResultId](https://docs.akool.com/ai-tools-suite/voiceLab#get-voice-results-list) |
**Response Attributes**
| **Parameter** | **Type** | **Value** | **Description** |
| ------------------- | -------- | -------------------------------------------------------- | --------------------------------------------------------- |
| - code | Integer | 1000
| API returns status code(1000:success) |
| - msg | String | | API returns status message |
| - data | Object | | Response data object |
| - result | Object | | Voice result object |
| - \_id | String | "688afbd9d2b4b269d1123ffb"
| Document ID |
| - create\_time | Long | 1753938905005
| Creation timestamp |
| - update\_time | Long | 0
| Update timestamp |
| - uid | Integer | 101400
| User ID |
| - team\_id | String | "6805fb69e92d9edc7ca0b409"
| Team ID |
| - input\_text | String | "Życie jak wspinaczka górska..." | Input text content |
| - rate | String | "100%"
| Processing rate |
| - status | Integer | 1
| Status: 【1:queueing, 2:processing, 3:completed, 4:failed】 |
| - webhookUrl | String | ""
| Callback URL |
| - duration | Integer | 0
| Audio duration in milliseconds |
| - file\_name | String | "1753938905005.mp3"
| File name |
| - gender | String | "Male"
| Voice gender |
| - deduction\_credit | Float | 0.5148
| Deducted credits |
| - name | String | "26ca668a9eb448b7b9a3806fa86207f3"
| Resource name |
| - priority | Integer | 2
| Priority level |
| - language\_code | String | "pt"
| Language code |
| - \_\_v | Integer | 0
| Version number |
| - preview | String | null
| Preview audio URL |
### Example
**Request**
```bash cURL
curl --location 'https://openapi.akool.com/api/open/v4/voice/resource/detail/688afbd9d2b4b269d1123ffb' \
--header 'Authorization: Bearer {{token}}'
```
```java Java
OkHttpClient client = new OkHttpClient().newBuilder()
.build();
MediaType mediaType = MediaType.parse("text/plain");
RequestBody body = RequestBody.create(mediaType, "");
Request request = new Request.Builder()
.url("https://openapi.akool.com/api/open/v4/voice/resource/detail/688afbd9d2b4b269d1123ffb")
.method("GET", body)
.addHeader("Authorization", "Bearer {{token}}")
.build();
Response response = client.newCall(request).execute();
```
```js Javascript
const myHeaders = new Headers();
myHeaders.append("Authorization", "Bearer {{token}}");
const requestOptions = {
method: "GET",
headers: myHeaders,
redirect: "follow"
};
fetch("https://openapi.akool.com/api/open/v4/voice/resource/detail/688afbd9d2b4b269d1123ffb", requestOptions)
.then((response) => response.text())
.then((result) => console.log(result))
.catch((error) => console.error(error));
```
```php PHP
'Bearer {{token}}'
];
$request = new Request('GET', 'https://openapi.akool.com/api/open/v4/voice/resource/detail/688afbd9d2b4b269d1123ffb', $headers);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();
?>
```
```python Python
import requests
url = "https://openapi.akool.com/api/open/v4/voice/resource/detail/688afbd9d2b4b269d1123ffb"
payload = {}
headers = {
'Authorization': 'Bearer {{token}}'
}
response = requests.request("GET", url, headers=headers, data=payload)
print(response.text)
```
**Response**
```json
{
"code": 1000,
"msg": "OK",
"data": {
"result": {
"_id": "688afbd9d2b4b269d1123ffb",
"create_time": 1753938905005,
"update_time": 0,
"uid": 101400,
"team_id": "6805fb69e92d9edc7ca0b409",
"input_text": "Życie jak wspinaczka górska: ważniejsza od wysokości szczytu jest postawa, z jaką się wspinasz. Gdy czujesz, że stopy",
"rate": "100%",
"status": 1,
"webhookUrl": "",
"duration": 0,
"file_name": "1753938905005.mp3",
"gender": "Male",
"deduction_credit": 0.5148,
"name": "26ca668a9eb448b7b9a3806fa86207f3",
"priority": 2,
"language_code": "pt",
"__v": 0,
"preview": null
}
}
}
```
# Webhook
Source: https://docstest.akool.io/ai-tools-suite/webhook
**A webhook is an HTTP-based callback function that allows lightweight, event-driven communication between 2 application programming interfaces (APIs). Webhooks are used by a wide variety of web apps to receive small amounts of data from other apps。**
**Response Data(That is the response data that webhookUrl in the request parameter needs to give us)**
If success, http statusCode it must be 200
* **statusCode** is the http status of response to your request . If success,it must be **200**. If you do not return a status code value of 200, we will retry the response to your webhook address.
**Response Data(The response result we give to the webhookUrl)**
**Content-Type: application/json**
**Response Attributes**
| **Parameter** | **Type** | **Value** | **Description** |
| ------------- | -------- | --------- | ------------------------------------------------------------------------------------------------ |
| signature | String | | message body signature: signature =sha1(sort(clientId、timestamp、nonce, dataEncrypt)) |
| dataEncrypt | String | | message body encryption, need decryption processing is required to obtain the real response data |
| timestamp | Number | | |
| nonce | String | | |
```json
{
"signature": "04e30dd43d9d8f95dd7c127dad617f0929d61c1d",
"dataEncrypt": "LuG1OVSVIwOO/xpW00eSYo77Ncxa9h4VKmOJRjwoyoAmCIS/8FdJRJ+BpZn90BVAAg8xpU1bMmcDlAYDT010Wa9tNi1jivX25Ld03iA4EKs=",
"timestamp": 1710757981609,
"nonce": "1529"
}
```
When we complete the signature checksum and dataEncrypt decryption, we can get the real response content.
The decrypted content of dataEncrypt is:
| **Parameter** | **Type** | **Value** | **Description** |
| ------------- | -------- | -------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| \_id | String | | \_id: returned by each interface |
| status | Number | 2 or 3 or 4 | status: the status of image or video or faceswap or background change or avatar or audio： 【1:queueing, 2:processing,3:completed, 4:failed】 |
| type | String | faceswap or image or audio or talking photo or video translate or background change or avatar or lipsync | Distinguish the type of each interface |
| url | String | | when staus = 3, the url is the final result about audio, image, and video. |
**Next, we will introduce the process and methods of encryption and decryption.**
### Encryption and Decryption technology solution
The encryption and decryption technical solution is implemented based on the AES encryption and decryption algorithm, as follows:
1. clientSecret: This is the message encryption and decryption Key. The length is fixed at 24 characters. ClientSecret is used as the encryption key.
2. AES adopts CBC mode, the secret key length is 24 bytes (192 bits), and the data is filled with PKCS#7; PKCS#7: K is the number of bytes of the secret key (24 is used), Buf is the content to be encrypted, N is its number of bytes. Buf needs to be filled to an integer multiple of K. Fill (K - N%K) bytes at the end of Buf, and the content of each byte is (K - N%K).
3. The IV length of AES is 16 bytes, and clientId is used as the IV.
**Message body encryption**
dataEncrypt is the result of the platform encrypting the message as follows:
* dataEncrypt = AES\_Encrypt( data, clientId, clientSecret )
Among them, data is the body content we need to transmit, clientId is the initial vector, and clientSecret is the encryption key.
**Message body signature**
In order to verify the legitimacy of the message body, developers can verify the authenticity of the message body and decrypt the message body that passes the verification.
Specific method: dataSignature=sha1(sort(clientId、timestamp、nonce, dataEncrypt))
| **Parameter** | **Description** |
| ------------- | ---------------------------------------------------------- |
| clientId | clientId of user key pair |
| timestamp | timestamp in body |
| nonce | nonce in body |
| dataEncrypt | The previous article describes the ciphertext message body |
**Message body verification and decryption**
The developer first verifies the correctness of the message body signature, and then decrypts the message body after passing the verification.
**Ways of identifying:**
1. The developer calculates the signature,compareSignature=sha1(sort(clientId、timestamp、nonce, dataEncrypt))
2. Compare compareSignature and the signature in the body to see if they are equal. If they are equal, the verification is passed.
The decryption method is as follows:
* data = AES\_Decrypt(dataEncrypt, clientSecret);
**Example: Encryption and Decryption**
1. To use nodejs or python or java for encryption.
```javascript Nodejs
// To use nodejs for encryption, you need to install crypto-js. Use the command npm install crypto-js to install it.
const CryptoJS = require('crypto-js')
const crypto = require('crypto');
// Generate signature
function generateMsgSignature(clientId, timestamp, nonce, msgEncrypt){
const sortedStr = [clientId, timestamp, nonce, msgEncrypt].sort().join('');
const hash = crypto.createHash('sha1').update(sortedStr).digest('hex');
return hash;
}
// decryption algorithm
function generateAesDecrypt(dataEncrypt,clientId,clientSecret){
const aesKey = clientSecret
const key = CryptoJS.enc.Utf8.parse(aesKey)
const iv = CryptoJS.enc.Utf8.parse(clientId)
const decrypted = CryptoJS.AES.decrypt(dataEncrypt, key, {
iv: iv,
mode: CryptoJS.mode.CBC,
padding: CryptoJS.pad.Pkcs7
})
return decrypted.toString(CryptoJS.enc.Utf8)
}
// Encryption Algorithm
function generateAesEncrypt(data,clientId,clientSecret){
const aesKey = clientSecret
const key = CryptoJS.enc.Utf8.parse(aesKey)
const iv = CryptoJS.enc.Utf8.parse(clientId)
const srcs = CryptoJS.enc.Utf8.parse(data)
// CBC encryption method, Pkcs7 padding method
const encrypted = CryptoJS.AES.encrypt(srcs, key, {
iv: iv,
mode: CryptoJS.mode.CBC,
padding: CryptoJS.pad.Pkcs7
})
return encrypted.toString()
}
```
```python Python
from hashlib import sha1
from Crypto.Cipher import AES
from Crypto.Util.Padding import pad, unpad
from Crypto.Random import get_random_bytes
# Generate signature
def generate_msg_signature(client_id, timestamp, nonce, msg_encrypt):
sorted_str = ''.join(sorted([client_id, timestamp, nonce, msg_encrypt]))
hash_obj = sha1(sorted_str.encode())
return hash_obj.hexdigest()
# Decryption algorithm
def generate_aes_decrypt(data_encrypt, client_id, client_secret):
aes_key = client_secret.encode()
iv = client_id.encode()
cipher = AES.new(aes_key, AES.MODE_CBC, iv)
decrypted = unpad(cipher.decrypt(data_encrypt), AES.block_size)
return decrypted.decode()
# Encryption algorithm
def generate_aes_encrypt(data, client_id, client_secret):
aes_key = client_secret.encode()
iv = client_id.encode()
cipher = AES.new(aes_key, AES.MODE_CBC, iv)
padded_data = pad(data.encode(), AES.block_size)
encrypted = cipher.encrypt(padded_data)
return encrypted
```
```java Java
import java.security.MessageDigest;
import javax.crypto.Cipher;
import javax.crypto.spec.IvParameterSpec;
import javax.crypto.spec.SecretKeySpec;
import java.util.Arrays;
import java.nio.charset.StandardCharsets;
import javax.xml.bind.DatatypeConverter;
public class CryptoUtils {
// Generate signature
public static String generateMsgSignature(String clientId, String timestamp, String nonce, String msgEncrypt) {
String[] arr = {clientId, timestamp, nonce, msgEncrypt};
Arrays.sort(arr);
String sortedStr = String.join("", arr);
return sha1(sortedStr);
}
// SHA-1 hash function
private static String sha1(String input) {
try {
MessageDigest md = MessageDigest.getInstance("SHA-1");
byte[] hashBytes = md.digest(input.getBytes(StandardCharsets.UTF_8));
return DatatypeConverter.printHexBinary(hashBytes).toLowerCase();
} catch (Exception e) {
e.printStackTrace();
return null;
}
}
// Decryption algorithm
public static String generateAesDecrypt(String dataEncrypt, String clientId, String clientSecret) {
try {
byte[] keyBytes = clientSecret.getBytes(StandardCharsets.UTF_8);
byte[] ivBytes = clientId.getBytes(StandardCharsets.UTF_8);
SecretKeySpec keySpec = new SecretKeySpec(keyBytes, "AES");
IvParameterSpec ivSpec = new IvParameterSpec(ivBytes);
Cipher cipher = Cipher.getInstance("AES/CBC/PKCS5Padding");
cipher.init(Cipher.DECRYPT_MODE, keySpec, ivSpec);
byte[] encryptedBytes = DatatypeConverter.parseHexBinary(dataEncrypt);
byte[] decryptedBytes = cipher.doFinal(encryptedBytes);
return new String(decryptedBytes, StandardCharsets.UTF_8);
} catch (Exception e) {
e.printStackTrace();
return null;
}
}
// Encryption algorithm
public static String generateAesEncrypt(String data, String clientId, String clientSecret) {
try {
byte[] keyBytes = clientSecret.getBytes(StandardCharsets.UTF_8);
byte[] ivBytes = clientId.getBytes(StandardCharsets.UTF_8);
SecretKeySpec keySpec = new SecretKeySpec(keyBytes, "AES");
IvParameterSpec ivSpec = new IvParameterSpec(ivBytes);
Cipher cipher = Cipher.getInstance("AES/CBC/PKCS5Padding");
cipher.init(Cipher.ENCRYPT_MODE, keySpec, ivSpec);
byte[] encryptedBytes = cipher.doFinal(data.getBytes(StandardCharsets.UTF_8));
return DatatypeConverter.printHexBinary(encryptedBytes).toLowerCase();
} catch (Exception e) {
e.printStackTrace();
return null;
}
}
// Example usage
public static void main(String[] args) {
String clientId = "your_client_id";
String clientSecret = "your_client_secret";
String timestamp = "your_timestamp";
String nonce = "your_nonce";
String msgEncrypt = "your_encrypted_message";
// Generate signature
String signature = generateMsgSignature(clientId, timestamp, nonce, msgEncrypt);
System.out.println("Signature: " + signature);
// Encryption
String data = "your_data_to_encrypt";
String encryptedData = generateAesEncrypt(data, clientId, clientSecret);
System.out.println("Encrypted Data: " + encryptedData);
// Decryption
String decryptedData = generateAesDecrypt(encryptedData, clientId, clientSecret);
System.out.println("Decrypted Data: " + decryptedData);
}
}
```
2. Assume that our webhookUrl has obtained the corresponding data, such as the following corresponding data
```json
{
"signature": "04e30dd43d9d8f95dd7c127dad617f0929d61c1d",
"dataEncrypt": "LuG1OVSVIwOO/xpW00eSYo77Ncxa9h4VKmOJRjwoyoAmCIS/8FdJRJ+BpZn90BVAAg8xpU1bMmcDlAYDT010Wa9tNi1jivX25Ld03iA4EKs=",
"timestamp": 1710757981609,
"nonce": 1529
}
```
3. To verify the correctness of the signature and decrypt the content, clientId and clientSecret are required.
```javascript Nodejs
// express example
const obj = {
"signature": "04e30dd43d9d8f95dd7c127dad617f0929d61c1d",
"dataEncrypt": "LuG1OVSVIwOO/xpW00eSYo77Ncxa9h4VKmOJRjwoyoAmCIS/8FdJRJ+BpZn90BVAAg8xpU1bMmcDlAYDT010Wa9tNi1jivX25Ld03iA4EKs=",
"timestamp": 1710757981609,
"nonce": 1529
}
let clientId = "AKDt8rWEczpYPzCGur2xE="
let clientSecret = "nmwUjMAK0PJpl0MOiXLOOOwZADm0gkLo"
let signature = obj.signature
let msg_encrypt = obj.dataEncrypt
let timestamp = obj.timestamp
let nonce = obj.nonce
let newSignature = generateMsgSignature(clientId,timestamp,nonce,msg_encrypt)
if (signature===newSignature) {
let result = generateAesDecrypt(msg_encrypt,clientId,clientSecret)
// Handle your own business logic
response.status(200).json({}) // If the processing is successful,http statusCode:200 must be returned.
}else {
response.status(400).json({})
}
```
```python Python
import hashlib
from Crypto.Cipher import AES
from Crypto.Util.Padding import unpad
import base64
# Generate signature
def generate_msg_signature(client_id, timestamp, nonce, msg_encrypt):
sorted_str = ''.join(sorted([client_id, str(timestamp), str(nonce), msg_encrypt]))
hash_obj = hashlib.sha1(sorted_str.encode())
return hash_obj.hexdigest()
# Decryption algorithm
def generate_aes_decrypt(data_encrypt, client_id, client_secret):
aes_key = client_secret.encode()
iv = client_id.encode()
cipher = AES.new(aes_key, AES.MODE_CBC, iv)
decrypted = unpad(cipher.decrypt(base64.b64decode(data_encrypt)), AES.block_size)
return decrypted.decode()
# Example usage
if __name__ == "__main__":
obj = {
"signature": "04e30dd43d9d8f95dd7c127dad617f0929d61c1d",
"dataEncrypt": "LuG1OVSVIwOO/xpW00eSYo77Ncxa9h4VKmOJRjwoyoAmCIS/8FdJRJ+BpZn90BVAAg8xpU1bMmcDlAYDT010Wa9tNi1jivX25Ld03iA4EKs=",
"timestamp": 1710757981609,
"nonce": 1529
}
clientId = "AKDt8rWEczpYPzCGur2xE="
clientSecret = "nmwUjMAK0PJpl0MOiXLOOOwZADm0gkLo"
signature = obj["signature"]
msg_encrypt = obj["dataEncrypt"]
timestamp = obj["timestamp"]
nonce = obj["nonce"]
new_signature = generate_msg_signature(clientId, timestamp, nonce, msg_encrypt)
if signature == new_signature:
result = generate_aes_decrypt(msg_encrypt, clientId, clientSecret)
# Handle your own business logic
print("Decrypted Data:", result)
# Return success http satusCode 200
else:
# Return error http statuCode 400
```
```java Java
import java.security.MessageDigest;
import java.util.Arrays;
import javax.crypto.Cipher;
import javax.crypto.spec.IvParameterSpec;
import javax.crypto.spec.SecretKeySpec;
import java.util.Base64;
public class CryptoUtils {
// Generate signature
public static String generateMsgSignature(String clientId, long timestamp, int nonce, String msgEncrypt) {
String[] arr = {clientId, String.valueOf(timestamp), String.valueOf(nonce), msgEncrypt};
Arrays.sort(arr);
String sortedStr = String.join("", arr);
return sha1(sortedStr);
}
// SHA-1 hash function
private static String sha1(String input) {
try {
MessageDigest md = MessageDigest.getInstance("SHA-1");
byte[] hashBytes = md.digest(input.getBytes());
StringBuilder hexString = new StringBuilder();
for (byte b : hashBytes) {
String hex = Integer.toHexString(0xff & b);
if (hex.length() == 1) hexString.append('0');
hexString.append(hex);
}
return hexString.toString();
} catch (Exception e) {
e.printStackTrace();
return null;
}
}
// Decryption algorithm
public static String generateAesDecrypt(String dataEncrypt, String clientId, String clientSecret) {
try {
byte[] keyBytes = clientSecret.getBytes();
byte[] ivBytes = clientId.getBytes();
SecretKeySpec keySpec = new SecretKeySpec(keyBytes, "AES");
IvParameterSpec ivSpec = new IvParameterSpec(ivBytes);
Cipher cipher = Cipher.getInstance("AES/CBC/PKCS5Padding");
cipher.init(Cipher.DECRYPT_MODE, keySpec, ivSpec);
byte[] encryptedBytes = Base64.getDecoder().decode(dataEncrypt);
byte[] decryptedBytes = cipher.doFinal(encryptedBytes);
return new String(decryptedBytes);
} catch (Exception e) {
e.printStackTrace();
return null;
}
}
// Example usage
public static void main(String[] args) {
String clientId = "AKDt8rWEczpYPzCGur2xE=";
String clientSecret = "nmwUjMAK0PJpl0MOiXLOOOwZADm0gkLo";
String signature = "04e30dd43d9d8f95dd7c127dad617f0929d61c1d";
String msgEncrypt = "LuG1OVSVIwOO/xpW00eSYo77Ncxa9h4VKmOJRjwoyoAmCIS/8FdJRJ+BpZn90BVAAg8xpU1bMmcDlAYDT010Wa9tNi1jivX25Ld03iA4EKs=";
long timestamp = 1710757981609L;
int nonce = 1529;
String newSignature = generateMsgSignature(clientId, timestamp, nonce, msgEncrypt);
if (signature.equals(newSignature)) {
String result = generateAesDecrypt(msgEncrypt, clientId, clientSecret);
// Handle your own business logic
System.out.println("Decrypted Data: " + result);
// must be Return success http satusCode 200
} else {
// must be Return error http satusCode 400
}
}
}
```
# Usage
Source: https://docstest.akool.io/authentication/usage
### Overview
OpenAPI uses API keys for authentication. Get your API token from our API interfaces . We provide open APIs for Gen AI Platform by clicking on the top API button on this page [openAPI](https://akool.com/openapi).
* First you need to login to our website.
* Then click the picture icon in the upper right corner of the website, and click the "APl Credentials" function to set the key pair (clientId, clientSecret) used when accessing the API and save it.
* Use the secret key pair just saved to send the api interface to obtain the access token.
### API
#### Get the token
```
POST https://openapi.akool.com/api/open/v3/getToken
```
**Body Attributes**
| **Parameter** | **Description** |
| ------------- | --------------------------------------- |
| clientId | Used for request creation authorization |
| clientSecret | Used for request creation authorization |
**Response Attributes**
| **Parameter** | **Value** | **Description** |
| ------------- | --------- | ---------------------------------------------------- |
| code | 1000 | Interface returns business status code(1000:success) |
| token | | API token |
Please note that the generated token is valid for more than 1 year.
#### Example
**Body**
```json
{
"clientId": "64db241f6d9e5c4bd136c187",
"clientSecret": "openapi.akool.com"
}
```
**Request**
```bash cURL
curl --location 'https://openapi.akool.com/api/open/v3/getToken' \
--header 'Content-Type: application/json' \
--data '{
"clientId": "64db241f6d9e5c4bd136c187",
"clientSecret": "openapi.akool.com"
}'
```
```java Java
OkHttpClient client = new OkHttpClient().newBuilder()
.build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\r\n \"clientId\": \"64db241f6d9e5c4bd136c187\",\r\n \"clientSecret\": \"openapi.akool.com\"\r\n}");
Request request = new Request.Builder()
.url("https://openapi.akool.com/api/open/v3/getToken")
.method("POST", body)
.addHeader("Content-Type", "application/json")
.build();
Response response = client.newCall(request).execute();
```
```javascript Javascript
const myHeaders = new Headers();
myHeaders.append("Content-Type", "application/json");
const raw = JSON.stringify({
"clientId": "64db241f6d9e5c4bd136c187",
"clientSecret": "openapi.akool.com"
});
const requestOptions = {
method: "POST",
headers: myHeaders,
body: raw,
redirect: "follow"
};
fetch("https://openapi.akool.com/api/open/v3/getToken", requestOptions)
.then((response) => response.text())
.then((result) => console.log(result))
.catch((error) => console.error(error));
```
```PHP PHP
'application/json'
];
$body = '{
"clientId": "64db241f6d9e5c4bd136c187",
"clientSecret": "openapi.akool.com"
}';
$request = new Request('POST', 'https://openapi.akool.com/api/open/v3/getToken', $headers, $body);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();
```
```python Python
import requests
import json
url = "https://openapi.akool.com/api/open/v3/getToken"
payload = json.dumps({
"clientId": "64db241f6d9e5c4bd136c187",
"clientSecret": "openapi.akool.com"
})
headers = {
'Content-Type': 'application/json'
}
response = requests.request("POST", url, headers=headers, data=payload)
print(response.text)
```
**Response**
```json
{
"code": 1000,
"token": "xxxxxxxxxxxxxxxx"
}
```
All API requests should include your API token in the HTTP header,
Authorization looks like this:
```
Authorization: Bearer token
```
Remember, your API token is secret! Do not share it with others or
expose it in any client-side code (browser, application). Production
requests must be routed through your own backend server, and your API
token can be securely loaded from environment variables or a key
management service.
**Response Code Description**
Please note that if the value of the response code is not equal to 1000, the request is failed or wrong
| **Parameter** | **Value** | **Description** |
| ------------- | --------- | ------------------------------------------------------ |
| code | 1000 | Success |
| code | 1101 | Invalid authorization or The request token has expired |
| code | 1102 | Authorization cannot be empty |
| code | 1200 | The account has been banned |