AdsTurbo AdClone (v2beta) API

openapi: 3.2.0
info:
  title: AdsTurbo Open AdClone (v2beta) 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: AdClone (v2beta)
  description: AdClone video recreation (v2beta, editable draft flow)
paths:
  /openapi/v2beta/adclone/create:
    post:
      tags:
      - AdClone (v2beta)
      summary: Create an AdClone draft
      description: 'Submit a source video. The server analyzes it asynchronously into an **editable draft** and returns a `clone_id` immediately. Poll the draft with `/openapi/v2beta/adclone/get`.


        **Full flow**: `create` → poll `get` until `completed` → `preview` (optional) → `submit` → poll `/openapi/v1/work/status` for results.


        **Only single-segment clones are supported for now**: the source clip (after clipping) must be 15 seconds or shorter. Longer sources are **rejected synchronously** (`10000`, `source longer than 15s requires multi-segment clone, not available yet`).


        Drafts are kept for 24 hours and are only readable by the user who owns the API key that created them.'
      operationId: openAdCloneCreate
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OpenAdCloneCreateBody'
            examples:
              basic:
                summary: Clip seconds 0-12
                value:
                  video_url: https://example.com/source.mp4
                  clip_start: 0
                  clip_end: 12
                  lang: en
                  idempotency_key: 3f1c9a52-7d7e-4c1b-9d61-0b1c2d3e4f50
      responses:
        '200':
          description: JSON business response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiSuccessOpenAdCloneCreateEnt'
  /openapi/v2beta/adclone/get:
    post:
      tags:
      - AdClone (v2beta)
      summary: Get an AdClone draft
      description: 'Poll a draft. While `processing`, the response carries `stage` / `progress`; once `completed`, it carries `draft` (lines, voices, reference slots, prompt, aspect ratio / resolution options, default quote, and edit limits).


        If the `clone_id` does not exist, has expired (24 hours), or belongs to another user, the call **does not fail**; it returns `status=not_found`.'
      operationId: openAdCloneGet
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OpenAdCloneGetBody'
      responses:
        '200':
          description: JSON business response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiSuccessOpenAdCloneGetEnt'
  /openapi/v2beta/adclone/preview:
    post:
      tags:
      - AdClone (v2beta)
      summary: Preview AdClone edits
      description: 'Optional step: rebuild the prompt from `edits` and the `video` settings, and return reference bindings plus a quote. **No credits are charged and nothing is generated.**


        A later `submit` with **exactly the same** `edits` + `video` reuses this preview, so the submitted prompt is the one you saw here.


        The draft must be `completed`; otherwise the call returns `10000` (`clone is not ready (status=...)`).'
      operationId: openAdClonePreview
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OpenAdClonePreviewBody'
      responses:
        '200':
          description: JSON business response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiSuccessOpenAdClonePreviewEnt'
  /openapi/v2beta/adclone/submit:
    post:
      tags:
      - AdClone (v2beta)
      summary: Submit an AdClone generation
      description: 'Submit a generation task. **Credits are charged before the task is created.** Returns async task IDs; poll `/openapi/v1/work/status` for status and results.


        - When `video.quantity` > 1, multiple videos are generated and `workspace_ids` lists every task ID (`workspace_id` is the first one)

        - If `edits` + `video` match the latest `preview` exactly, the preview result is reused; otherwise the prompt is rebuilt on submit

        - On an `idempotency_key` hit only the first `workspace_id` is returned; the full `workspace_ids` list is only in the first response

        - `callback_id` is echoed back in the response as-is'
      operationId: openAdCloneSubmit
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OpenAdCloneSubmitBody'
            examples:
              basic:
                summary: Edit one line, replace the person reference, generate 2 videos
                value:
                  clone_id: acl_4f2a9c1e7b3d4e5f8a6b0c1d2e3f4a5b
                  edits:
                    lines:
                    - id: L1
                      text: This serum changed my skin in a week.
                    references:
                    - type: 2
                      slot_id: subject_1
                      image_url: https://example.com/my_actor.jpg
                  video:
                    aspect_ratio: '9:16'
                    duration: 12
                    quantity: 2
                  callback_id: cb_adclone_001
                  idempotency_key: 8a4e2c10-1f3b-4d5e-9a7b-6c5d4e3f2a10
      responses:
        '200':
          description: JSON business response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiSuccessOpenWorkEnt'
components:
  schemas:
    OpenAdCloneVideoSetting:
      type: object
      description: Generation settings. All optional.
      properties:
        aspect_ratio:
          type: string
          description: Aspect ratio. Empty = default; see `draft.gen_options` for options.
        resolution:
          type: string
          description: Resolution. Empty = default; see `draft.gen_options` for options.
        duration:
          type: integer
          format: int32
          description: Duration in seconds. 0 = source clip duration (rounded up). Below 4 becomes 4; above 15 becomes 15.
        quantity:
          type: integer
          format: int32
          description: Number of videos. 0 or 1 = one video; maximum 4.
    OpenAdCloneVoice:
      type: object
      properties:
        id:
          type: string
          description: Voice identity ID.
        desc:
          type: string
          description: Voice description.
    OpenAdCloneEdits:
      type: object
      description: Edits shared by `preview` and `submit`. All optional; omitted = keep the original draft.
      properties:
        lines:
          type: array
          description: Only the changed lines. `id` must be unique and exist in the draft; an empty `text` mutes that line.
          items:
            $ref: '#/components/schemas/OpenAdCloneLineEdit'
        references:
          type: array
          description: Final reference image set. `image_url` is required for each item; `type` must be 1, 2, or 3.
          items:
            $ref: '#/components/schemas/OpenAdCloneRefInput'
        prompt:
          type: string
          description: Overrides the whole prompt. Empty = no override.
        voice_id:
          type: string
          description: Reserved (dubbing voice). **Any non-empty value returns `10000` for now.**
    OpenAdCloneSubmitBody:
      type: object
      required:
      - clone_id
      properties:
        clone_id:
          type: string
          description: Draft ID.
        edits:
          $ref: '#/components/schemas/OpenAdCloneEdits'
        video:
          $ref: '#/components/schemas/OpenAdCloneVideoSetting'
        callback_id:
          type: string
          description: Custom tracking ID, echoed back in the response.
        idempotency_key:
          type: string
          description: Optional idempotency key (UUID recommended). Repeated requests with the same key return the same task without charging again.
    OpenAdClonePreviewData:
      type: object
      properties:
        prompt:
          type: string
          description: Rebuilt prompt.
        bindings:
          type: array
          description: 'Reference bindings: prompt tag ↔ the image actually used.'
          items:
            $ref: '#/components/schemas/OpenAdCloneRefBinding'
        pricing:
          $ref: '#/components/schemas/AdClonePricing'
    OpenAdCloneCreateBody:
      type: object
      description: Create an AdClone draft. The source clip (after clipping) must be 15 seconds or shorter.
      required:
      - video_url
      properties:
        video_url:
          type: string
          description: Source video URL. Must be publicly accessible.
        clip_start:
          type: number
          format: double
          minimum: 0
          description: Clip start in seconds. When both `clip_start` and `clip_end` are 0 (or omitted), the whole video is used.
        clip_end:
          type: number
          format: double
          description: Clip end in seconds. Must be greater than `clip_start`. The server clips on whole seconds (start rounded down, end rounded up); the rounded range must be 15 seconds or shorter.
        lang:
          type: string
          description: Language for writing the prompt. Empty = `en`. Lines always keep their original language.
        house_model:
          type: string
          description: Reserved. No values are available yet; **any non-empty value returns `10000`**. Leave empty.
        idempotency_key:
          type: string
          description: Optional idempotency key (UUID recommended). Repeated requests with the same key return the same `clone_id`.
    ApiSuccessOpenAdCloneGetEnt:
      type: object
      required:
      - ret
      properties:
        ret:
          type: integer
          example: 1
        msg:
          type: string
        data:
          type: object
          properties:
            ent:
              $ref: '#/components/schemas/OpenAdCloneGetData'
    ApiSuccessOpenAdCloneCreateEnt:
      type: object
      required:
      - ret
      properties:
        ret:
          type: integer
          example: 1
        msg:
          type: string
        data:
          type: object
          properties:
            ent:
              $ref: '#/components/schemas/OpenAdCloneCreateData'
    OpenAdCloneRefBinding:
      type: object
      properties:
        tag:
          type: string
          description: Reference tag inside the prompt, such as `[@character_1]`.
        type:
          $ref: '#/components/schemas/AdCloneRefType'
        image_url:
          type: string
          description: Image actually used.
    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
    OpenAdCloneRefSlot:
      type: object
      properties:
        slot_id:
          type: string
          description: Slot ID (for example `subject_1`). Reference it in `edits.references[].slot_id`.
        type:
          $ref: '#/components/schemas/AdCloneRefType'
        desc:
          type: string
          description: Subject description.
        image_url:
          type: string
          description: Candidate frame URL (always empty for now; the caller supplies replacement images).
        source_ts:
          type: number
          format: double
          description: Candidate frame time in seconds (always 0 for now).
        shots:
          type: array
          items:
            type: integer
            format: int32
          description: Shot indexes in which the subject appears.
    OpenAdCloneCreateData:
      type: object
      properties:
        clone_id:
          type: string
          description: 'Draft ID: `acl_` followed by 32 hex characters.'
        matched_house_model:
          type: string
          description: Reserved. Always empty for now.
    OpenAdCloneLimits:
      type: object
      description: 'Edit limits (single-segment clones: at most 9 references, at most 2 person references, duration 4-15 seconds, at most 4 videos).'
      properties:
        max_references:
          type: integer
          format: int32
          description: Maximum number of reference images.
        max_person_references:
          type: integer
          format: int32
          description: Maximum number of person reference images.
        min_duration:
          type: integer
          format: int32
          description: Minimum selectable duration in seconds.
        max_duration:
          type: integer
          format: int32
          description: Maximum selectable duration in seconds.
        max_quantity:
          type: integer
          format: int32
          description: Maximum number of videos per submission.
    AdCloneTextMark:
      type: object
      properties:
        type:
          type: string
          description: '`brand` brand term / `risk` content risk.'
        term:
          type: string
          description: Matched term (a substring of the line).
        reason:
          type: string
          description: Explanation.
    AdClonePricing:
      type: object
      description: Quote in credits. The whole object is empty when pricing lookup fails; the main flow is not blocked.
      properties:
        credit_per_second:
          type: integer
          format: int64
          description: Credits per second.
        total_credits:
          type: integer
          format: int64
          description: Total credits, including the number of videos.
    OpenAdCloneLine:
      type: object
      properties:
        id:
          type: string
          description: Line ID (for example `L1`). Send it back unchanged when editing.
        speaker:
          type: string
          description: Voice identity, matching `voices[].id`.
        text:
          type: string
          description: Original line text. **The only editable field.**
        start:
          type: number
          format: double
          description: Start time in the source video, in seconds (always 0 for now).
        end:
          type: number
          format: double
          description: End time in the source video, in seconds (always 0 for now).
        shot:
          type: integer
          format: int32
          description: Shot index.
        delivery:
          type: integer
          format: int32
          enum:
          - 0
          - 1
          - 2
          description: 'Delivery: `1` on-screen lip sync / `2` voice-over; `0` is treated as lip sync.'
        marks:
          type: array
          description: Brand / risk marks (always empty for now).
          items:
            $ref: '#/components/schemas/AdCloneTextMark'
    OpenAdCloneGetBody:
      type: object
      required:
      - clone_id
      properties:
        clone_id:
          type: string
          description: Draft ID.
    AdCloneRefType:
      type: integer
      format: int32
      enum:
      - 1
      - 2
      - 3
      - 4
      description: 'Reference type (**integer enum**):


        | Value | Meaning |

        |---|---|

        | `1` | product |

        | `2` | person |

        | `3` | scene |

        | `4` | other (not supported for single-segment clones yet; returns `10000`) |'
    OpenAdCloneDraft:
      type: object
      description: Editable draft, returned when `status=completed`.
      properties:
        clone_id:
          type: string
          description: Draft ID.
        duration:
          type: number
          format: double
          description: Source clip duration in seconds.
        lines:
          type: array
          items:
            $ref: '#/components/schemas/OpenAdCloneLine'
          description: Script lines.
        voices:
          type: array
          items:
            $ref: '#/components/schemas/OpenAdCloneVoice'
          description: Voice identities.
        slots:
          type: array
          items:
            $ref: '#/components/schemas/OpenAdCloneRefSlot'
          description: 'Reference slots: subjects detected in the video. Replace them with your own images via `edits.references`.'
        prompt:
          type: string
          description: Generation prompt. Override it entirely with `edits.prompt`.
        gen_options:
          $ref: '#/components/schemas/AdCloneGenOptions'
        pricing:
          $ref: '#/components/schemas/AdClonePricing'
        limits:
          $ref: '#/components/schemas/OpenAdCloneLimits'
        has_speech:
          type: boolean
          description: Whether the video has speech.
        has_person:
          type: boolean
          description: Whether a person appears on screen.
        audio_language:
          type: string
          description: Original audio language.
        bgm:
          type: integer
          format: int32
          enum:
          - 0
          - 1
          - 2
          description: 'Background music verdict: `0` not checked / `1` none / `2` detected (mind copyright). Always `0` for single-segment clones for now.'
    OpenAdCloneLineEdit:
      type: object
      required:
      - id
      properties:
        id:
          type: string
          description: Line ID.
        text:
          type: string
          description: New line text. Empty string = mute this line.
    AdCloneGenOptions:
      type: object
      description: Aspect ratio and resolution options.
      properties:
        aspect_ratios:
          type: array
          items:
            type: string
          description: Available aspect ratios.
        default_aspect_ratio:
          type: string
          description: Default aspect ratio.
        resolutions:
          type: array
          items:
            type: string
          description: Available resolutions.
        default_resolution:
          type: string
          description: Default resolution.
    OpenAdCloneRefInput:
      type: object
      required:
      - type
      - image_url
      properties:
        type:
          $ref: '#/components/schemas/AdCloneRefType'
        slot_id:
          type: string
          description: Slot ID to replace (binding hint).
        image_url:
          type: string
          description: Replacement image URL. Required.
        note:
          type: string
          description: Local description.
    ApiSuccessOpenWorkEnt:
      type: object
      required:
      - ret
      properties:
        ret:
          type: integer
          example: 1
        msg:
          type: string
        data:
          type: object
          properties:
            ent:
              $ref: '#/components/schemas/OpenWorkData'
    OpenAdClonePreviewBody:
      type: object
      required:
      - clone_id
      properties:
        clone_id:
          type: string
          description: Draft ID.
        edits:
          $ref: '#/components/schemas/OpenAdCloneEdits'
        video:
          $ref: '#/components/schemas/OpenAdCloneVideoSetting'
    OpenAdCloneGetData:
      type: object
      properties:
        status:
          type: string
          enum:
          - processing
          - completed
          - failed
          - not_found
          description: 'Draft status: `processing` analyzing / `completed` editable / `failed` failed (see `message`) / `not_found` missing, expired, or owned by another user.'
        stage:
          type: string
          description: 'Stage while `processing`: `queued` → `cutting` (only when clipping) → `analyzing`.'
        progress:
          type: integer
          format: int32
          description: Rough progress, 0-100.
        message:
          type: string
          description: Failure reason.
        draft:
          $ref: '#/components/schemas/OpenAdCloneDraft'
        matched_house_model:
          type: string
          description: Reserved. Always empty for now.
    ApiSuccessOpenAdClonePreviewEnt:
      type: object
      required:
      - ret
      properties:
        ret:
          type: integer
          example: 1
        msg:
          type: string
        data:
          type: object
          properties:
            ent:
              $ref: '#/components/schemas/OpenAdClonePreviewData'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: '在 [adsturbo.ai](https://adsturbo.ai) 控制台创建的密钥。调用时在请求头设置：`Authorization: Bearer <your_api_key>`。

        '