Skip to main content
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
ParameterValueDescription
x-api-keyAPI KeyYour API Key used for request authorization. If both Authorization and x-api-key have values, Authorization will be used first and x-api-key will be discarded.
AuthorizationBearer tokenYour API Key used for request authorization. You can get from https://openapi.akool.com/api/open/v3/getToken api.
Query Attributes
ParameterTypeValueDescription
fromNumber2、32 represents the official avatar of Akool, 3 represents the avatar uploaded by the user themselves，If empty, returns all avatars by default.
pageNumber1Current number of pages，Default is 1.
sizeNumber10Current number of returns per page，Default is 100.
Response Attributes
ParameterTypeValueDescription
codeint1000Interface returns business status code(1000:success)
msgStringOKInterface returns status information
dataArray[{ 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 
curl --location 'https://openapi.akool.com/api/open/v3/avatar/list?from=2&page=1&size=100' \
--header 'x-api-key: {{API Key}}'
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
ParameterValueDescription
x-api-keyAPI KeyYour API Key used for request authorization. If both Authorization and x-api-key have values, Authorization will be used first and x-api-key will be discarded.
AuthorizationBearer tokenYour API Key used for request authorization. You can get from https://openapi.akool.com/api/open/v3/getToken api.
Query Attributes
ParameterTypeValueDescription
idStringavatar record id.
Response Attributes
ParameterTypeValueDescription
codeint1000Interface returns business status code(1000:success)
msgStringOKInterface returns status information
dataArray[{ 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 
curl --location 'https://openapi.akool.com/api/open/v3/avatar/detail?id=66a1a02d591ad336275eda62' \
--header 'x-api-key: {{API Key}}'
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

POST https://openapi.akool.com/api/open/v3/avatar/create
Request Headers
ParameterValueDescription
x-api-keyAPI KeyYour API Key used for request authorization. If both Authorization and x-api-key have values, Authorization will be used first and x-api-key will be discarded.
AuthorizationBearer tokenYour API Key used for request authorization. You can get from https://openapi.akool.com/api/open/v3/getToken api.
Body Attributes
ParameterTypeValueDescription
urlStringAvatar 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_idStringavatar unique ID，Can only contain /^a-zA-Z0-9/.
nameStringAvatar display name for easier identification and management.
typeNumber1，2Avatar 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.
url_fromNumber1，2url source, 1 means akool and other links, 2 means other third-party links (currently only supports YouTube / TikTok / X / Google Drive)
Response Attributes
ParameterTypeValueDescription
codeint1000Interface returns business status code(1000:success)
msgStringOKInterface returns status information
dataArray[{ 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 
curl --location 'https://openapi.akool.com/api/open/v3/avatar/create' \
--header 'x-api-key: {{API Key}}' \
--header 'Content-Type: application/json' \
--data '{
  "url": "https://drz0f01yeq1cx.cloudfront.net/1721197444322-leijun000.mp4",
  "avatar_id": "HHdEKhn7k7vVBlR5FSi0e",
  "name": "My Custom Avatar",
  "type": 1,
  "url_from": 1
}'
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
ParameterValueDescription
x-api-keyAPI KeyYour API Key used for request authorization. If both Authorization and x-api-key have values, Authorization will be used first and x-api-key will be discarded.
AuthorizationBearer tokenYour API Key used for request authorization. You can get from https://openapi.akool.com/api/open/v3/getToken api.
Body Attributes
ParameterTypeValueDescription
data[Object]
[data].widthNumber1920Set the output video width
[data].heightNumber1080Set the output video height
[data].durationNumberSet the output video duration (in milliseconds)
[data].voiceObjectSet Video Sound
[data].voice.voice_urlStringWhen 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_numberNumberElement hierarchy, with higher levels displayed above
[data].[elements].avatar_idNumberYou use the avatar_id of the avatar model, and you can get from Avatar list V3 api, you will obtain the field 【avatar_id】 and pass it here
[data].[elements].urlStringYou can provide image or video url resources
[data].ratioStringVideo ratio，default “16:9”
[data].backgroundStringVideo background color, default white (# ffffff)
[data].avatarFromNumberYou use the avatar from of the avatar model, and you can get from Avatar list V3 api, you will obtain the field 【from】 and pass it here
durationNumberGenerate the total duration of the video, which defaults to the sum of the durations in the array sub-items (in milliseconds)
webhookUrlStringCallback url address based on HTTP request.
voice_id and voice_url must provide one
Response Attributes
ParameterTypeValueDescription
codeint1000Interface returns business status code (1000:success)
msgStringInterface returns status information
dataObject{ _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": ""
}
Request 
curl --location 'https://openapi.akool.com/api/open/v3/avatar/createVideo' \
--header "x-api-key: {{API Key}}" \
--header 'Content-Type: application/json' \
--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":""
}'
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":""
      "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
ParameterValueDescription
x-api-keyAPI KeyYour API Key used for request authorization. If both Authorization and x-api-key have values, Authorization will be used first and x-api-key will be discarded.
AuthorizationBearer tokenYour API Key used for request authorization. You can get from https://open.akool.com/api/open/v3/getToken api.
Query Attributes
ParameterTypeValueDescription
video_model_idStringNULLvideo db id: You can get it based on the _id field returned by https://openapi.akool.com/api/open/v3/avatar/createVideo .
Response Attributes
ParameterTypeValueDescription
codeint1000Interface returns business status code(1000:success)
msgStringOKInterface returns status information
dataObject{ 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 
curl --location 'https://openapi.akool.com/api/open/v3/content/video/infobymodelid?video_model_id=64b126c4a680e8edea44f02b' \
--header "x-api-key: {{API Key}}"
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
ParameterValueDescription
code1000Success
code1003Parameter error or Parameter can not be empty
code1006Your quota is not enough
code1109create avatar video error
code1102Authorization cannot be empty
code1200The account has been banned
code1201Create audio error, please try again later