---
title: "Submit Task"
method: POST
path: "/v1/photo_avatar/task/submit"
---

# Submit Task

`POST /v1/photo_avatar/task/submit`

Submit an asynchronous Photo Avatar task. Returns a `taskId`; poll the [Query Task](/v1/photo_avatar/task/query) endpoint for the result.

**Script source (scriptMode)**:
- `text`: text-to-speech, requires `ttsText` and `voiceId`; `voiceModel` and `voiceSettings` are optional.
- `audio`: use an uploaded audio file, requires `audioFileId`.

**Credits**: billing type `photo_avatar4`, charged by generated video duration (seconds, rounded up); `avatar4`=0.1/s, `avatar4Fast`=0.06/s, `avatar2`=0.4/s; 50% off when `offPeak=true` and `mode=avatar4/avatar4Fast`. Settled on success, fully refunded on failure.

## Headers

- `Topview-Uid` string, required
- `Authorization` string, required

## Request body

- object
  - `avatarId` string — Avatar template ID (public or custom). Provide either avatarId or templateImageFileId to specify the avatar
  - `templateImageFileId` string — fileId of an uploaded model image (obtained from the upload endpoint). Alternative to avatarId
  - `mode` 'avatar2' | 'avatar4' | 'avatar4Fast' — Generation mode: `avatar2` / `avatar4` / `avatar4Fast`
  - `scriptMode` 'text' | 'audio' — Script source: `text` for text-to-speech (requires ttsText, voiceId); `audio` to use an uploaded audio file (requires audioFileId)
  - `ttsText` string — Voiceover script. Required when scriptMode=text
  - `voiceId` string — Voice ID. Required when scriptMode=text
  - `voiceModel` 'elevenlabs-v2.5' | 'elevenlabs-v3' | 'minimax-v2.5' — Voice model (effective only when scriptMode=text, optional, case-insensitive). If omitted, the backend default voice model is used; if provided, generation uses the selected model. - `elevenlabs-v2.5`: ElevenLabs V2.5 - `elevenlabs-v3`: ElevenLabs V3 - `minimax-v2.5`: MINIMAX V2.5
  - `voiceSettings` object — Advanced voice settings (effective only when scriptMode=text and voiceModel is provided, optional).
    - `volume` integer — Volume, range 0-200. Out-of-range values return an error (4000)
    - `stability` integer — Stability, range 0-100. Out-of-range values return an error (4000)
  - `audioFileId` string — Audio file fileId (obtained from the upload endpoint). Required when scriptMode=audio
  - `captionId` string — Caption ID (optional)
  - `customMotion` string — Motion/expression prompt (optional), max length 600
  - `saveCustomAiAvatar` string — Whether to save as a custom avatar (optional), true/false
  - `offPeak` boolean — Whether this is an off-peak task (optional), effective only when mode=avatar4/avatar4Fast. true means off-peak: 50% credits, fallback timeout 24 hours
  - `boardId` string — Associated Board ID (optional). When provided, the system creates a corresponding boardTask in aigc-backend; the response may return boardId and boardTaskIds
  - `noticeUrl` string — Callback URL invoked when the task completes (optional). When set, the response returns a noticeUuid

## Response `200`

Accepted (the task has been created and entered the processing pipeline; poll the query endpoint for the execution result)

- object
  - `code` string — Business status code, 200 on success
  - `message` string — Message
  - `result` object — Submission result (TaskPair)
    - `taskId` string — Task ID, used to poll the query endpoint
    - `status` 'init' | 'running' | 'success' | 'fail' — Acceptance status returned after submission; get the execution status (init/running/success/fail) via the query endpoint
    - `errorMsg` string — Error message on failure (may be present when acceptance fails)
    - `subTaskId` string — Sub-task ID (returned in some scenarios; usually not returned by this endpoint)
    - `boardTaskIds` string[] — List of Board sub-task IDs returned when associated with a Board
    - `boardId` string — Board ID returned when associated with a Board
    - `noticeUuid` string — UUID of the async callback notification (returned when noticeUrl is set in the request body)

---

[API](https://skmtc.net/topview/apis/image-character-swap-apis-editable-in-readme.md) · [All operations](https://skmtc.net/topview/apis/image-character-swap-apis-editable-in-readme/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/topview/image-character-swap-apis-editable-in-readme/revisions/83cd46ca7859/schema)