AdsTurbo AI Actor API

openapi: 3.2.0
info:
  title: AdsTurbo Open AI Actor API
  description: 'AdsTurbo Open API documentation. All endpoints are under `/openapi/v1/`.


    **Base URL**: `https://adsturbo.ai/klian/novartapi`


    **Authentication**: Use **HTTP Bearer** (RFC 6750). Send `Authorization: Bearer `, where `` is the API key created in the AdsTurbo console.


    **Request body**: `Content-Type: application/json`


    **Success response**: HTTP 200 with `{ "ret": 1, "data": { "ent": } }`


    **Business errors**: HTTP 200 may still contain `ret` other than `1`. Read `msg` for the error reason.'
  version: 1.0.0
servers:
- url: https://adsturbo.ai/klian/novartapi
  description: API base URL
security:
- bearerAuth: []
tags:
- name: AiActor
  description: System actor workflows
paths:
  /openapi/v1/aiactor/list:
    post:
      tags:
      - AiActor
      summary: List system actors
      operationId: openAiActorList
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OpenAiActorListBody'
      responses:
        '200':
          description: JSON business response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiSuccessOpenAiActorListEnt'
      description: Return available system actors with optional filters and pagination.
  /openapi/v1/aiactor/say:
    post:
      tags:
      - AiActor
      summary: Generate system actor speech
      operationId: openAiActorSay
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OpenAiActorSayBody'
      responses:
        '200':
          description: JSON business response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiSuccessOpenAiActorSayEnt'
      description: Generate speech audio with a system actor voice.
  /openapi/v1/aiactor/perform:
    post:
      tags:
      - AiActor
      summary: Generate an actor performance
      description: '`actor_id` may be either a system actor ID or a custom Persona `actor_id`. Both use the same performance parameters and async task response.'
      operationId: openAiActorPerform
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OpenAiActorPerformBody'
      responses:
        '200':
          description: JSON business response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiSuccessOpenWorkEnt'
components:
  schemas:
    OpenWorkData:
      type: object
      description: Async task status and result summary.
      properties:
        workspace_id:
          type: string
        status:
          type: string
          description: pending / processing / completed / failed
        callback_id:
          type: string
          description: Custom tracking ID, echoed back in `/openapi/v1/work/status` results so you can match tasks to your own records (webhook delivery is not available yet).
        result_type:
          type: string
          enum:
          - video
          - image
          - audio
          - text
          - structured
        result_url:
          type: string
        thumbnail_url:
          type: string
        duration:
          type: number
          format: float
        message:
          type: string
        created_at:
          type: integer
          format: int64
    OpenAiActorListBody:
      type: object
      description: System actor filters and pagination. Filter values are lowercase; spaces in English phrases use hyphens.
      properties:
        gender:
          type: array
          items:
            type: string
            enum:
            - female
            - male
        age:
          type: array
          items:
            type: string
            enum:
            - senior
            - adult
            - young-adult
            - kid
        situation:
          type: array
          items:
            type: string
            enum:
            - balcony
            - beach
            - bedroom
            - car
            - coffee-shop
            - grwm
            - home
            - kitchen
            - medical
            - news-anchor
            - office
            - podcast
            - snow
            - studio
        sort_by:
          type: string
        offset:
          type: integer
          format: int32
        limit:
          type: integer
          format: int32
        pose:
          type: array
          items:
            type: string
            enum:
            - arms-crossed
            - cross-legged
            - gesturing
            - leaning
            - leaning-forward
            - legs-crossed
            - pointing
            - reclining
            - sitting
            - standing
        shot_type:
          type: array
          items:
            type: string
            enum:
            - close-up
            - full-shot
            - long-shot
            - medium-close-up
            - medium-full-shot
            - medium-shot
        ethnicity:
          type: array
          items:
            type: string
            enum:
            - asian
            - caucasian
            - african
            - latino
        industry:
          type: array
          description: Filter by server-side industry category, such as `beauty`, `fitness`, or `finance`. Valid values follow the server registry.
          items:
            type: string
    OpenAiActorInfo:
      type: object
      description: System actor information.
      properties:
        id:
          type: integer
          format: int64
        hired_at:
          type: integer
          format: int64
          description: Hire time as Unix seconds.
        actor_id:
          type: string
          description: Actor ID (UUID).
        name:
          type: string
          description: Name.
        age:
          type: string
          description: Age label.
        gender:
          type: string
          description: Gender.
        situation:
          type: array
          items:
            type: string
          description: Scene tags.
        pose:
          type: string
        shot_type:
          type: string
        skin_tone:
          type: string
          description: Skin tone code, from `skin-001` to `skin-006`.
        accessories:
          type: array
          items:
            type: string
          description: Accessories.
        special_for:
          type: array
          items:
            type: string
          description: Subscription tiers this actor is exclusive to.
        preview_url:
          type: string
          description: Compressed preview image URL.
        photo_url:
          type: string
          description: Image template URL to use.
        original_show_off_url:
          type: string
          description: Original showcase video URL.
        show_off_url:
          type: string
          description: Compressed showcase video URL.
        light:
          type: string
          description: Lighting setup.
        audition_audio_url:
          type: string
          description: Audition audio URL.
        score:
          type: integer
          format: int32
          minimum: 0
          maximum: 100
          description: Actor score. Maximum is 100.
        status:
          type: string
          description: pending / processing / completed / failed
        voices:
          type: array
          items:
            $ref: '#/components/schemas/AiActorVoiceOption'
        ethnicity:
          type: string
          description: Primary ethnicity. Values include `asian`, `caucasian`, `african`, and `latino`.
        poses:
          type: array
          description: Historical pose list. `pose` is the primary pose.
          items:
            type: string
        shot_types:
          type: array
          description: Historical shot type list. `shot_type` is the primary shot type.
          items:
            type: string
        industries:
          type: array
          description: Supported industries. Valid values follow the server registry.
          items:
            type: string
    OpenAiActorListData:
      type: object
      description: System actor list and pagination metadata.
      properties:
        infos:
          type: array
          items:
            $ref: '#/components/schemas/OpenAiActorInfo'
        offset:
          type: integer
          format: int32
        more:
          type: boolean
        total:
          type: integer
          format: int32
    OpenAiActorSayData:
      type: object
      description: Speech synthesis result.
      properties:
        audio_url:
          type: string
        duration:
          type: integer
          format: int32
    ApiSuccessOpenAiActorListEnt:
      type: object
      required:
      - ret
      properties:
        ret:
          type: integer
          example: 1
        msg:
          type: string
        data:
          type: object
          properties:
            ent:
              $ref: '#/components/schemas/OpenAiActorListData'
    OpenAiActorSayBody:
      type: object
      description: System actor speech synthesis request.
      properties:
        actor_id:
          type: string
        script:
          type: string
        auto_emotion:
          type: boolean
        speed:
          type: number
          format: float
        stability:
          type: number
          format: float
        similarity:
          type: number
          format: float
    OpenAiActorPerformBody:
      type: object
      description: Actor performance request for both system actors and custom Personas.
      properties:
        script:
          type: string
        actor_id:
          type: string
          description: System actor ID or Persona `actor_id`.
        auto_emotion:
          type: boolean
        speed:
          type: number
          format: float
        stability:
          type: number
          format: float
        style:
          type: number
          format: float
        speaker_boost:
          type: boolean
        similarity:
          type: number
          format: float
        callback_id:
          type: string
          description: Custom tracking ID, echoed back in `/openapi/v1/work/status` results so you can match tasks to your own records (webhook delivery is not available yet).
    AiActorVoiceOption:
      type: object
      description: Actor voice option.
      properties:
        voice_id:
          type: string
        voice_url:
          type: string
        voice_description:
          type: string
        source:
          type: string
    ApiSuccessOpenAiActorSayEnt:
      type: object
      required:
      - ret
      properties:
        ret:
          type: integer
          example: 1
        msg:
          type: string
        data:
          type: object
          properties:
            ent:
              $ref: '#/components/schemas/OpenAiActorSayData'
    ApiSuccessOpenWorkEnt:
      type: object
      required:
      - ret
      properties:
        ret:
          type: integer
          example: 1
        msg:
          type: string
        data:
          type: object
          properties:
            ent:
              $ref: '#/components/schemas/OpenWorkData'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: '在 [adsturbo.ai](https://adsturbo.ai) 控制台创建的密钥。调用时在请求头设置：`Authorization: Bearer <your_api_key>`。

        '