# Audio Source: https://docs.akool.com/ai-tools-suite/audio Audio API documentation You can use the following API to generate tts voice and voice clones. 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. ### Get Voice List Result ``` GET https://openapi.akool.com/api/open/v3/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** | **Value** | **Description** | | ------------- | -------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | from | Number | 3, 4 | 3 represents the official voice of Akool, 4 represents the voice created by the user themselves，If empty, returns all voice by office and users. | **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 | `[{ voice_id: "xx", preview: "" }]` | voice\_id: Used by talking photo interface and creating audio interface. preview: You can preview the voice via the link. | **Example** **Request** ```bash cURL curl --location 'https://openapi.akool.com/api/open/v3/voice/list?from=3' \ --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/voice/list?from=3") .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/voice/list?from=3", 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/voice/list?from=3', $headers); $res = $client->sendAsync($request)->wait(); echo $res->getBody(); ``` ```python Python import requests url = "https://openapi.akool.com/api/open/v3/voice/list?from=3" 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": "65e980d7af040969db5be863", "create_time": 1687181385319, "uid": 1, "from": 3, "voice_id": "piTKgcLEGmPE4e6mEKli", "gender": "Female", "accent":"american", "name": "Nicole", "description":"whisper", "useCase":"audiobook", "type": 1, "preview": "https://storage.googleapis.com/eleven-public-prod/premade/voices/piTKgcLEGmPE4e6mEKli/c269a54a-e2bc-44d0-bb46-4ed2666d6340.mp3", "__v": 0 } ] } ``` ### Create TTS ``` POST https://openapi.akool.com/api/open/v3/audio/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** | | ------------- | -------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | input\_text | String | | Enter what talkingphoto to say | | voice\_id | String | | Voice id: get from [https://openapi.akool.com/api/open/v3/voice/list](https://docs.akool.com/ai-tools-suite/audio#get-voice-list-result) api，the field is 【voice\_id】 | | rate | String | | Voice speaking speed【field value ranges（0%-100%）】 | | 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: "", status: 1 }` | \_id: Interface returns data, status: the status of audio: 【1:queueing, 2:processing, 3:completed, 4:failed】 | **Example** **Body** ```json { "input_text": "Choose from male and female voices for various use-cases. For tailored options, refer to voice settings or read further.There are both male and female voices to choose from", "voice_id": "LcfcDJNUP1GQjkzn1xUU", "rate": "100%", "webhookUrl":"http://localhost:3007/api/open/v3/test/webhook" } ``` **Request** ```bash cURL curl --location 'https://openapi.akool.com/api/open/v3/audio/create' \ --header 'authorization: Bearer token' \ --header 'Content-Type: application/json' \ --data '{ "input_text": "Choose from male and female voices for various use-cases. For tailored options, refer to voice settings or read further.There are both male and female voices to choose from", "voice_id": "LcfcDJNUP1GQjkzn1xUU", "rate": "100%", "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 \"input_text\": \"Choose from male and female voices for various use-cases. For tailored options, refer to voice settings or read further.There are both male and female voices to choose from\",\n \"voice_id\": \"LcfcDJNUP1GQjkzn1xUU\",\n \"rate\": \"100%\",\n \"webhookUrl\":\"http://localhost:3007/api/open/v3/test/webhook\" \n}"); Request request = new Request.Builder() .url("https://openapi.akool.com/api/open/v3/audio/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({ "input_text": "Choose from male and female voices for various use-cases. For tailored options, refer to voice settings or read further.There are both male and female voices to choose from", "voice_id": "LcfcDJNUP1GQjkzn1xUU", "rate": "100%", "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/audio/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 = '{ "input_text": "Choose from male and female voices for various use-cases. For tailored options, refer to voice settings or read further.There are both male and female voices to choose from", "voice_id": "LcfcDJNUP1GQjkzn1xUU", "rate": "100%", "webhookUrl": "http://localhost:3007/api/open/v3/test/webhook" }'; $request = new Request('POST', 'https://openapi.akool.com/api/open/v3/audio/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/audio/create" payload = json.dumps({ "input_text": "Choose from male and female voices for various use-cases. For tailored options, refer to voice settings or read further.There are both male and female voices to choose from", "voice_id": "LcfcDJNUP1GQjkzn1xUU", "rate": "100%", "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, "msg": "OK", "data": { "_id": "65f8017f56559aa67f0ecde7", "create_time": 1710752127995, "uid": 101690, "from": 3, "input_text": "Choose from male and female voices for various use-cases. For tailored options, refer to voice settings or read further.There are both male and female voices to choose from", "rate": "100%", "voice_model_id": "65e980d7af040969db5be854", "url": "https://drz0f01yeq1cx.cloudfront.net/1710752141387-e7867802-0a92-41d4-b899-9bfb23144929-4946.mp3", "status": 3, "__v": 0 } } ``` ### Create Voice Clone ``` POST https://openapi.akool.com/api/open/v3/audio/clone ``` **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 | | Enter what avatar in video to say | | rate | String | true | | Voice speaking speed【field value ranges（0%-100%）】 | | voice\_url | String | false | | Voice url address | | 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: "", status: 1, url:"" }` | \_id: Interface returns data, status: the status of audio: 【1:queueing, 2:processing, 3:completed, 4:failed】, url: Links to the generated audio resources，You can use it in the interface [https://openapi.akool.com/api/open/v3/talkingavatar/create](https://docs.akool.com/ai-tools-suite/talking-avatar#create-talking-avatar) api. | **Example** **Body** ```json { "input_text": "Hello, this is Akool's AI platform!", "rate": "100%", "voice_url":"https://drz0f01yeq1cx.cloudfront.net/1713168740392-4022bc91-5502-4e79-a66a-8c45b31792e4-4867.mp3", "webhookUrl":"http://localhost:3007/api/open/v3/test/webhook" } ``` **Request** ```bash cURL curl --location 'https://openapi.akool.com/api/open/v3/audio/clone' \ --header 'authorization: Bearer token' \ --header 'Content-Type: application/json' \ --data '{ "input_text": "Hello, this is Akool'\''s AI platform!", "rate": "100%", "voice_url":"https://drz0f01yeq1cx.cloudfront.net/1713168740392-4022bc91-5502-4e79-a66a-8c45b31792e4-4867.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 \"input_text\": \"Hello, this is Akool's AI platform!\",\n \"rate\": \"100%\",\n \"voice_url\":\"https://drz0f01yeq1cx.cloudfront.net/1713168740392-4022bc91-5502-4e79-a66a-8c45b31792e4-4867.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/audio/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({ "input_text": "Hello, this is Akool's AI platform!", "rate": "100%", "voice_url": "https://drz0f01yeq1cx.cloudfront.net/1713168740392-4022bc91-5502-4e79-a66a-8c45b31792e4-4867.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/audio/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 = '{ "input_text": "Hello, this is Akool's AI platform!", "rate": "100%", "voice_url": "https://drz0f01yeq1cx.cloudfront.net/1713168740392-4022bc91-5502-4e79-a66a-8c45b31792e4-4867.mp3", "webhookUrl": "http://localhost:3007/api/open/v3/test/webhook" }'; $request = new Request('POST', 'https://openapi.akool.com/api/open/v3/audio/clone', $headers, $body); $res = $client->sendAsync($request)->wait(); echo $res->getBody(); ``` ```python Python import requests import json url = "https://openapi.akool.com/api/open/v3/audio/clone" payload = json.dumps({ "input_text": "Hello, this is Akool's AI platform!", "rate": "100%", "voice_url": "https://drz0f01yeq1cx.cloudfront.net/1713168740392-4022bc91-5502-4e79-a66a-8c45b31792e4-4867.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, "msg": "OK", "data": { "create_time": 1712113285547, "from": 3, "input_text": "Hello, this is Akool's AI platform!", "rate": "100%", "voice_model_id": "65e813955daad44c2267380d", "url": "https://drz0f01yeq1cx.cloudfront.net/1712113284451-fe73dd6c-f981-46df-ba73-0b9d85c1be9c-8195.mp3", "status": 3, "_id": "660cc685b0950b5bf9bf4b55" } } ``` ### Get Audio Info Result ``` GET https://openapi.akool.com/api/open/v3/audio/infobymodelid?audio_model_id=65f8017f56559aa67f0ecde7 ``` **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** | | ----------------------- | -------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | audio\_model\_id | String | | audio db id：You can get it based on the `_id` field returned by [https://openapi.akool.com/api/open/v3/audio/create](https://docs.akool.com/ai-tools-suite/audio#create-tts) or [https://openapi.akool.com/api/open/v3/audio/clone](https://docs.akool.com/ai-tools-suite/audio#create-voice-clone) 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 | `{status:1,_id:"", url:""}` | status: the status of audio：【1:queueing, 2:processing, 3:completed, 4:failed】`_id`: Interface returns data.url: Generated audio resource url | **Example** **Request** ```bash cURL curl --location 'https://openapi.akool.com/api/open/v3/audio/infobymodelid?audio_model_id=65f8017f56559aa67f0ecde7' \ --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/audio/infobymodelid?audio_model_id=65f8017f56559aa67f0ecde7") .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/audio/infobymodelid?audio_model_id=65f8017f56559aa67f0ecde7", 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/audio/infobymodelid?audio_model_id=65f8017f56559aa67f0ecde7', $headers); $res = $client->sendAsync($request)->wait(); echo $res->getBody(); ``` ```python Python import requests url = "https://openapi.akool.com/api/open/v3/audio/infobymodelid?audio_model_id=65f8017f56559aa67f0ecde7" 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": "65f8017f56559aa67f0ecde7", "create_time": 1710752127995, "uid": 101690, "from": 3, "input_text": "Choose from male and female voices for various use-cases. For tailored options, refer to voice settings or read further.There are both male and female voices to choose from", "rate": "100%", "voice_model_id": "65e980d7af040969db5be854", "url": "https://drz0f01yeq1cx.cloudfront.net/1710752141387-e7867802-0a92-41d4-b899-9bfb23144929-4946.mp3", // Generated audio resource url "status": 3, // current status of audio：【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 audio details.）】 "__v": 0 } } ``` # Background Change Source: https://docs.akool.com/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.[getToken](https://docs.akool.com/authentication/usage#get-the-token) | **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://d3c24lvfmudc1v.cloudfront.net/public/background_change/ROne.png", "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://d3c24lvfmudc1v.cloudfront.net/public/background_change/ROne.png", "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://d3c24lvfmudc1v.cloudfront.net/public/background_change/ROne.png", "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://d3c24lvfmudc1v.cloudfront.net/public/background_change/ROne.png\",\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://d3c24lvfmudc1v.cloudfront.net/public/background_change/ROne.png", "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://d3c24lvfmudc1v.cloudfront.net/public/background_change/ROne.png", "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://d3c24lvfmudc1v.cloudfront.net/public/background_change/ROne.png", "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.[getToken](https://docs.akool.com/authentication/usage#get-the-token) | **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/bg/replace](https://docs.akool.com/ai-tools-suite/background-change#background-change) 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 | # ErrorCode Source: https://docs.akool.com/ai-tools-suite/error-code Error codes and meanings **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 | | code | 1004 | Requires verification | | code | 1005 | Frequent operation | | code | 1006 | Insufficient quota balance | | code | 1007 | Face count changes exceed | | code | 1008 | content not exist | | code | 1009 | permission denied | | code | 1010 | This content cannot be operated | | code | 1011 | This content has been operated | | code | 1013 | Use audio in video | | code | 1014 | Resource does not exist | | code | 1015 | Video processing error | | code | 1016 | Face swapping error | | code | 1017 | Audio not created | | code | 1101 | Illegal token | | code | 1102 | token cannot be empty | | code | 1103 | Not paid or payment is overdue | | code | 1104 | Insufficient credit balance | | code | 1105 | avatar processing error | | code | 1108 | image processing error | | code | 1109 | account not exist | | code | 1110 | audio processing error | | code | 1111 | avatar callback processing error | | code | 1112 | voice processing error | | code | 1200 | Account blocked | | code | 1201 | create audio processing error | | code | 1202 | Video lip sync same language out of range | | code | 1203 | Using Video and Audio | | code | 1204 | video duration exceed | | code | 1205 | create video processing error | | code | 1206 | backgroound change processing error | | code | 1207 | video size exceed | | code | 1208 | video parsing error | | code | 1209 | The video encoding format is not supported | | code | 1210 | video fps exceed | | code | 1211 | Creating lip sync errors | | code | 1212 | Sentiment analysis fails | | code | 1213 | Requires subscription user to use | | code | 1214 | liveAvatar in processing | | code | 1215 | liveAvatar processing is busy | | code | 1216 | liveAvatar session not exist | | code | 1217 | liveAvatar callback error | | code | 1218 | liveAvatar processing error | | code | 1219 | liveAvatar closed | | code | 1220 | liveAvatar upload avatar error | | code | 1221 | Account not subscribed | | code | 1222 | Resource already exist | | code | 1223 | liveAvatar upload exceed | # Face Swap Source: https://docs.akool.com/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":"http://localhost:3007/api/webhook" // 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": "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 \"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\":\"http://localhost:3007/api/webhook\" \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": "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/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": "http://localhost:3007/api/webhook" }'; $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": "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 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":"http://localhost:3007/api/webhook2" // 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":"http://localhost:3007/api/webhook2" }' ``` ```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\":\"http://localhost:3007/api/webhook2\" \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": "http://localhost:3007/api/webhook2" }); 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": "http://localhost:3007/api/webhook2" }'; $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": "http://localhost:3007/api/webhook2" }) 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://docs.akool.com/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.[getToken](https://docs.akool.com/authentication/usage#get-the-token) | **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.[getToken](https://docs.akool.com/authentication/usage#get-the-token) | **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://docs.akool.com/ai-tools-suite/image-generate#text-to-image-image-to-image) | | 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://docs.akool.com/ai-tools-suite/image-generate#get-image-result-image-info)【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.[getToken](https://docs.akool.com/authentication/usage#get-the-token) | **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://docs.akool.com/ai-tools-suite/image-generate#text-to-image-image-to-image) or [https://openapi.akool.com/api/open/v3/content/image/createbybutton](https://docs.akool.com/ai-tools-suite/image-generate#generate-4k-or-variations) 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 | # Jarvis Moderator Source: https://docs.akool.com/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://openapi.akool.com/api/open/v3/content/analysis/sentiment ``` **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** | | ------------- | -------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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 | | 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 | | 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" } ``` **Request** ```bash cURL curl --location 'https://openapi.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://openapi.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://openapi.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://openapi.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://openapi.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://openapi.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.[getToken](https://docs.akool.com/authentication/usage#get-the-token) | **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/content/analysis/sentiment](https://docs.akool.com/ai-tools-suite/jarvis-moderator#jarvis-moderator) . | **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://openapi.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://openapi.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://openapi.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://openapi.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://openapi.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://docs.akool.com/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.[getToken](https://docs.akool.com/authentication/usage#get-the-token) | **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.[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/content/video/lipsync](https://docs.akool.com/ai-tools-suite/lip-sync#create-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 | # Streaming avatar Source: https://docs.akool.com/ai-tools-suite/live-avatar Streaming 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. To experience our live avatar streaming feature in action, explore our demo built on the Agora streaming service: [AKool Streaming Avatar React Demo](https://github.com/AKOOL-Official/akool-streaming-avatar-react-demo). ### Upload Streaming Avatar ``` POST https://openapi.akool.com/api/open/v3/avatar/create ``` **Request Headers** | **Parameter** | **Type** | **Required** | **Description** | | ------------- | -------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------- | | Authorization | String | Yes | Bearer token for API authentication. Obtain from [GetToken](https://docs.akool.com/authentication/usage#get-the-token) endpoint. | **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 | 2 | Avatar type 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](https://docs.akool.com/ai-tools-suite/talkingavatar#upload-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 | `{ 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", "type": 2 }' ``` ```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 \"type\": 2\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", "type": 2 }); 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", "type": 2 }'; $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", "type": 2 }); 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": 2, "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 Streaming Avatar List ```http GET https://openapi.akool.com/api/open/v4/liveAvatar/avatar/list ``` **Request Headers** | **Parameter** | **Type** | **Required** | **Description** | | ------------- | -------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------- | | Authorization | String | Yes | Bearer token for API authentication. Obtain from [GetToken](https://docs.akool.com/authentication/usage#get-the-token) endpoint. | **Query Parameters** | **Parameter** | **Type** | **Required** | **Default** | **Description** | | ------------- | -------- | ------------ | ----------- | ---------------------------------- | | page | Number | No | 1 | Page number for pagination | | size | Number | No | 100 | Number of items per page (max 100) | **Response Properties** | **Property** | **Type** | **Description** | | ------------ | -------- | --------------------------------------------- | | code | Integer | Response status code (1000 indicates success) | | msg | String | Response status message | | data | Object | Container for response data | | data.count | Number | Total number of streaming avatars | | data.result | Array | List of streaming avatar objects | **Streaming Avatar Object Properties** | **Property** | **Type** | **Description** | | ------------ | -------- | ----------------------------------------------------------------------- | | avatar\_id | String | Unique identifier for the streaming avatar | | voice\_id | String | Associated voice model identifier | | name | String | Display name of the avatar | | url | String | URL to access the streaming avatar | | thumbnailUrl | String | URL for the avatar's preview thumbnail | | gender | String | Avatar's gender designation | | available | Boolean | Indicates if the avatar is currently available for use | | type | Number | Avatar type identifier (2 for streaming avatars) | | from | Number | Source identifier for the avatar, 2 for official and 3 for user created | **Example** **Request** ```bash cURL curl --location 'https://openapi.akool.com/api/open/v4/liveAvatar/avatar/list?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/v4/liveAvatar/avatar/list?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/v4/liveAvatar/avatar/list?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/v4/liveAvatar/avatar/list?page=1&size=100', $headers); $res = $client->sendAsync($request)->wait(); echo $res->getBody(); ``` ```python Python import requests url = "https://openapi.akool.com/api/open/v4/liveAvatar/avatar/list?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": { "count": 1, "result": [ { "_id": "67498e55cd053926b2e75cf2", "uid": 1, "type": 2, "from": 2, "avatar_id": "dvp_Tristan_cloth2_1080P", "voice_id": "iP95p4xoKVk53GoZ742B", "name": "tristan_dvp", "url": "https://static.website-files.org/assets/avatar/avatar/streaming_avatar/tristan_10s_silence.mp4", "thumbnailUrl": "https://static.website-files.org/assets/avatar/avatar/thumbnail/1716457024728-tristan_cloth2_20240522.webp", "gender": "male", "available": true } ] } } ``` ### Create session ``` POST https://openapi.akool.com/api/open/v4/liveAvatar/session/create ``` **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** | **Value** | **Description** | | ------------- | -------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | avatar\_id | String | | Digital human model in real-time avatar, The current system provides only one option: "dvp\_Tristan\_cloth2\_1080P". 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. | | duration | Number | | The duration of the session, in seconds. The maximum value is 3600 seconds. | | **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, "credentials": {} }` | `_id`: Interface returns data, status: the status of session: \[1:queueing, 2:processing, 3:completed, 4:failed], credentials: the join information for the Agora SDK | **Example** **Body** ```json { "_id": "6698c9d69cf7b0d61d1b6420", "status": 1, "stream_type": "agora", "credentials": { "agora_uid": 100000, // The user ID for the Agora SDK. "agora_app_id": "", // The App ID used for the Agora SDK. "agora_channel": "", // The specified channel name for the Agora SDK. "agora_token": "", // The authentication token for the Agora SDK, currently the valid time is 5 minutes. } } ``` **Request** ```bash cURL curl --location 'https://openapi.akool.com/api/open/v4/liveAvatar/session/create' \ --header 'authorization: Bearer token' \ --header 'content-type: application/json' \ --data '{ "avatar_id": "dvp_Tristan_cloth2_1080P" }' ``` ```java Java OkHttpClient client = new OkHttpClient().newBuilder() .build(); MediaType mediaType = MediaType.parse("application/json"); RequestBody body = RequestBody.create(mediaType, "{\n \"avatar_id\": \"dvp_Tristan_cloth2_1080P\",\n \"webhookUrl\":\"https://openapitest.akool.com/api/open/v4/test/webhook\"\n}"); Request request = new Request.Builder() .url("https://openapi.akool.com/api/open/v4/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: "dvp_Tristan_cloth2_1080P", 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/v4/test/webhook" }); const requestOptions = { method: "POST", headers: myHeaders, body: raw, redirect: "follow", }; fetch( "https://openapi.akool.com/api/open/v4/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": "dvp_Tristan_cloth2_1080P", "webhookUrl": "https://openapitest.akool.com/api/open/v4/test/webhook" }'; $request = new Request('POST', 'https://openapi.akool.com/api/open/v4/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/v4/liveAvatar/session/create" pld = json.dumps({ "avatar_id": "dvp_Tristan_cloth2_1080P", "webhookUrl": "https://openapitest.akool.com/api/open/v4/test/webhook" }) headers = { 'authorization': 'Bearer token', 'content-type': 'application/json' } response = requests.request("POST", url, headers=headers, data=pld) print(response.text) ``` **Response** ```json { "code": 1000, "msg": "OK", "data": { "_id": "6698c9d69cf7b0d61d1b6420", "uid": 100010, "type": 1, "status": 1, "stream_type": "agora", "credentials": { "agora_uid": 100000, // The user ID for the Agora SDK. "agora_app_id": "", // The App ID used for the Agora SDK. "agora_channel": "", // The specified channel name for the Agora SDK. "agora_token": "", // The authentication token for the Agora SDK, currently the valid time is 5 minutes. } } } ``` ### Get Session Info Result ``` GET https://openapi.akool.com/api/open/v4/liveAvatar/session/detail?id=6698c9d69cf7b0d61d1b6420 ``` **Request Headers** | **Parameter** | **Value** | **Description** | | ------------- | ---------------- | ------------------------------------------------------------------------------------------- | | Authorization | Bearer `{token}` | Your API Key used for request authorization.[getToken](/authentication/usage#get-the-token) | **Query Attributes** | **Parameter** | **Type** | **Value** | **Description** | | ------------- | -------- | --------- | ------------------------------------------------------------------------------------------------------------------------------- | | id | String | NULL | video db id: You can get it based on the `_id` field returned by [Create Session](/ai-tools-suite/live-avatar#create-session) . | **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:"", credentials:{} }` | status: the status of live avatar:(1:queueing, 2:processing, 3:completed, 4:failed) credentials: the url of live avatar, \_id: Interface returns data | **Example** **Request** ```bash cURL curl --location 'http://openapi.akool.com/api/open/v4/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/v4/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/v4/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/v4/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/v4/liveAvatar/session/detail?id=6698c9d69cf7b0d61d1b6420" pld = {} headers = { 'Authorization': 'Bearer token' } response = requests.request("GET", url, headers=headers, data=pld) print(response.text) ``` **Response** ```json { "code": 1000, "msg": "OK", "data": { "_id": "6698c9d69cf7b0d61d1b6420", "uid": 100010, "type": 1, "status": 3, "stream_type": "agora", "credentials": { "agora_uid": 100000, // The user ID for the Agora SDK. "agora_app_id": "", // The App ID used for the Agora SDK. "agora_channel": "", // The specified channel name for the Agora SDK. } } } ``` ### Close Session ``` POST https://openapi.akool.com/api/open/v4/liveAvatar/session/close ``` **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** | **Value** | **Description** | | ------------- | -------- | --------- | ------------------------------------------------------------------------------------------------------------------------------ | | id | String | NULL | session id: You can get it based on the `_id` field returned by [Create session](/ai-tools-suite/live-avatar#create-session) . | **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/v4/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/v4/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/v4/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/v4/liveAvatar/session/close', $headers); $res = $client->sendAsync($request)->wait(); echo $res->getBody(); ``` ```python Python import requests url = "http://openapi.akool.com/api/open/v4/liveAvatar/session/close" pld = {} headers = { 'Authorization': 'Bearer token' } response = requests.request("POST", url, headers=headers, data=pld) print(response.text) ``` **Response** ```json { "code": 1000, "msg": "OK" } ``` ### Get Session List ``` GET https://openapi.akool.com/api/open/v4/liveAvatar/session/list?page=1&size=10&status=1 ``` **Request Headers** | **Parameter** | **Value** | **Description** | | ------------- | ---------------- | -------------------------------------------------------------------------------------------- | | Authorization | Bearer `{token}` | Your API Key used for request authorization. [getToken](/authentication/usage#get-the-token) | **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: [{ credentials: {} }] }` | task\_id: task id of session. url: the url of live avatar. | **Example** **Request** ```bash cURL curl --location 'http://openapi.akool.com/api/open/v4/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/v4/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/v4/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/v4/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/v4/liveAvatar/session/list?page=1&size=10&status=1" pld = {} headers = { 'Authorization': 'Bearer token' } response = requests.request("GET", url, headers=headers, data=pld) print(response.text) ``` **Response** ```json { "code": 1000, "msg": "OK", "data": { "count": 18, "result": [ { "_id": "666d3006247f07725af0f884", "uid": 100010, "type": 1, "status": 1, "stream_type": "agora", "credentials": { "agora_uid": 100000, // The user ID for the Agora SDK. "agora_app_id": "", // The App ID used for the Agora SDK. "agora_channel": "" // The specified channel name for the Agora SDK. }, } ] } } ``` ### Live Avatar Stream Message ```ts IAgoraRTCClient.on(event: "stream-message", listener: (uid: UID, pld: Uint8Array) => void) IAgoraRTCClient.sendStreamMessage(msg: Uint8Array | string, flag: boolean): Promise; ``` **Send Data** **Chat Type Parameters** | **Parameter** | **Type** | **Required** | **Value** | **Description** | | ------------- | -------- | ------------ | --------- | --------------------------------------------------- | | v | Number | Yes | 2 | Version of the message | | type | String | Yes | chat | Message type for chat interactions | | mid | String | Yes | | Unique message identifier for conversation tracking | | idx | Number | Yes | | Sequential index of the message, start from 0 | | fin | Boolean | Yes | | Indicates if this is the final part of the message | | pld | Object | Yes | | Container for message payload | | pld.text | String | Yes | | Text content to send to avatar (e.g. "Hello") | **Command Type Parameters** | **Parameter** | **Type** | **Required** | **Value** | **Description** | | -------------- | -------- | ------------ | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | v | Number | Yes | 2 | Protocol version number | | type | String | Yes | command | Specifies this is a system command message | | mid | String | Yes | | Unique ID to track and correlate command messages | | pld | Object | Yes | | Contains the command details and parameters | | pld.cmd | String | Yes | | Command action to execute. Valid values: **"set-params"** (update avatar settings), **"interrupt"** (stop current avatar response) | | pld.data | Object | No | | Parameters for the command (required for **"set-params"**) | | pld.data.vid | String | No | | Voice ID to change avatar's voice. Only used with **"set-params"**. Get valid IDs from [Voice List API](/ai-tools-suite/audio#get-voice-list-result) | | pld.data.vurl | String | No | | Custom voice model URL. Only used with **"set-params"**. Get valid URLs from [Voice List API](/ai-tools-suite/audio#get-voice-list-result) | | pld.data.lang | String | No | | Language code for avatar responses (e.g. "en", "es"). Only used with **"set-params"**. Get valid codes from [Language List API](/ai-tools-suite/video-translation#get-language-list-result) | | pld.data.mode | Number | No | | Avatar interaction style. Only used with **"set-params"**. "1" = Retelling (avatar repeats content), "2" = Dialogue (avatar engages in conversation) | | pld.data.bgurl | String | No | | URL of background image/video for avatar scene. Only used with **"set-params"** | **JSON Example** ```json Chat Request { "v": 2, "type": "chat", "mid": "msg-1723629433573", "idx": 0, "fin": true, "pld": { "text": "Hello" }, } ``` ```json Set Avatar Params { "v": 2, "type": "command", "mid": "msg-1723629433573", "pld": { "cmd": "set-params", "data": { "vid": "1", "lang": "en", "mode": 1, "bgurl": "https://example.com/background.jpg" } }, } ``` ```json Interrupt Response { "v": 2, "type": "command", "mid": "msg-1723629433573", "pld": { "cmd": "interrupt" }, } ``` **Receive Data** **Chat Type Parameters** | **Parameter** | **Type** | **Value** | **Description** | | ------------- | -------- | --------------- | --------------------------------------------------------------------------------------- | | v | Number | 2 | Version of the message | | type | String | chat | Message type for chat interactions | | mid | String | | Unique message identifier for tracking conversation flow | | idx | Number | | Sequential index of the message part | | fin | Boolean | | Indicates if this is the final part of the response | | pld | Object | | Container for message payload | | pld.from | String | "bot" or "user" | Source of the message - "bot" for avatar responses, "user" for speech recognition input | | pld.text | String | | Text content of the message | **Command Type Parameters** | **Parameter** | **Type** | **Value** | **Description** | | ------------- | -------- | ------------------------- | -------------------------------------------------------------------------------------------------------- | | v | Number | 2 | Version of the message | | type | String | command | Message type for system commands | | mid | String | | Unique identifier for tracking related messages in a conversation | | pld | Object | | Container for command payload | | pld.cmd | String | "set-params", "interrupt" | Command to execute: **"set-params"** to update avatar settings, **"interrupt"** to stop current response | | pld.code | Number | 1000 | Response code from the server, 1000 indicates success | | pld.msg | String | | Response message from the server | **JSON Example** ```json Chat Response { "v": 2, "type": "chat", "mid": "msg-1723629433573", "idx": 0, "fin": true, "pld": { "from": "bot", "text": "Hello! How can I assist you today? " } } ``` ```json Command Response { "v": 2, "type": "command", "mid": "msg-1723629433573", "pld": { "cmd": "set-params", "code": 1000, "msg": "OK" } } ``` **Typescript Example** ```ts Create Client const client: IAgoraRTCClient = AgoraRTC.createClient({ mode: 'rtc', codec: 'vp8', }); client.join(agora_app_id, agora_channel, agora_token, agora_uid); client.on('stream-message', (message: Uint8Array | string) => { console.log('received: %s', message); }); ``` ```ts Send Message const msg = JSON.stringify({ v: 2, type: "chat", mid: "msg-1723629433573", idx: 0, fin: true, pld: { text: "hello" }, }); await client.sendStreamMessage(msg, false); ``` ```ts Set Avatar Params const setAvatarParams = async () => { const msg = JSON.stringify({ v: 2, type: 'command', pld: { cmd: 'set-params', params: { vid: voiceId, lang: language, mode: modeType, }, }, }); return client.sendStreamMessage(msg, false); }; ``` ```ts Interrupt Response const interruptResponse = async () => { const msg = JSON.stringify({ v: 2, type: 'command', pld: { cmd: 'interrupt', }, }); return client.sendStreamMessage(msg, false); }; ``` ### Integrating Your Own LLM Service Before dispatching a message to the WebSocket, consider executing an HTTP request to your LLM service. ```ts TypeScript const client: IAgoraRTCClient = AgoraRTC.createClient({ mode: 'rtc', codec: 'vp8', }); client.join(agora_app_id, agora_channel, agora_token, agora_uid); client.on('stream-message', (message: Uint8Array | string) => { console.log('received: %s', message); }); let inputMessage = 'hello'; try { const response = await fetch('https://your-backend-host/api/llm/answer', { method: "POST", headers: { "Content-Type": "application/json", }, body: JSON.stringify({ question: inputMessage, }), }); if (response.ok) { const result = await response.json(); inputMessage = result.answer; } else { console.error("Failed to fetch from backend", response.statusText); } } catch (error) { console.error("Error during fetch operation", error); } const message = { v: 2, type: "chat", mid: "msg-1723629433573", idx: 0, fin: true, pld: { text: inputMessage, }, }; client.sendStreamMessage(JSON.stringify(message), false); ``` ### 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 | # Reage Source: https://docs.akool.com/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. Experience our age adjustment technology in action by exploring our interactive demo on GitHub: [AKool Reage Demo](https://github.com/AKOOL-Official/akool-reage-demo). ### 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.[getToken](https://docs.akool.com/authentication/usage#get-the-token) | **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://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\_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.[getToken](https://docs.akool.com/authentication/usage#get-the-token) | **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://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\_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://static.website-files.org/assets/images/faceswap/crop_1719224038759-3888-0-1719224039439-1517.jpg", // Links to faces detected in target images "opts": "1408,786:1954,798:1653,1091:1447,1343" // 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": [ // Replacement target image information { "path": "https://static.website-files.org/assets/images/faceswap/crop_1719224038759-3888-0-1719224039439-1517.jpg", // Links to faces detected in target images "opts": "1408,786:1954,798:1653,1091:1447,1343" // 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 }' ``` ```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://static.website-files.org/assets/images/faceswap/crop_1719224038759-3888-0-1719224039439-1517.jpg\", \n \"opts\": \"1408,786:1954,798:1653,1091:1447,1343\" \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}\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": [ // Replacement target image information { "path": "https://static.website-files.org/assets/images/faceswap/crop_1719224038759-3888-0-1719224039439-1517.jpg", // Links to faces detected in target images "opts": "1408,786:1954,798:1653,1091:1447,1343" // 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 }); 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": [ // Replacement target image information { "path": "https://static.website-files.org/assets/images/faceswap/crop_1719224038759-3888-0-1719224039439-1517.jpg", // Links to faces detected in target images "opts": "1408,786:1954,798:1653,1091:1447,1343" // 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 = 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": [ // Replacement target image information { "path": "https://static.website-files.org/assets/images/faceswap/crop_1719224038759-3888-0-1719224039439-1517.jpg", // Links to faces detected in target images "opts": "1408,786:1954,798:1653,1091:1447,1343" // 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 }) 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.[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/reage#image-reage) or [https://openapi.akool.com/api/open/v3/faceswap/highquality/specifyvideo](https://docs.akool.com/ai-tools-suite/reage#video-reage) 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.[getToken](https://docs.akool.com/authentication/usage#get-the-token) | **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/specifyimage](https://docs.akool.com/ai-tools-suite/reage#image-reage) or [https://openapi.akool.com/api/open/v3/faceswap/highquality/specifyvideo](https://docs.akool.com/ai-tools-suite/reage#video-reage) 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](https://docs.akool.com/ai-tools-suite/reage#image-reage) or [https://openapi.akool.com/api/open/v3/faceswap/highquality/specifyvideo](https://docs.akool.com/ai-tools-suite/reage#video-reage) 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 Avatar Source: https://docs.akool.com/ai-tools-suite/talking-avatar 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/audio#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](https://docs.akool.com/ai-tools-suite/audio#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-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/talkingavatar#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. | **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" } ], "webhookUrl": "http://localhost:3007/api/open/v3/test/webhook" } ``` **Request** ```bash cURL curl --location 'https://openapi-test.akool.io/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" } ] }' ``` ```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-test.akool.io/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" } ] }); const requestOptions = { method: "POST", headers: myHeaders, body: raw, redirect: "follow" }; fetch("https://openapi-test.akool.io/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-test.akool.io/api/open/v3/talkingavatar/create', $headers, $body); $res = $client->sendAsync($request)->wait(); echo $res->getBody(); ``` ```python Python import requests import json url = "https://openapi-test.akool.io/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://docstest.akool.io/ai-tools-suite/talkingavatar#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/. | | type | String | 1，2 | Avatar type, 1 represents talking 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](https://docs.akool.com/ai-tools-suite/talkingavatar#upload-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://landing-test.akool.io/interface/stats-api/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", "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 \"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", "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", "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", "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 | # Talking Photo Source: https://docs.akool.com/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. Experience our talking photo technology in action by exploring our interactive demo on GitHub: [AKool Talking Photo Demo](https://github.com/AKOOL-Official/akool-talking-photo-demo). ### 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.[getToken](https://docs.akool.com/authentication/usage#get-the-token). | **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. [getToken](https://docs.akool.com/authentication/usage#get-the-token) | **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://docs.akool.com/ai-tools-suite/talking-photo#talking-photo) 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 | # Video Translation Source: https://docs.akool.com/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. [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 | 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. [getToken](https://docs.akool.com/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. | **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": "http://localhost:3007/api/open/v3/test/webhook" // Callback url address based on HTTP request } ``` **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, "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 \"url\": \"https://drz0f01yeq1cx.cloudfront.net/1710470596011-facebook.mp4\", \n \"language\": \"hi\", \n \"source_language\": \"zh\", \n \"lipsync\":true, \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/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: "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/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, "webhookUrl": "http://localhost:3007/api/open/v3/test/webhook" }'; $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, "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, "msg": "OK", "data": { "create_time": 1710757900382, "uid": 101690, "type": 8, "sub_type": 801, "from": 2, "target_video": "https://drz0f01yeq1cx.cloudfront.net/1710470596011-facebook.mp4", "source_language": "zh", "language": "hi", "faceswap_quality": 2, "video_id": "16db4826-e090-4169-861a-1de5de809a33", "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": "https://drz0f01yeq1cx.cloudfront.net/1710487405274-252239be-3411-4084-9e84-bf92eb78fbba-2031.mp4", // the url of Generated video "storage_loc": 1, "webhookUrl": "http://localhost:3007/api/open/v3/test/webhook", "task_id": "65f8180c4116596c1592edfb", "target_video_md5": "64fd4b47695945e94f0181b2a2fe5bb1", "pre_video_id": "", "lipsync": true, "lipSyncType": true, "_id": "65f8180c24d9989e93dde3b6", "__v": 0 } } ``` ### 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.[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/content/video/createbytranslate](https://docs.akool.com/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 | # Webhook Source: https://docs.akool.com/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 import hashlib from Crypto.Cipher import AES import base64 # Generate signature def generate_msg_signature(client_id, timestamp, nonce, msg_encrypt): sorted_str = ''.join(sorted([client_id, timestamp, nonce, msg_encrypt])) hash_value = hashlib.sha1(sorted_str.encode('utf-8')).hexdigest() return hash_value # Decryption algorithm def generate_aes_decrypt(data_encrypt, client_id, client_secret): aes_key = client_secret.encode('utf-8') # Ensure the IV is 16 bytes long iv = client_id.encode('utf-8') iv = iv[:16] if len(iv) >= 16 else iv.ljust(16, b'\0') cipher = AES.new(aes_key, AES.MODE_CBC, iv) decrypted_data = cipher.decrypt(base64.b64decode(data_encrypt)) padding_len = decrypted_data[-1] return decrypted_data[:-padding_len].decode('utf-8') # Encryption algorithm def generate_aes_encrypt(data, client_id, client_secret): aes_key = client_secret.encode('utf-8') # Ensure the IV is 16 bytes long iv = client_id.encode('utf-8') iv = iv[:16] if len(iv) >= 16 else iv.ljust(16, b'\0') # Pkcs7 padding data_bytes = data.encode('utf-8') padding_len = AES.block_size - len(data_bytes) % AES.block_size padded_data = data_bytes + bytes([padding_len]) * padding_len cipher = AES.new(aes_key, AES.MODE_CBC, iv) encrypted_data = cipher.encrypt(padded_data) return base64.b64encode(encrypted_data).decode('utf-8') ``` ```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 import base64 def generate_msg_signature(client_id, timestamp, nonce, msg_encrypt): sorted_str = ''.join(sorted([client_id, timestamp, nonce, msg_encrypt])) hash_value = hashlib.sha1(sorted_str.encode('utf-8')).hexdigest() return hash_value # Decryption algorithm def generate_aes_decrypt(data_encrypt, client_id, client_secret): aes_key = client_secret.encode('utf-8') # Ensure the IV is 16 bytes long iv = client_id.encode('utf-8') iv = iv[:16] if len(iv) >= 16 else iv.ljust(16, b'\0') cipher = AES.new(aes_key, AES.MODE_CBC, iv) decrypted_data = cipher.decrypt(base64.b64decode(data_encrypt)) padding_len = decrypted_data[-1] return decrypted_data[:-padding_len].decode('utf-8') # 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://docs.akool.com/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. All API requests should include your API token in the HTTP header. Bearer tokens are generally composed of a random string of characters. Formally, it takes the form of the "Bearer" keyword and the token value separated by spaces. The following is the general form of a Bearer token: ``` Authorization: Bearer {token} ``` Here is an example of an actual Bearer token: ``` Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjYyYTA2Mjg1N2YzNWNjNTJlM2UxNzYyMCIsInR5cGUiOiJ1c2VyIiwiZnJvbSI6InRvYiIsImVtYWlsIjoiZ3VvZG9uZ2RvbmdAYWtvb2wuY29tIiwiZmlyc3ROYW1lIjoiZGQiLCJ1aWQiOjkwMzI4LCJjb2RlIjoiNTY1NCIsImlhdCI6MTczMjg2NzczMiwiZXhwIjoxNzMyODY3NzMzfQ._pilTnv8sPsrKCzrAyh9Lsvyge8NPxUG5Y_8CTdxad0 ``` 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. ### 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. Bearer tokens are generally composed of a random string of characters. Formally, it takes the form of the "Bearer" keyword and the token value separated by spaces. The following is the general form of a Bearer token: ``` Authorization: Bearer {token} ``` Here is an example of an actual Bearer token: ``` Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjYyYTA2Mjg1N2YzNWNjNTJlM2UxNzYyMCIsInR5cGUiOiJ1c2VyIiwiZnJvbSI6InRvYiIsImVtYWlsIjoiZ3VvZG9uZ2RvbmdAYWtvb2wuY29tIiwiZmlyc3ROYW1lIjoiZGQiLCJ1aWQiOjkwMzI4LCJjb2RlIjoiNTY1NCIsImlhdCI6MTczMjg2NzczMiwiZXhwIjoxNzMyODY3NzMzfQ._pilTnv8sPsrKCzrAyh9Lsvyge8NPxUG5Y_8CTdxad0 ``` 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 | # Streaming Avatar Integration: using Agora SDK Source: https://docs.akool.com/implementation-guide/streaming-avatar Learn how to integrate streaming avatars using the Agora SDK ## Overview The Streaming Avatar feature allows you to create interactive, real-time avatar experiences in your application. This guide provides a comprehensive walkthrough of integrating streaming avatars using the Agora SDK, including: * Setting up real-time communication channels * Handling avatar interactions and responses * Managing audio streams * Implementing cleanup procedures * Optional LLM service integration The integration uses Agora's Real-Time Communication (RTC) SDK for reliable, low-latency streaming and our avatar service for generating responsive avatar behaviors. ## Prerequisites 1. Install the Agora SDK in your project: ```bash npm install agora-rtc-sdk-ng # or yarn add agora-rtc-sdk-ng ``` 2. Import the required dependencies: ```ts import AgoraRTC, { IAgoraRTCClient } from "agora-rtc-sdk-ng"; ``` 3. Add the hidden API of Agora SDK Agora SDK's sendStreamMessage is not exposed, so we need to add it manually. And it has some limitations, so we need to handle it carefully. We can infer [from the doc](https://docs.agora.io/en/voice-calling/troubleshooting/error-codes?platform=android#data-stream-related-error-codes) that the message size is limited to 1KB and the message frequency is limited to 6KB per second. The Agora SDK's `sendStreamMessage` method needs to be manually added to the type definitions: ```ts interface RTCClient extends IAgoraRTCClient { sendStreamMessage(msg: Uint8Array | string, flag: boolean): Promise; } ``` **Important**: The Agora SDK has the following limitations: * Maximum message size: 1KB * Maximum message frequency: 6KB per second ## Integration Flow ```mermaid sequenceDiagram participant Client participant YourBackend participant Akool participant Agora %% Session Creation - Two Paths alt Direct Browser Implementation Client->>Akool: Create session Akool-->>Client: Return Agora credentials else Backend Implementation Client->>YourBackend: Request session YourBackend->>Akool: Create session Akool-->>YourBackend: Return Agora credentials YourBackend-->>Client: Forward Agora credentials end %% Agora Connection Client->>Agora: Join channel with credentials Agora-->>Client: Connection established %% Optional LLM Integration alt Using Custom LLM service Client->>YourBackend: Send question to LLM YourBackend-->>Client: Return processed response end %% Message Flow Client->>Agora: Send message Agora->>Akool: Forward message %% Response Flow Akool->>Agora: Stream avatar response Agora->>Client: Forward streamed response %% Audio Flow (Optional) opt Audio Interaction Client->>Agora: Publish audio track Agora->>Akool: Forward audio stream Akool->>Agora: Stream avatar response Agora->>Client: Forward avatar response end %% Video Flow (Coming Soon) opt Video Interaction (Future Feature) Client->>Agora: Publish video track Agora->>Akool: Forward video stream Akool->>Agora: Stream avatar response Agora->>Client: Forward avatar response end %% Cleanup - Two Paths alt Direct Browser Implementation Client->>Agora: Leave channel Client->>Akool: Close session else Backend Implementation Client->>Agora: Leave channel Client->>YourBackend: Request session closure YourBackend->>Akool: Close session end ``` ## Key Implementation Steps ### 1. Create a Live Avatar Session **Security Recommendation**: We strongly recommend implementing session management through your backend server rather than directly in the browser. This approach: * Protects your AKool API token from exposure * Allows for proper request validation and rate limiting * Enables usage tracking and monitoring * Provides better control over session lifecycle * Prevents unauthorized access to the API First, create a session to obtain Agora credentials. While both browser and backend implementations are possible, the backend approach is recommended for security: ```ts // Recommended: Backend Implementation async function createSessionFromBackend(): Promise { // Your backend endpoint that securely wraps the AKool API const response = await fetch('https://your-backend.com/api/avatar/create-session', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ avatarId: "dvp_Tristan_cloth2_1080P", duration: 600, }) }); if (!response.ok) { throw new Error('Failed to create session through backend'); } return response.json(); } // Not Recommended: Direct Browser Implementation // Only use this for development/testing purposes async function createSessionInBrowser(): Promise { const response = await fetch('https://openapi.akool.com/api/open/v4/liveAvatar/session/create', { method: 'POST', headers: { 'Authorization': 'Bearer YOUR_TOKEN', // Security risk: Token exposed in browser 'Content-Type': 'application/json' }, body: JSON.stringify({ avatar_id: "dvp_Tristan_cloth2_1080P", duration: 600, }) }); if (!response.ok) { throw new Error(`Failed to create session: ${response.status} ${response.statusText}`); } const res = await response.json(); return res.data; } ``` ### 2. Initialize Agora Client Create and configure the Agora client: ```ts async function initializeAgoraClient(credentials) { const client = AgoraRTC.createClient({ mode: 'rtc', codec: 'vp8' }); try { await client.join( credentials.agora_app_id, credentials.agora_channel, credentials.agora_token, credentials.agora_uid ); return client; } catch (error) { console.error('Error joining channel:', error); throw error; } } ``` ### 3. Subscribe Audio and Video Stream Subscribe to the audio and video stream of the avatar: ```ts async function subscribeToAvatarStream(client: IAgoraRTCClient) { const onUserPublish = async (user: IAgoraRTCRemoteUser, mediaType: 'video' | 'audio') => { const remoteTrack = await client.subscribe(user, mediaType); remoteTrack.play(); }; const onUserUnpublish = async (user: IAgoraRTCRemoteUser, mediaType: 'video' | 'audio') => { await client.unsubscribe(user, mediaType); }; client.on('user-published', onUserPublish); client.on('user-unpublished', onUserUnpublish); } ``` ### 4. Set Up Message Handling Configure message listeners to handle avatar responses: ```ts function setupMessageHandlers(client: IAgoraRTCClient) { let answer = ''; client.on('stream-message', (uid, message) => { try { const parsedMessage = JSON.parse(message); if (parsedMessage.type === 'chat') { const payload = parsedMessage.pld; if (payload.from === 'bot') { if (!payload.fin) { answer += payload.text; } else { console.log('Avatar response:', answer); answer = ''; } } else if (payload.from === 'user') { console.log('User message:', payload.text); } } else if (parsedMessage.type === 'command') { if (parsedMessage.pld.code !== 1000) { console.error('Command failed:', parsedMessage.pld.msg); } } } catch (error) { console.error('Error parsing message:', error); } }); } ``` ### 5. Send Messages to Avatar Implement functions to interact with the avatar: ```ts async function sendMessageToAvatar(client: IAgoraRTCClient, question: string) { const message = { v: 2, type: "chat", mid: `msg-${Date.now()}`, idx: 0, fin: true, pld: { text: question, } }; try { await client.sendStreamMessage(JSON.stringify(message), false); } catch (error) { console.error('Error sending message:', error); throw error; } } ``` In real-world scenarios, the message size is limited to 1KB and the message frequency is limited to 6KB per second, so we need to split the message into chunks and send them separately. ```ts export async function sendMessageToAvatar(client: RTCClient, messageId: string, content: string) { const MAX_ENCODED_SIZE = 950; const BYTES_PER_SECOND = 6000; // Improved message encoder with proper typing const encodeMessage = (text: string, idx: number, fin: boolean): Uint8Array => { const message: StreamMessage = { v: 2, type: 'chat', mid: messageId, idx, fin, pld: { text, }, }; return new TextEncoder().encode(JSON.stringify(message)); }; // Validate inputs if (!content) { throw new Error('Content cannot be empty'); } // Calculate maximum content length const baseEncoded = encodeMessage('', 0, false); const maxQuestionLength = Math.floor((MAX_ENCODED_SIZE - baseEncoded.length) / 4); // Split message into chunks const chunks: string[] = []; let remainingMessage = content; let chunkIndex = 0; while (remainingMessage.length > 0) { let chunk = remainingMessage.slice(0, maxQuestionLength); let encoded = encodeMessage(chunk, chunkIndex, false); // Binary search for optimal chunk size if needed while (encoded.length > MAX_ENCODED_SIZE && chunk.length > 1) { chunk = chunk.slice(0, Math.ceil(chunk.length / 2)); encoded = encodeMessage(chunk, chunkIndex, false); } if (encoded.length > MAX_ENCODED_SIZE) { throw new Error('Message encoding failed: content too large for chunking'); } chunks.push(chunk); remainingMessage = remainingMessage.slice(chunk.length); chunkIndex++; } log(`Splitting message into ${chunks.length} chunks`); // Send chunks with rate limiting for (let i = 0; i < chunks.length; i++) { const isLastChunk = i === chunks.length - 1; const encodedChunk = encodeMessage(chunks[i], i, isLastChunk); const chunkSize = encodedChunk.length; const minimumTimeMs = Math.ceil((1000 * chunkSize) / BYTES_PER_SECOND); const startTime = Date.now(); log(`Sending chunk ${i + 1}/${chunks.length}, size=${chunkSize} bytes`); try { await client.sendStreamMessage(encodedChunk, false); } catch (error: unknown) { throw new Error(`Failed to send chunk ${i + 1}: ${error instanceof Error ? error.message : 'Unknown error'}`); } if (!isLastChunk) { const elapsedMs = Date.now() - startTime; const remainingDelay = Math.max(0, minimumTimeMs - elapsedMs); if (remainingDelay > 0) { await new Promise((resolve) => setTimeout(resolve, remainingDelay)); } } } } ``` ### 6. Control Avatar Parameters Implement functions to control avatar settings: ```ts async function setAvatarParams(client: IAgoraRTCClient, params: { vid?: string; lang?: string; mode?: number; bgurl?: string; }) { const message = { v: 2, type: 'command', mid: `msg-${Date.now()}`, pld: { cmd: 'set-params', data: params } }; await client.sendStreamMessage(JSON.stringify(message), false); } async function interruptAvatar(client: IAgoraRTCClient) { const message = { v: 2, type: 'command', mid: `msg-${Date.now()}`, pld: { cmd: 'interrupt' } }; await client.sendStreamMessage(JSON.stringify(message), false); } ``` ### 7. Audio Interaction With The Avatar To enable audio interaction with the avatar, you'll need to publish your local audio stream: ```ts async function publishAudio(client: IAgoraRTCClient) { // Create a microphone audio track const audioTrack = await AgoraRTC.createMicrophoneAudioTrack(); try { // Publish the audio track to the channel await client.publish(audioTrack); console.log("Audio publishing successful"); return audioTrack; } catch (error) { console.error("Error publishing audio:", error); throw error; } } // Example usage with audio controls async function setupAudioInteraction(client: IAgoraRTCClient) { let audioTrack; // Start audio async function startAudio() { try { audioTrack = await publishAudio(client); } catch (error) { console.error("Failed to start audio:", error); } } // Stop audio async function stopAudio() { if (audioTrack) { // Stop and close the audio track audioTrack.stop(); audioTrack.close(); await client.unpublish(audioTrack); audioTrack = null; } } // Mute/unmute audio function toggleAudio(muted: boolean) { if (audioTrack) { if (muted) { audioTrack.setEnabled(false); } else { audioTrack.setEnabled(true); } } } return { startAudio, stopAudio, toggleAudio }; } ``` Now you can integrate audio controls into your application: ```ts async function initializeWithAudio() { try { // Initialize avatar const client = await initializeStreamingAvatar(); // Setup audio controls const audioControls = await setupAudioInteraction(client); // Start audio when needed await audioControls.startAudio(); // Example of muting/unmuting audioControls.toggleAudio(true); // mute audioControls.toggleAudio(false); // unmute // Stop audio when done await audioControls.stopAudio(); } catch (error) { console.error("Error initializing with audio:", error); } } ``` For more details about Agora's audio functionality, refer to the [Agora Web SDK Documentation](https://docs.agora.io/en/voice-calling/get-started/get-started-sdk?platform=web#publish-a-local-audio-track). ### 8. Video Interaction With The Avatar (coming soon) Video interaction is currently under development and will be available in a future release. The following implementation details are provided as a reference for upcoming features. To enable video interaction with the avatar, you'll need to publish your local video stream: ```ts // Note: This is a preview of upcoming functionality async function publishVideo(client: IAgoraRTCClient) { // Create a camera video track const videoTrack = await AgoraRTC.createCameraVideoTrack(); try { // Publish the video track to the channel await client.publish(videoTrack); console.log("Video publishing successful"); return videoTrack; } catch (error) { console.error("Error publishing video:", error); throw error; } } // Example usage with video controls (Preview of upcoming features) async function setupVideoInteraction(client: IAgoraRTCClient) { let videoTrack; // Start video async function startVideo() { try { videoTrack = await publishVideo(client); // Play the local video in a specific HTML element videoTrack.play('local-video-container'); } catch (error) { console.error("Failed to start video:", error); } } // Stop video async function stopVideo() { if (videoTrack) { // Stop and close the video track videoTrack.stop(); videoTrack.close(); await client.unpublish(videoTrack); videoTrack = null; } } // Enable/disable video function toggleVideo(enabled: boolean) { if (videoTrack) { videoTrack.setEnabled(enabled); } } // Switch camera (if multiple cameras are available) async function switchCamera(deviceId: string) { if (videoTrack) { await videoTrack.setDevice(deviceId); } } return { startVideo, stopVideo, toggleVideo, switchCamera }; } ``` The upcoming video features will include: * Two-way video communication * Camera switching capabilities * Video quality controls * Integration with existing audio features Stay tuned for updates on when video interaction becomes available. ### 9. Integrating your own LLM service (optional) You can integrate your own LLM service to process messages before sending them to the avatar. Here's how to do it: ```ts // Define the LLM service response interface interface LLMResponse { answer: string; } // Set the avatar to retelling mode await setAvatarParams(client, { mode: 1, }); // Create a wrapper for your LLM service async function processWithLLM(question: string): Promise { try { const response = await fetch('YOUR_LLM_SERVICE_ENDPOINT', { method: 'POST', headers: { 'Content-Type': 'application/json', }, body: JSON.stringify({ question, }) }); if (!response.ok) { throw new Error('LLM service request failed'); } return await response.json(); } catch (error) { console.error('Error processing with LLM:', error); throw error; } } async function sendMessageToAvatarWithLLM( client: IAgoraRTCClient, question: string ) { try { // Process the question with your LLM service const llmResponse = await processWithLLM(question); // Prepare the message with LLM response const message = { type: "chat", mid: `msg-${Date.now()}`, idx: 0, fin: true, pld: { text: llmResponse.answer // Use the LLM-processed response } }; // Send the processed message to the avatar await client.sendStreamMessage(JSON.stringify(message), false); } catch (error) { console.error('Error in LLM-enhanced message sending:', error); throw error; } } ``` *Remember to*: 1. Implement proper rate limiting for your LLM service 2. Handle token limits appropriately 3. Implement retry logic for failed LLM requests 4. Consider implementing streaming responses if your LLM service supports it 5. Cache common responses when appropriate ### 10. Cleanup Cleanup can also be performed either directly or through your backend: ```ts // Browser Implementation async function cleanupInBrowser(client: IAgoraRTCClient, sessionId: string) { await fetch('https://openapi.akool.com/api/open/v4/liveAvatar/session/close', { method: 'POST', headers: { 'Authorization': 'Bearer YOUR_TOKEN' }, body: JSON.stringify({ id: sessionId }) }); await performClientCleanup(client); } // Backend Implementation async function cleanupFromBackend(client: IAgoraRTCClient, sessionId: string) { await fetch('https://your-backend.com/api/avatar/close-session', { method: 'POST', body: JSON.stringify({ sessionId }) }); await performClientCleanup(client); } // Shared cleanup logic async function performClientCleanup(client: IAgoraRTCClient) { // Remove event listeners client.removeAllListeners('user-published'); client.removeAllListeners('user-unpublished'); client.removeAllListeners('stream-message'); // Stop audio/video and unpublish if they're still running if (audioControls) { await audioControls.stopAudio(); } if (videoControls) { await videoControls.stopVideo(); } // Leave the Agora channel await client.leave(); } ``` When implementing through your backend, make sure to: * Securely store your AKool API token * Implement proper authentication and rate limiting * Handle errors appropriately * Consider implementing session management and monitoring ### 11. Putting It All Together Here's how to use all the components together: ```ts async function initializeStreamingAvatar() { let client; try { // Create session and get credentials const session = await createSession(); const { credentials } = session; // Initialize Agora client client = await initializeAgoraClient(credentials); // Subscribe to the audio and video stream of the avatar await subscribeToAvatarStream(client); // Set up message handlers setupMessageHandlers(client); // Example usage await sendMessageToAvatar(client, "Hello!"); // Or use your own LLM service await sendMessageToAvatarWithLLM(client, "Hello!"); // Example of voice interaction await interruptAvatar(client); // Example of Audio Interaction With The Avatar await setupAudioInteraction(client); // Example of changing avatar parameters await setAvatarParams(client, { lang: "en", vid: "new_voice_id" }); return client; } catch (error) { console.error('Error initializing streaming avatar:', error); if (client) { await cleanup(client, session._id); } throw error; } } ``` ## Additional Resources * [Agora Web SDK Documentation](https://docs.agora.io/en/sdks?platform=web) * [Agora Web SDK API Reference](https://api-ref.agora.io/en/video-sdk/web/4.x/index.html) * [AKool OpenAPI Error Codes](/ai-tools-suite/live-avatar#response-code-description) # Streaming Avatar SDK Best Practice Source: https://docs.akool.com/sdk/jssdk-best-practice Learn how implement Streaming Avatar SDK step by step ## Overview When implementing a JavaScript SDK, especially one that interacts with sensitive resources or APIs, it is critical to ensure the security of private keys, tokens, and other sensitive credentials. Exposing such sensitive information in a client-side environment (e.g., browsers) can lead to vulnerabilities, including unauthorized access, token theft, and API abuse. This document outlines best practices for securing private keys and tokens in your Streaming Avatar SDK implementation while exposing only the necessary session data to the client. * Never Expose Private Keys in the Client-Side Code * Use Short-Lived Session as token * Delegate Authentication to a Backend Server * Handling avatar interactions and responses * Managing audio streams and events The integration uses Agora's Real-Time Communication (RTC) SDK for reliable, low-latency streaming and our avatar service for generating responsive avatar behaviors. ## Prerequisites * Get your [Akool API Token](https://www.akool.com) from [Akool Authentication API](/authentication/usage#get-the-token) * Basic knowledge of backend services and internet security. * Basic knowledge of JavaScript and Http Request ## Getting Started 1.To get started with the Streaming Avatar SDK, you just need one html page with lots of elements like below: ```html Streaming Avatar SDK

Streaming Avatar Demo

``` 2.importing Streaming Avatar SDK: ```html ``` 3.Instantiation StreamingAvatar class and get session params form your backend: ```js var stream = new StreamingAvatar(); // info: start your stream session with Credentials. // Best Practice: get from Akool Session_ID and Credentials from your backend service. const paramsWithCredentials = await YOUR_BACK_END_API_FOR_START_SESSION() ``` YOUR\_BACK\_END\_API\_FOR\_START\_SESSION may like below: ```js async function fetchAccessToken() { const id = YOUR_CLIENT_ID; const apiKey = AKOOL_SECRET_KEY; const response = await fetch( "https://openapi.akool.com/api/open/v3/getToken", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ "clientId": id "clientSecret": apiKey }), redirect: "follow", } ); const { data } = await response.json(); return data.token; } async function createSession(token,avatar_id,duration) { const id = YOUR_CLIENT_ID; const apiKey = AKOOL_SECRET_KEY; const response = await fetch( "https://openapi.akool.com/api/open/v4/liveAvatar/session/create", { method: "POST", headers: { "Authorization": `Bearer ${token}`, "Content-Type": "application/json", }, body: JSON.stringify({ avatar_id; duration; }), redirect: "follow", } ); const { data } = await response.json(); return data; } const token = await fetchAccessToken() avatar_id = "dvp_Tristan_cloth2_1080P" duration = 300; const paramsWithCredentials = await createSession(token,avatar_id,duration) ``` Make sure the YOUR\_BACK\_END\_API\_FOR\_START\_SESSION return the paramsWithCredentials from your backend 4. Sign up functions for steaming events and button click events: ```js function handleStreamReady(event:any) { console.log('Stream is ready:',event.detail) } function handleMessageReceive(event:any) { console.log('Message:', event.detail) } function handleWillExpire(event:any) { console.log('Warning:',event.detail.msg) } function handleExpired(event:any) { console.log('Warning:',event.detail.msg) } function handleERROR(event:any) { console.error('ERROR has occurred:',event.detail.msg) } function handleStreamClose(event:any) { console.log('Stream is close:',event.detail) // when you leave the page you'd better off the eventhandler stream.off(StreamEvents.READY,handleStreamReady) stream.off(StreamEvents.ONMESSAGE,handleMessageReceive) stream.off(StreamEvents.WILLEXPIRE,handleWillExpire) stream.off(StreamEvents.EXPIRED,handleExpired) stream.off(StreamEvents.ERROR,handleERROR) stream.off(StreamEvents.CLOSED,handleStreamClose) } stream.on(StreamEvents.READY,handleStreamReady) stream.on(StreamEvents.ONMESSAGE,handleMessageReceive) stream.on(StreamEvents.WILLEXPIRE,handleWillExpire) stream.on(StreamEvents.EXPIRED,handleExpired) stream.on(StreamEvents.ERROR,handleERROR) stream.on(StreamEvents.CLOSED,handleStreamClose) async function handleToggleSession() { if (window.toggleSession.innerHTML == " ... ") return if (window.toggleSession.innerHTML == "Start Session") { window.toggleSession.innerHTML = " ... " await stream.startSessionWithCredentials('yourStreamingVideoDom',paramsWithCredentials) window.toggleSession.innerHTML = "End Session" window.userInput.disabled = false; window.sendButton.disabled = false; window.voiceButton.disabled = false; }else{ // info: close your stream session stream.closeStreaming() window.messageWrap.innerHTML = '' window.toggleSession.innerHTML = "Start Session" window.userInput.disabled = true; window.sendButton.disabled = true; window.voiceButton.disabled = true; } } async function handleSendMessage() { await stream.sendMessage(window.userInput.value ?? '') } async function handleToggleMic() { await stream.toggleMic() if (stream.micStatus) { window.voiceButton.innerHTML = "Turn mic off" }else{ window.voiceButton.innerHTML = "Turn mic on" } } window.toggleSession.addEventListener("click", handleToggleSession); window.sendButton.addEventListener("click", handleSendMessage); window.voiceButton.addEventListener("click", handleToggleMic); ``` ## Additional Resources * [Streaming Avatar SDK API Interface](/implementation-guide/jssdk-api) * [AKool OpenAPI Error Codes](/ai-tools-suite/live-avatar#response-code-description) # Streaming Avatar SDK Quick Start Source: https://docs.akool.com/sdk/jssdk-start Learn what is the Streaming Avatar SDK ## Overview The JSSDK provides access to Akool Streaming Avatar services, enabling programmatic control of avatar interactions. You can connect and manage avatars in live sessions using WebSockets for seamless communication. This allows you to send text commands to avatars, enabling real-time speech with customizable voices. The JSSDK simplifies the creation, management, and termination of avatar sessions programmatically. * Vanilla javascript and light weight dependency files * Integrating interactive avatar just by one line js code * Handling avatar interactions and responses * Managing audio streams The integration uses Agora's Real-Time Communication (RTC) SDK for reliable, low-latency streaming and our avatar service for generating responsive avatar behaviors. ## Prerequisites * Get your [Akool API Token](https://www.akool.com) from [Akool Authentication API](/authentication/usage#get-the-token) * Basic knowledge of JavaScript and Http Request ## Getting Started 1.To get started with the Streaming Avatar SDK, you just need one html page, and one div container: ```html Streaming Avatar SDK

Streaming Avatar Demo

``` 2.Importing Streaming Avatar SDK and a few js code to access the interactive avatar stream. ```bash npm install @akool/streaming-avatar-sdk # or yarn add @akool/streaming-avatar-sdk ``` ```js import { StreamingAvatar,StreamEvents } from 'streaming-avatar-sdk' const myStreamingAvatar = new StreamingAvatar({ token: "your-api-token" }) myStreamingAvatar.initDom('yourAvatarContainer') ``` or by vanilla js way ```html ``` ```html ``` * Then you will get the result:

* [Learn how to get your api token](/authentication/usage#get-the-token) * [Best Practice with your own service for security](/implementation-guide/jssdk-best-practice) ## Additional Resources * [Streaming Avatar SDK API Interface](/implementation-guide/jssdk-api) * [AKool OpenAPI Error Codes](/ai-tools-suite/live-avatar#response-code-description)