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.