Submit Task

post

https://api.topview.ai/v1/photo_avatar/task/submit

Submit an asynchronous Photo Avatar task. Returns a taskId; poll the Query Task 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.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Body Params

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

string

enum

Generation mode: avatar2 / avatar4 / avatar4Fast

Allowed:

scriptMode

string

enum

Script source: text for text-to-speech (requires ttsText, voiceId); audio to use an uploaded audio file (requires audioFileId)

Allowed:

ttsText

string

Voiceover script. Required when scriptMode=text

voiceId

string

Voice ID. Required when scriptMode=text

voiceModel

string

enum

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

Allowed:

voiceSettings

object

Advanced voice settings (effective only when scriptMode=text and voiceModel is provided, optional).

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

Headers

Topview-Uid

string

required

Defaults to <your-topview-uid>

User ID

Authorization

string

required

Defaults to Bearer <your-api-key>

API key, format: Bearer {apiKey}

Response

Language

Loading…

Response

Click Try It! to start a request and see the response here! Or choose an example:

application/json

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