AdsTurbo Persona API

openapi: 3.2.0
info:
  title: AdsTurbo Open Persona 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: Persona
  description: Custom Persona workflows
paths:
  /openapi/v1/aiactor/perform:
    post:
      tags:
      - Persona
      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'
  /openapi/v1/persona/create:
    post:
      tags:
      - Persona
      summary: Create a custom Persona
      operationId: openPersonaCreate
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OpenPersonaCreateBody'
      responses:
        '200':
          description: JSON business response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiSuccessOpenPersonaEnt'
      description: Create a custom Persona from a portrait image and optional voice sample.
  /openapi/v1/persona/delete:
    post:
      tags:
      - Persona
      summary: Delete a custom Persona
      operationId: openPersonaDelete
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OpenPersonaDeleteBody'
      responses:
        '200':
          description: JSON business response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiSuccessOpenPersonaDeleteEnt'
      description: Delete a custom Persona owned by the current API key.
  /openapi/v1/persona/list:
    post:
      tags:
      - Persona
      summary: List personal actors
      description: List custom Personas created by the current user with pagination.
      operationId: openPersonalList
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OpenPersonalListBody'
      responses:
        '200':
          description: JSON business response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiSuccessOpenPersonalListEnt'
  /openapi/v1/persona/status:
    post:
      tags:
      - Persona
      summary: Query Persona status
      operationId: openGetPersonaStatus
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OpenGetPersonaStatusBody'
      responses:
        '200':
          description: JSON business response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiSuccessOpenPersonaEnt'
      description: Query Persona processing status by `actor_id`.
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
    OpenPersonaCreateBody:
      type: object
      description: Create custom Persona request.
      properties:
        photo_url:
          type: string
        voice_audio_url:
          type: string
          description: Optional audio sample for voice cloning.
        name:
          type: string
        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).
    OpenPersonaDeleteBody:
      type: object
      description: Delete Persona request.
      properties:
        actor_id:
          type: string
    OpenPersonaData:
      type: object
      description: Custom Persona information.
      properties:
        actor_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).
        name:
          type: string
        photo_url:
          type: string
        voice_url:
          type: string
        preview_image_url:
          type: string
        preview_video_url:
          type: string
        voices:
          type: array
          items:
            $ref: '#/components/schemas/AiActorVoiceOption'
        message:
          type: string
        created_at:
          type: integer
          format: int64
    ApiSuccessOpenPersonalListEnt:
      type: object
      required:
      - ret
      properties:
        ret:
          type: integer
          example: 1
        msg:
          type: string
        data:
          type: object
          properties:
            ent:
              $ref: '#/components/schemas/OpenPersonalListData'
    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).
    ApiSuccessOpenPersonaDeleteEnt:
      type: object
      required:
      - ret
      properties:
        ret:
          type: integer
          example: 1
        msg:
          type: string
        data:
          type: object
          properties:
            ent:
              $ref: '#/components/schemas/OpenPersonaDeleteData'
    ApiSuccessOpenPersonaEnt:
      type: object
      required:
      - ret
      properties:
        ret:
          type: integer
          example: 1
        msg:
          type: string
        data:
          type: object
          properties:
            ent:
              $ref: '#/components/schemas/OpenPersonaData'
    AiActorVoiceOption:
      type: object
      description: Actor voice option.
      properties:
        voice_id:
          type: string
        voice_url:
          type: string
        voice_description:
          type: string
        source:
          type: string
    OpenPersonalListBody:
      type: object
      description: Paginated list request for personal actors. `offset` and `limit` are pagination parameters.
      properties:
        offset:
          type: integer
          format: int32
        limit:
          type: integer
          format: int32
    ApiSuccessOpenWorkEnt:
      type: object
      required:
      - ret
      properties:
        ret:
          type: integer
          example: 1
        msg:
          type: string
        data:
          type: object
          properties:
            ent:
              $ref: '#/components/schemas/OpenWorkData'
    OpenGetPersonaStatusBody:
      type: object
      description: Query Persona status by `actor_id`.
      properties:
        actor_id:
          type: string
    OpenPersonaDeleteData:
      type: object
      description: Delete operation result.
      properties:
        ok:
          type: boolean
    OpenPersonalListData:
      type: object
      description: Personal actor list and pagination metadata.
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/OpenPersonaData'
        offset:
          type: integer
          format: int32
        more:
          type: boolean
        total:
          type: integer
          format: int32
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: '在 [adsturbo.ai](https://adsturbo.ai) 控制台创建的密钥。调用时在请求头设置：`Authorization: Bearer <your_api_key>`。

        '