# Submit Lip Sync Task

> Video Generation

Submit video lip sync task, supports TTS mode and audio drive mode.

**Important Notes:**
- `audio_type` is required, must explicitly pass `"tts"` or `"audio"`
- TTS mode: `audio_man_id` and `text` are required
- Audio mode: `audio_file_id` is required

## Endpoint

`POST https://api.modelverse.cn/v1/tasks/submit`

## Request Body

## Responses

- **200** — Task submitted successfully
- **400** — 
- **401** — 

## OpenAPI Definition

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "ModelVerse Chanjing Lip Sync API",
    "description": "Chanjing lip sync API for synchronizing video character lip movements with audio/text.\n\n**Two Drive Modes Supported:**\n\n1. **TTS Mode** (`audio_type=\"tts\"`)\n   - Input text, system synthesizes speech to drive lip movements\n   - Required: `audio_man_id` + `text`\n   - Adjustable: speed (speech rate), pitch (tone)\n\n2. **Audio Drive Mode** (`audio_type=\"audio\"`)\n   - Upload audio file to directly drive lip movements\n   - Required: `audio_file_id`\n\n**Complete Workflow:**\n1. Upload video file → Get `video_file_id`\n2. (Audio mode) Upload audio file → Get `audio_file_id`\n3. (TTS mode) Query common voice list → Get `audio_man_id`\n4. Submit lip sync task → Get `task_id`\n5. Poll task status → Get result URL\n\n**Screen Sizes:**\n- `1080*1920` - Portrait 9:16 (default)\n- `1920*1080` - Landscape 16:9\n- `720*1280` - Portrait 9:16 (small size)\n",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://api.modelverse.cn",
      "description": "ModelVerse API Server"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/v1/chanjing/list_common_audio": {
      "get": {
        "summary": "List Common Voices",
        "description": "Get system-provided common voice list for TTS mode lip sync",
        "operationId": "listChanjingCommonAudio",
        "tags": [
          "Chanjing Lip Sync"
        ],
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "Page number, default 1",
            "schema": {
              "type": "integer",
              "default": 1
            }
          },
          {
            "name": "size",
            "in": "query",
            "required": false,
            "description": "Items per page, default 10",
            "schema": {
              "type": "integer",
              "default": 10
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Voice list retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CommonAudioListResponse"
                },
                "example": {
                  "object": "list",
                  "data": [
                    {
                      "id": "f9248f3b1b42447fb9282829321cfcf2",
                      "name": "Sales Assistant Xiaoyun",
                      "gender": "female",
                      "lang": "multilingual"
                    },
                    {
                      "id": "a1b2c3d4e5f678901234567890123456",
                      "name": "News Anchor",
                      "gender": "male",
                      "lang": "cn"
                    }
                  ],
                  "total": 91,
                  "page": 1,
                  "size": 10
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/v1/tasks/submit": {
      "post": {
        "summary": "Submit Lip Sync Task",
        "description": "Submit video lip sync task, supports TTS mode and audio drive mode.\n\n**Important Notes:**\n- `audio_type` is required, must explicitly pass `\"tts\"` or `\"audio\"`\n- TTS mode: `audio_man_id` and `text` are required\n- Audio mode: `audio_file_id` is required\n",
        "operationId": "submitChanjingLipSyncTask",
        "tags": [
          "Chanjing Lip Sync"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SubmitLipSyncRequest"
              },
              "examples": {
                "ttsMode": {
                  "summary": "TTS Mode",
                  "value": {
                    "model": "cicada-video-lip-sync",
                    "input": {
                      "video_file_id": "file_video_xxx",
                      "audio_type": "tts",
                      "audio_man_id": "f9248f3b1b42447fb9282829321cfcf2",
                      "text": "Hello, this is a lip sync test"
                    },
                    "parameters": {
                      "model_version": "0",
                      "speed": 1,
                      "pitch": 1,
                      "volume": 100,
                      "size": "1080*1920"
                    }
                  }
                },
                "audioMode": {
                  "summary": "Audio Drive Mode",
                  "value": {
                    "model": "cicada-video-lip-sync",
                    "input": {
                      "video_file_id": "file_video_xxx",
                      "audio_type": "audio",
                      "audio_file_id": "file_audio_xxx"
                    },
                    "parameters": {
                      "model_version": "0",
                      "volume": 80,
                      "size": "1080*1920"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Task submitted successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SubmitTaskResponse"
                },
                "example": {
                  "output": {
                    "task_id": "task_lip_abc123"
                  },
                  "request_id": "req_xxx"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/v1/tasks/status": {
      "get": {
        "summary": "Get Task Status",
        "description": "Query the execution status and result of a lip sync task.\n\n**Task Status:**\n- `Pending` - Task in progress (queued/generating)\n- `Success` - Task completed successfully\n- `Failure` - Task failed\n",
        "operationId": "getChanjingLipSyncTaskStatus",
        "tags": [
          "Chanjing Lip Sync"
        ],
        "parameters": [
          {
            "name": "task_id",
            "in": "query",
            "required": true,
            "description": "Task ID",
            "schema": {
              "type": "string"
            },
            "example": "task_lip_abc123"
          }
        ],
        "responses": {
          "200": {
            "description": "Task status retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TaskStatusResponse"
                },
                "examples": {
                  "pending": {
                    "summary": "In Progress",
                    "value": {
                      "output": {
                        "task_id": "task_lip_abc123",
                        "task_status": "Pending",
                        "submit_time": 1704067200
                      },
                      "request_id": "req_xxx"
                    }
                  },
                  "success": {
                    "summary": "Success",
                    "value": {
                      "output": {
                        "task_id": "task_lip_abc123",
                        "task_status": "Success",
                        "submit_time": 1704067200,
                        "finish_time": 1704067500,
                        "urls": [
                          "https://xxx.oss-cn-beijing.aliyuncs.com/lip_sync_video.mp4"
                        ]
                      },
                      "usage": {
                        "duration": 15
                      },
                      "request_id": "req_xxx"
                    }
                  },
                  "failure": {
                    "summary": "Failed",
                    "value": {
                      "output": {
                        "task_id": "task_lip_abc123",
                        "task_status": "Failure",
                        "submit_time": 1704067200,
                        "finish_time": 1704067500,
                        "error_message": "Video processing failed"
                      },
                      "request_id": "req_xxx"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "API Key authentication, format: Bearer {api_key}"
      }
    },
    "schemas": {
      "CommonAudioItem": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Voice ID"
          },
          "name": {
            "type": "string",
            "description": "Voice name"
          },
          "gender": {
            "type": "string",
            "description": "Gender",
            "enum": [
              "male",
              "female"
            ]
          },
          "lang": {
            "type": "string",
            "description": "Language"
          }
        }
      },
      "CommonAudioListResponse": {
        "type": "object",
        "properties": {
          "object": {
            "type": "string",
            "description": "Object type"
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CommonAudioItem"
            },
            "description": "Voice list"
          },
          "total": {
            "type": "integer",
            "description": "Total count"
          },
          "page": {
            "type": "integer",
            "description": "Current page number"
          },
          "size": {
            "type": "integer",
            "description": "Items per page"
          }
        }
      },
      "LipSyncInput": {
        "type": "object",
        "required": [
          "video_file_id",
          "audio_type"
        ],
        "properties": {
          "video_file_id": {
            "type": "string",
            "description": "Video file ID (obtained via file upload API)"
          },
          "audio_type": {
            "type": "string",
            "description": "Audio drive type",
            "enum": [
              "tts",
              "audio"
            ]
          },
          "audio_man_id": {
            "type": "string",
            "description": "System voice ID (required when audio_type=\"tts\")"
          },
          "audio_file_id": {
            "type": "string",
            "description": "Audio file ID (required when audio_type=\"audio\")"
          },
          "text": {
            "type": "string",
            "description": "Lip sync text content (required when audio_type=\"tts\")"
          }
        }
      },
      "LipSyncParameters": {
        "type": "object",
        "properties": {
          "model_version": {
            "type": "string",
            "description": "Model version",
            "enum": [
              "0",
              "1"
            ],
            "default": "0"
          },
          "size": {
            "type": "string",
            "description": "Screen size, format: width*height",
            "default": "1080*1920"
          },
          "speed": {
            "type": "number",
            "format": "float",
            "description": "Speech rate, range 0.5-2.0, only effective in TTS mode",
            "default": 1,
            "minimum": 0.5,
            "maximum": 2
          },
          "pitch": {
            "type": "number",
            "format": "float",
            "description": "Pitch, only effective in TTS mode",
            "default": 1
          },
          "volume": {
            "type": "integer",
            "description": "Volume, range 1-100",
            "default": 100,
            "minimum": 1,
            "maximum": 100
          }
        }
      },
      "SubmitLipSyncRequest": {
        "type": "object",
        "required": [
          "model",
          "input"
        ],
        "properties": {
          "model": {
            "type": "string",
            "description": "Model name",
            "enum": [
              "cicada-video-lip-sync"
            ]
          },
          "input": {
            "$ref": "#/components/schemas/LipSyncInput"
          },
          "parameters": {
            "$ref": "#/components/schemas/LipSyncParameters"
          }
        }
      },
      "SubmitTaskResponse": {
        "type": "object",
        "properties": {
          "output": {
            "type": "object",
            "properties": {
              "task_id": {
                "type": "string",
                "description": "Task ID"
              }
            }
          },
          "request_id": {
            "type": "string",
            "description": "Request ID"
          }
        }
      },
      "TaskStatusOutput": {
        "type": "object",
        "properties": {
          "task_id": {
            "type": "string",
            "description": "Task ID"
          },
          "task_status": {
            "type": "string",
            "description": "Task status",
            "enum": [
              "Pending",
              "Success",
              "Failure"
            ]
          },
          "submit_time": {
            "type": "integer",
            "description": "Submission time (Unix timestamp)"
          },
          "finish_time": {
            "type": "integer",
            "description": "Completion time (Unix timestamp)"
          },
          "urls": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Result file URL list"
          },
          "error_message": {
            "type": "string",
            "description": "Error message (returned when failed)"
          }
        }
      },
      "TaskUsage": {
        "type": "object",
        "properties": {
          "duration": {
            "type": "integer",
            "description": "Generated video duration in seconds"
          }
        }
      },
      "TaskStatusResponse": {
        "type": "object",
        "properties": {
          "output": {
            "$ref": "#/components/schemas/TaskStatusOutput"
          },
          "usage": {
            "$ref": "#/components/schemas/TaskUsage"
          },
          "request_id": {
            "type": "string",
            "description": "Request ID"
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "description": "Error code"
              },
              "message": {
                "type": "string",
                "description": "Error message"
              }
            }
          }
        }
      }
    },
    "responses": {
      "BadRequest": {
        "description": "Invalid request parameters",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "examples": {
              "missingAudioType": {
                "summary": "Missing audio_type",
                "value": {
                  "error": {
                    "code": "invalid_request",
                    "message": "input.audio_type is required for lip sync, must be 'tts' or 'audio'"
                  }
                }
              },
              "missingAudioManId": {
                "summary": "TTS mode missing audio_man_id",
                "value": {
                  "error": {
                    "code": "invalid_request",
                    "message": "input.audio_man_id is required when audio_type is 'tts'"
                  }
                }
              },
              "missingText": {
                "summary": "TTS mode missing text",
                "value": {
                  "error": {
                    "code": "invalid_request",
                    "message": "input.text is required when audio_type is 'tts'"
                  }
                }
              },
              "missingAudioFileId": {
                "summary": "Audio mode missing audio_file_id",
                "value": {
                  "error": {
                    "code": "invalid_request",
                    "message": "input.audio_file_id is required when audio_type is 'audio'"
                  }
                }
              }
            }
          }
        }
      },
      "Unauthorized": {
        "description": "Authentication failed",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "example": {
              "error": {
                "code": "unauthorized",
                "message": "missing token"
              }
            }
          }
        }
      },
      "NotFound": {
        "description": "Resource not found",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "example": {
              "error": {
                "code": "not_found",
                "message": "task not found"
              }
            }
          }
        }
      }
    }
  }
}
```