openapi: 3.0.3
info:
title: Akool OpenAPI
description: >-
The Akool OpenAPI exposes Akool's generative AI video and image tools over
HTTPS REST under https://openapi.akool.com. Covered here are the Talking
Avatar, Talking Photo, Face Swap, Video Translation, Image Generation, and
Live Avatar (real-time streaming) products. Generation is asynchronous:
callers create a task and either poll by id or receive an encrypted webhook
callback when the task completes (video_status / image_status / job status
1=queueing, 2=processing, 3=completed, 4=failed). Requests authenticate with
an `Authorization: Bearer {token}` header (token minted from clientId /
clientSecret at POST /api/open/v3/getToken) or a direct `x-api-key` header.
This document is authored by API Evangelist from Akool's public
documentation (docs.akool.com) and hand-models request/response shapes at a
high level; consult the live docs and Akool's own published OpenAPI files for
exhaustive field detail.
version: '1.0'
contact:
name: Akool
url: https://akool.com
x-authored-by: API Evangelist
x-source: https://docs.akool.com
servers:
- url: https://openapi.akool.com
description: Akool OpenAPI
security:
- bearerAuth: []
- apiKeyAuth: []
tags:
- name: Authentication
description: Mint a Bearer token from a clientId / clientSecret pair.
- name: Talking Avatar
description: Generate a speaking avatar video from text or audio.
- name: Talking Photo
description: Animate a still portrait into a talking video.
- name: Face Swap
description: Swap a source face onto a target image or video.
- name: Video Translation
description: Translate a video into other languages with optional lip-sync.
- name: Image Generation
description: Text-to-image and image-to-image generation.
- name: Live Avatar
description: Real-time streaming avatar sessions over WebRTC (Agora / LiveKit / TRTC).
paths:
/api/open/v3/getToken:
post:
operationId: getToken
tags:
- Authentication
summary: Get an API token
description: >-
Exchange a clientId and clientSecret for a Bearer token used in the
Authorization header. Alternatively, callers may skip this step and pass
a direct `x-api-key` header on each request.
security: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- clientId
- clientSecret
properties:
clientId:
type: string
clientSecret:
type: string
responses:
'200':
description: A token response (code 1000 on success).
content:
application/json:
schema:
type: object
properties:
code:
type: integer
token:
type: string
/api/open/v3/talkingavatar/create:
post:
operationId: createTalkingAvatar
tags:
- Talking Avatar
summary: Create a talking avatar video
description: >-
Generate a speaking avatar video. Provide an avatar_id (from the avatar
list), a voice_id, and input_text, or a pre-generated audio url that
takes precedence over input_text. Poll status with the video info
endpoint using the returned _id.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/TalkingAvatarRequest'
responses:
'200':
description: Task accepted; contains _id and video_status.
content:
application/json:
schema:
$ref: '#/components/schemas/VideoTask'
/api/open/v3/content/video/createbytalkingphoto:
post:
operationId: createByTalkingPhoto
tags:
- Talking Photo
summary: Create a talking photo video
description: >-
Animate a still portrait (talking_photo_url) with an audio track
(audio_url). Optional prompt controls gestures; resolution is 720p or
1080p; webhookUrl receives an encrypted completion callback.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/TalkingPhotoRequest'
responses:
'200':
description: Task accepted; contains _id and video_status.
content:
application/json:
schema:
$ref: '#/components/schemas/VideoTask'
/api/open/v3/content/video/infobymodelid:
get:
operationId: getVideoInfoByModelId
tags:
- Talking Photo
summary: Poll video status
description: >-
Retrieve the status and result URL of a talking photo (or other
content video) task by its model id. Returns video_status and, once
completed, the video URL.
parameters:
- name: video_model_id
in: query
required: true
schema:
type: string
responses:
'200':
description: Current status and result.
content:
application/json:
schema:
$ref: '#/components/schemas/VideoTask'
/api/open/v4/faceswap/faceswapPlusByImage:
post:
operationId: faceSwapPlusByImage
tags:
- Face Swap
summary: Face swap onto an image or video
description: >-
Swap a source_url face onto a target_url image or video. Use
single_face_mode for one face, or a face_mapping array for multi-face
pairing. model_style is realistic, beautify, or lossless. Video jobs are
asynchronous; retrieve with the result endpoint or via webhookUrl.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/FaceSwapRequest'
responses:
'200':
description: Task accepted; contains data._id and data.job_id.
content:
application/json:
schema:
type: object
properties:
code:
type: integer
msg:
type: string
data:
type: object
properties:
_id:
type: string
job_id:
type: string
/api/open/v3/faceswap/result/listbyids:
get:
operationId: listFaceSwapResultsByIds
tags:
- Face Swap
summary: Get face swap results by ids
description: >-
Retrieve one or more face swap results by a comma-separated list of ids.
Each result carries a faceswap_status (1=in queue, 2=processing,
3=success, 4=failed).
parameters:
- name: _ids
in: query
required: true
description: Comma-separated result ids.
schema:
type: string
responses:
'200':
description: A list of face swap results.
content:
application/json:
schema:
type: object
properties:
code:
type: integer
data:
type: array
items:
type: object
/api/open/v3/language/list:
get:
operationId: listTranslationLanguages
tags:
- Video Translation
summary: List supported translation languages
description: >-
Returns the languages supported for video translation, including
language names, codes, and flag icon URLs.
responses:
'200':
description: A list of supported languages.
content:
application/json:
schema:
type: object
properties:
code:
type: integer
data:
type: array
items:
type: object
/api/open/v3/content/video/createbytranslate:
post:
operationId: createByTranslate
tags:
- Video Translation
summary: Create a video translation
description: >-
Translate a source video (url) into one or more target languages, with
optional lipsync, speaker_num detection, remove_bgm, and caption_type
handling. Poll status by the returned _id.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/VideoTranslateRequest'
responses:
'200':
description: Task accepted; contains _id and video_status.
content:
application/json:
schema:
$ref: '#/components/schemas/VideoTask'
/api/open/v4/content/image/createBySourcePrompt:
post:
operationId: createImageBySourcePrompt
tags:
- Image Generation
summary: Generate an image (text-to-image / image-to-image)
description: >-
Generate images from a text prompt, optionally conditioned on
source_images for image-to-image. Controls include model_name, scale
(aspect ratio), resolution (1080p or 4k), and batch_quantity (1-4). Poll
status with the image info endpoint.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ImageGenerateRequest'
responses:
'200':
description: Task accepted; contains _id and image_status.
content:
application/json:
schema:
$ref: '#/components/schemas/ImageTask'
/api/open/v3/content/image/infobymodelid:
get:
operationId: getImageInfoByModelId
tags:
- Image Generation
summary: Poll image status
description: Retrieve image generation status and result URL by image_model_id.
parameters:
- name: image_model_id
in: query
required: true
schema:
type: string
responses:
'200':
description: Current status and result.
content:
application/json:
schema:
$ref: '#/components/schemas/ImageTask'
/api/open/v4/liveAvatar/avatar/list:
get:
operationId: listLiveAvatars
tags:
- Live Avatar
summary: List streaming avatars
description: Retrieve available streaming avatars with optional page and size pagination.
parameters:
- name: page
in: query
required: false
schema:
type: integer
- name: size
in: query
required: false
schema:
type: integer
responses:
'200':
description: A list of streaming avatars.
content:
application/json:
schema:
type: object
properties:
code:
type: integer
data:
type: array
items:
type: object
/api/open/v4/liveAvatar/session/create:
post:
operationId: createLiveAvatarSession
tags:
- Live Avatar
summary: Create a live avatar session
description: >-
Open a real-time streaming avatar session. The session media is carried
over a caller-selected third-party WebRTC transport - stream_type is
agora (default), livekit, or trtc - and the corresponding credentials
(agora_channel / agora_token, or livekit_url / livekit_token, etc.) are
supplied by the caller. Akool itself does not expose a proprietary
WebSocket for the media stream.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/LiveAvatarSessionRequest'
responses:
'200':
description: Session created; contains _id, status, stream_type, and credentials.
content:
application/json:
schema:
$ref: '#/components/schemas/LiveAvatarSession'
/api/open/v4/liveAvatar/session/close:
post:
operationId: closeLiveAvatarSession
tags:
- Live Avatar
summary: Close a live avatar session
description: Close an open streaming avatar session by id.
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
id:
type: string
responses:
'200':
description: Session closed.
content:
application/json:
schema:
type: object
properties:
code:
type: integer
msg:
type: string
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: >-
Bearer token minted from clientId / clientSecret via POST
/api/open/v3/getToken. Passed as `Authorization: Bearer {token}`.
apiKeyAuth:
type: apiKey
in: header
name: x-api-key
description: Direct API key passed as the `x-api-key` header (no token step required).
schemas:
VideoTask:
type: object
description: Common asynchronous video task envelope.
properties:
code:
type: integer
description: 1000 indicates success.
_id:
type: string
description: Task id used to poll status.
video_status:
type: integer
description: 1=queueing, 2=processing, 3=completed, 4=failed.
video:
type: string
description: Result video URL, available when video_status is 3.
ImageTask:
type: object
description: Common asynchronous image task envelope.
properties:
code:
type: integer
_id:
type: string
image_status:
type: integer
description: 1=queueing, 2=processing, 3=completed, 4=failed.
deduction_credit:
type: number
description: Credits deducted for the request.
TalkingAvatarRequest:
type: object
properties:
avatar_from:
type: integer
description: 2 for official Akool avatars, 3 for user-provided.
avatar_id:
type: string
voice_id:
type: string
input_text:
type: string
url:
type: string
description: Optional pre-generated audio URL; takes precedence over input_text.
width:
type: integer
height:
type: integer
TalkingPhotoRequest:
type: object
required:
- talking_photo_url
- audio_url
properties:
talking_photo_url:
type: string
audio_url:
type: string
prompt:
type: string
resolution:
type: string
description: 720p or 1080p (default 720p).
webhookUrl:
type: string
FaceSwapRequest:
type: object
required:
- source_url
- target_url
properties:
source_url:
type: string
description: Source (new) face image URL.
target_url:
type: string
description: Target image or video URL.
single_face_mode:
type: boolean
model_style:
type: string
description: realistic, beautify, or lossless.
face_enhance:
type: boolean
face_mapping:
type: array
description: Source/target face pairs for multi-face mode.
items:
type: object
webhookUrl:
type: string
VideoTranslateRequest:
type: object
required:
- url
- language
properties:
url:
type: string
description: The video URL to translate.
language:
type: string
description: Target language(s), comma-separated.
source_language:
type: string
description: Original language; DEFAULT auto-detects.
lipsync:
type: boolean
speaker_num:
type: integer
remove_bgm:
type: boolean
caption_type:
type: integer
webhookUrl:
type: string
ImageGenerateRequest:
type: object
required:
- prompt
properties:
prompt:
type: string
model_name:
type: string
source_images:
type: array
description: URLs for image-to-image transformation.
items:
type: string
scale:
type: string
description: Aspect ratio such as 1:1, 16:9, 4:3.
resolution:
type: string
description: 1080p or 4k.
batch_quantity:
type: integer
description: 1-4 images per request.
LiveAvatarSessionRequest:
type: object
properties:
avatar_id:
type: string
stream_type:
type: string
description: agora (default), livekit, or trtc.
agora_channel:
type: string
agora_token:
type: string
agora_uid:
type: integer
agora_app_id:
type: string
livekit_url:
type: string
livekit_token:
type: string
LiveAvatarSession:
type: object
properties:
code:
type: integer
data:
type: object
properties:
_id:
type: string
uid:
type: integer
status:
type: integer
description: 1=queueing, 2=processing, 3=completed, 4=failed.
stream_type:
type: string
credentials:
type: object
description: Echo of the WebRTC transport credentials provided.