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.

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
- 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
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
Then, you need to generate an avatar video by calling the API Create Avatar Video
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

Get Avatar List

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. You can get from https://openapi.akool.com/api/open/v3/getToken api.

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.
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

Response

{
  "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": []
    }
  ]
}

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. You can get from https://openapi.akool.com/api/open/v3/getToken api.

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

Response

{
  "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 Avatar

GET https://openapi.akool.com/api/open/v3/avatar/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 api.

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/.
type	String	1，2	Avatar type, 1 represents real avatar, 2 represents stream avatar, When type is 2, you need to wait until status is 3 before you can use it, You can get the current status in real time through the interface https://openapi.akool.com/api/open/v3/avatar/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	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

Response

{
  "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": []
    }
  ]
}

Create Avatar Video

POST https://openapi.akool.com/api/open/v3/avatar/createVideo

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 api.

Body Attributes

Parameter	Type	Value	Description
data	[Object]
[data].width	Number	1920	Set the output video width
[data].height	Number	1080	Set the output video height
[data].duration	Number		Set the output video duration (in milliseconds)
[data].voice	Object		Set Video Sound
[data].voice.voice_url	String		When you want to use the specified audio for cloning, you first need to call https://openapi.akool.com/api/open/v3/audio/create API for audio cloning, you will obtain the field 【url】 and pass it here
[data].elements	[Object]		Collection of elements passed in in the video
[data].[elements].url	[Object]		Link to element
[data].[elements].scale_x	[Object]		Horizontal scaling ratio, range of values (0-1)
[data].[elements].scale_y	[Object]		Vertical scaling ratio, range of values (0-1)
[data].[elements].offset_x	[Object]		Horizontal offset of the upper left corner of the element from the video setting area (in pixels)
[data].[elements].offset_y	[Object]		Vertical offset of the upper left corner of the element from the video setting area (in pixels)
[data].[elements].type	[Object]		Element type（avatar、image、video）
[data].[elements].layer_number	Number		Element hierarchy, with higher levels displayed above
[data].[elements].avatar_id	Number		You use the avatar_id of the avatar model, and you can get from https://openapi.akool.com/api/open/v3/avatar/list api, you will obtain the field 【avatar_id】 and pass it here
[data].[elements].url	String		You can provide image or video url resources
[data].ratio	String		Video ratio，default “16:9”
[data].background	String		Video background color, default white (# ffffff)
[data].avatarFrom	Number		You use the avatar from of the avatar model, and you can get from https://openapi.akool.com/api/open/v3/avatar/list api, you will obtain the field 【from】 and pass it here
duration	Number		Generate the total duration of the video, which defaults to the sum of the durations in the array sub-items (in milliseconds)
webhookUrl	String		Callback url address based on HTTP request.

voice_id and voice_url must provide one

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

{
  "data": [
    {
      "width": 1920,
      "height": 1080,
      "duration": 18938.75,
      "voice": {
        "voice_url": "https://drz0f01yeq1cx.cloudfront.net/1712113284451-fe73dd6c-f981-46df-ba73-0b9d85c1be9c-8195.mp3"
      },
      "elements": [
        {
          "url": "https://d11fbe263bhqij.cloudfront.net/agicontent/avatar/elements/landscape_furniture1.png",
          "scale_x": 1,
          "scale_y": 1,
          "offset_x": 960,
          "offset_y": 540,
          "type": "image",
          "layer_number": 1
        },
        {
          "id": "avatar",
          "url": "https://drz0f01yeq1cx.cloudfront.net/avatar/thumbnail/1700786295159-e450163c-7b50-4714-9763-ed7a0e09d8b2-8298.png",
          "scale_x": 1,
          "scale_y": 1,
          "offset_x": 1380,
          "offset_y": 540,
          "type": "avatar",
          "avatar_id": "Barbara_in_Black_suit_20231121",
          "layer_number": 3
        }
      ],
      "ratio": "16:9",
      "background": "#ffffff",
      "avatarFrom": 3
    }
  ],
  "webhookUrl": "http://localhost:3007/api/open/v3/test/webhook"
}

Request

Response

{
  "code": 1000, // API code
  "msg": "OK",
  "data": {
    "create_time": 1712048827995,
    "uid": 100004,
    "type": 4,
    "from": 2,
    "ratio": "16:9",
    "background": "",
    "offset_x": 0,
    "offset_y": 0,
    "scale": 1,
    "faceswap_quality": 2,
    "video_sub_status": 1,
    "video_status": 1,
    "video_lock_duration": 1515,
    "deduction_lock_duration": 1520,
    "external_video": "",
    "video": "",
    "storage_loc": 1,
    "source_data": {
      "data": [{
        "width": 1920,
        "height": 1080,
        "duration": 18938.75,
        "voice": {
          "voice_url": "https://drz0f01yeq1cx.cloudfront.net/1712113284451-fe73dd6c-f981-46df-ba73-0b9d85c1be9c-8195.mp3"
        },
        "elements": [
          {
            "url": "https://d11fbe263bhqij.cloudfront.net/agicontent/avatar/elements/landscape_furniture1.png",
            "scale_x": 1,
            "scale_y": 1,
            "offset_x": 960,
            "offset_y": 540,
            "type": "image",
            "layer_number": 1
          },
          {
            "id": "avatar",
            "url": "https://drz0f01yeq1cx.cloudfront.net/avatar/thumbnail/1700786295159-e450163c-7b50-4714-9763-ed7a0e09d8b2-8298.png",
            "scale_x": 1,
            "scale_y": 1,
            "offset_x": 1380,
            "offset_y": 540,
            "type": "avatar",
            "avatar_id": "Barbara_in_Black_suit_20231121",
            "layer_number": 3
          }
        ],
        "ratio": "16:9",
        "background": "#ffffff",
        "avatarFrom": 3
      }],
      "webhookUrl":"http://localhost:3007/api/open/v3/test/webhook"
      "userId": "64ddd5fa3a458a183f71f665"
    },
    "_id": "660bcabb6e2f6d2bba67f1fd",
    "__v": 0
  }
}

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. You can get from https://open.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/avatar/createVideo .

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

Response

{
  "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": "",
    "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	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

Authentication

AI Tools Suite

Description

Get Avatar List

Get Avatar Detail

Upload Avatar

Create Avatar Video

Get Video Info

Authentication

AI Tools Suite

​Description

​Get Avatar List

​Get Avatar Detail

​Upload Avatar

​Create Avatar Video

​Get Video Info

Description

Get Avatar List

Get Avatar Detail

Upload Avatar

Create Avatar Video

Get Video Info