Vyond Turbo API

openapi: 3.2.0
info:
  title: Vyond API Documentation Turbo API
  version: 1.1.0
  description: 'APIs for creating and tracking Turbo video generation tasks.


    Turbo lets you generate a video from a text prompt, optionally grounded on reference files (e.g. `.txt`,
    `.pdf`, `.docx`, `.pptx`). Submit a prompt to start a task, then poll the task by its ID to retrieve
    the status and, once completed, the download URL of the generated video.


    ## Webhook events


    Instead of polling, you can listen to webhook events to be notified when a Turbo task completes. Webhook
    events are always emitted for every task, so you can register a webhook subscription (owner type `user`)
    before the task completes, or supply a one-off `callbackWebhook` in the create request.


    | Event                        | Description                                                                                                         |

    | ---------------------------- | -------------------------------------------------------------------------------------------------------------------
    |

    | `turbo_generation.succeeded` | The Turbo video generation completed successfully. `data` contains
    `downloadUrl`, `creditConsumed` and `expiredAt`. |

    | `turbo_generation.failed`    | The Turbo video generation failed (or timed out). An `error.code`
    is included.                                      |


    The event `data` contains `id` (the task/thread ID), `status` and `turboThreadUrl`. Refer to [Webhook
    events](#tag/Webhook/Webhook-events) for the event body type definition, signature verification and
    sample payloads.

    '
tags:
- name: Turbo
  description: 'APIs for creating and tracking Turbo video generation tasks.


    Turbo lets you generate a video from a text prompt, optionally grounded on reference files (e.g. `.txt`,
    `.pdf`, `.docx`, `.pptx`). Submit a prompt to start a task, then poll the task by its ID to retrieve
    the status and, once completed, the download URL of the generated video.


    ## Webhook events


    Instead of polling, you can listen to webhook events to be notified when a Turbo task completes. Webhook
    events are always emitted for every task, so you can register a webhook subscription (owner type `user`)
    before the task completes, or supply a one-off `callbackWebhook` in the create request.


    | Event                        | Description                                                                                                         |

    | ---------------------------- | -------------------------------------------------------------------------------------------------------------------
    |

    | `turbo_generation.succeeded` | The Turbo video generation completed successfully. `data` contains
    `downloadUrl`, `creditConsumed` and `expiredAt`. |

    | `turbo_generation.failed`    | The Turbo video generation failed (or timed out). An `error.code`
    is included.                                      |


    The event `data` contains `id` (the task/thread ID), `status` and `turboThreadUrl`. Refer to [Webhook
    events](#tag/Webhook/Webhook-events) for the event body type definition, signature verification and
    sample payloads.

    '
paths:
  /rest/v1/turbo/:
    post:
      operationId: TurboController.createTurbo
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TurboCreateReqBody'
        description: TurboCreateReqBody
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TurboCreateResBody'
          description: Object with id = Turbo video generation task ID
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
          description: Bad Request - invalid request or files validation failures
        '401':
          description: Unauthorized - missing or invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
          description: Forbidden - missing required scope, invalid owner type or no Turbo license
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
          description: Unprocessable Entity - malware detected in uploaded files
        '429':
          description: Too Many Requests - rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
          description: Internal Server Error - unexpected error during Turbo generation creation
      summary: Create Turbo video generation
      tags:
      - Turbo
      security:
      - bearer: []
      description: Create a new Turbo video generation task from a prompt and optional reference files
  /rest/v1/turbo/{id}:
    get:
      operationId: TurboController.getTurbo
      parameters:
      - in: path
        name: id
        required: true
        schema:
          pattern: '[^\/#\?]+?'
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TurboGetResBody'
          description: Turbo video generation status details
        '401':
          description: Unauthorized - missing or invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
          description: Forbidden - missing required scope, invalid owner type or no Turbo license
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
          description: Not Found - Turbo generation task not found for the user
        '429':
          description: Too Many Requests - rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
          description: Internal Server Error - unexpected error while retrieving Turbo generation
      summary: Get Turbo video generation
      tags:
      - Turbo
      security:
      - bearer: []
      description: Get the status and download URL of a Turbo video generation task by ID
components:
  schemas:
    TurboCreateResBody:
      properties:
        id:
          type: string
          description: Turbo video generation task (thread) ID.
      type: object
      required:
      - id
    TurboGetResBody:
      properties:
        status:
          type: string
          enum:
          - queued
          - processing
          - completed
          - failed
          - cancelled
          description: Task status.
        turboThreadUrl:
          type: string
          description: Vyond web URL of the Turbo thread.
        creditConsumed:
          type: number
          description: Credits consumed by the generation.
        downloadUrl:
          format: url
          type: string
          description: Download URL of the generated video.
        expiredAt:
          pattern: \d{4}-[01]\d-[0-3]\dT[0-2]\d:[0-5]\d:[0-5]\d.\d+Z?
          type: string
          description: Expiration time of the download URL.
      type: object
      required:
      - status
      - turboThreadUrl
    TurboCreateReqBody:
      properties:
        prompt:
          maxLength: 10000
          type: string
          minLength: 1
          description: Prompt describing the video to generate.
        mode:
          type: string
          enum:
          - STILL_IMAGE
          - VIDEO_CLIP
          description: Video generation mode.
          default: STILL_IMAGE
        files:
          items:
            type: string
            format: binary
          maxItems: 3
          type: array
          description: Reference files, each with a maximum size of 104857600 bytes. Documents are limited
            to 100 pages. Only supported in `multipart/form-data` request.
        callbackWebhook:
          $ref: '#/components/schemas/CallbackWebhook'
          type: object
          description: Webhook for listening to webhook events of the Turbo video generation by Vyond.
      type: object
      required:
      - prompt
    CallbackWebhook:
      properties:
        url:
          format: url
          type: string
          description: Webhook URL. Must be in https protocol.
        secret:
          pattern: ^[0-9A-Za-z]{64}$
          type: string
          minLength: 64
          maxLength: 64
          description: Webhook secret for [signing the webhook event request by Vyond](#tag/Webhook/Verifying-Vyond-Signatures).
            If not provided, there is no signature in request. The secret should be in length 64 and contains
            only digits and English alphabets.
      type: object
      required:
      - url
    ApiErrorResponse:
      properties:
        err:
          type: string
          description: Error code identifying the specific error
        reason:
          type: string
          description: Additional reason describing why the error occurred
        message:
          type: string
          description: Error message, used as an alternative to reason for non-enumerated error messages
        scimType:
          type: string
          description: SCIM error type, present on SCIM 409 Conflict responses (e.g. uniqueness)
        details:
          items:
            $ref: '#/components/schemas/ValidationDetail'
          type: array
          description: Validation error details, present when err is REQUEST_VALIDATION_FAILED
      type: object
      required:
      - err
    ValidationDetail:
      properties:
        property:
          type: string
          description: The property that failed validation
        message:
          items:
            type: string
          type: array
          description: Validation error messages for the property
      type: object
      required:
      - property
      - message
  securitySchemes:
    bearer:
      type: http
      scheme: bearer