> ## Documentation Index
> Fetch the complete documentation index at: https://docs.navtalk.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Submit Video Compose Task

> Submit an asynchronous digital human video composition task.

**Input rules:**
- Exactly one of `audioFile`, `audioUrl`, or `textContent` is required
- Exactly one of `characterFile`, `characterUrl`, or `avatarId` is required
- If `textContent` is used, `avatarId` is required so the service can synthesize speech with the avatar's bound voice and provider



## OpenAPI

````yaml POST /api/open/v1/video-compose/submit
openapi: 3.1.0
info:
  title: NavTalk API
  description: NavTalk API for AI avatar management, file uploads, and video generation
  version: 1.0.0
servers:
  - url: https://api.navtalk.ai
    description: NavTalk Production Environment Server
  - url: https://qaapi.navtalk.ai
    description: NavTalk QA Environment Server
  - url: https://devapi.navtalk.ai
    description: NavTalk Development Environment Server
security:
  - navtalkLicenseAuth: []
paths:
  /api/open/v1/video-compose/submit:
    post:
      tags:
        - Video Compose
      summary: Submit Video Compose Task
      description: >-
        Submit an asynchronous digital human video composition task.


        **Input rules:**

        - Exactly one of `audioFile`, `audioUrl`, or `textContent` is required

        - Exactly one of `characterFile`, `characterUrl`, or `avatarId` is
        required

        - If `textContent` is used, `avatarId` is required so the service can
        synthesize speech with the avatar's bound voice and provider
      operationId: submitVideoComposeTask
      parameters: []
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/VideoComposeSubmitRequest'
            encoding:
              audioFile:
                contentType: audio/mpeg, audio/wav
              characterFile:
                contentType: >-
                  image/jpeg, image/png, image/webp, video/mp4, video/quicktime,
                  video/webm
      responses:
        '200':
          description: Video composition task submitted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VideoComposeSubmitResponse'
              example:
                code: 200
                message: SUCCESS
                data:
                  taskId: 6d7e24b7-412d-46ec-8d95-940099a3e979
                  status: Processing
        '400':
          description: Validation failed or submit error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NavtalkErrorResponse'
              examples:
                invalidAudioChoice:
                  summary: Invalid audio source selection
                  value:
                    code: 400
                    message: >-
                      Exactly one of audioFile, audioUrl, or textContent is
                      required
                invalidCharacterChoice:
                  summary: Invalid visual source selection
                  value:
                    code: 400
                    message: >-
                      Exactly one of characterFile, characterUrl, or avatarId is
                      required
                missingAvatarForTts:
                  summary: Avatar required for textContent
                  value:
                    code: 400
                    message: avatarId is required when textContent is used
      security:
        - navtalkLicenseAuth: []
components:
  schemas:
    VideoComposeSubmitRequest:
      type: object
      description: >-
        Multipart form data for submitting a video composition task. Exactly one
        audio source and exactly one visual source are required.
      properties:
        title:
          type: string
          description: Optional task title saved with the generation record.
          example: My first synthesis task
        audioFile:
          type: string
          format: binary
          description: >-
            Uploaded audio file. Use exactly one of `audioFile`, `audioUrl`, or
            `textContent`.
        audioUrl:
          type: string
          description: >-
            Public audio URL. Use exactly one of `audioFile`, `audioUrl`, or
            `textContent`.
          example: https://cdn.example.com/voice.mp3
        textContent:
          type: string
          description: >-
            Text to synthesize into speech. Use exactly one of `audioFile`,
            `audioUrl`, or `textContent`. Requires `avatarId`.
          example: Hello, welcome to NavTalk.
        characterFile:
          type: string
          format: binary
          description: >-
            Uploaded image or video visual source. Use exactly one of
            `characterFile`, `characterUrl`, or `avatarId`.
        characterUrl:
          type: string
          description: >-
            Public image or video visual source URL. Use exactly one of
            `characterFile`, `characterUrl`, or `avatarId`.
          example: https://cdn.example.com/source.mp4
        avatarId:
          type: string
          description: >-
            Existing trained avatar ID. Required when `textContent` is used. Use
            exactly one of `characterFile`, `characterUrl`, or `avatarId`.
          example: 4024d39983b4d4b488bba9377268fbac
        bboxShift:
          type: integer
          description: Optional face crop offset.
          default: 0
          example: 0
        extraMargin:
          type: integer
          description: Optional extra face margin.
          default: 10
          example: 10
        parsingMode:
          type: string
          description: Optional parsing mode.
          default: jaw
          example: jaw
        leftCheekWidth:
          type: integer
          description: Optional left cheek blend width.
          default: 90
          example: 90
        rightCheekWidth:
          type: integer
          description: Optional right cheek blend width.
          default: 90
          example: 90
    VideoComposeSubmitResponse:
      type: object
      properties:
        code:
          type: integer
          example: 200
        message:
          type: string
          example: SUCCESS
        data:
          $ref: '#/components/schemas/VideoComposeSubmitData'
    NavtalkErrorResponse:
      type: object
      properties:
        code:
          type: integer
          example: 400
        message:
          type: string
          example: Invalid license key
    VideoComposeSubmitData:
      type: object
      properties:
        taskId:
          type: string
          description: Generated task ID used for polling status.
          example: 6d7e24b7-412d-46ec-8d95-940099a3e979
        status:
          type: string
          enum:
            - Processing
          description: Initial task status after successful submission.
          example: Processing
  securitySchemes:
    navtalkLicenseAuth:
      type: apiKey
      in: header
      name: license
      description: NavTalk API license key (e.g. sk_navtalk_...)

````