v1

latestOpenAPI 3.0.32026-07-241112213.6 KB

Submit Task

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.

post/v1/photo_avatar/task/submit

Headers

Topview-Uidstring required

User ID

Authorizationstring required

API key, format: Bearer {apiKey}

Request body

avatarIdstring

Avatar template ID (public or custom). Provide either avatarId or templateImageFileId to specify the avatar

templateImageFileIdstring

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)

ttsTextstring

Voiceover script. Required when scriptMode=text

voiceIdstring

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

audioFileIdstring

Audio file fileId (obtained from the upload endpoint). Required when scriptMode=audio

captionIdstring

Caption ID (optional)

customMotionstring

Motion/expression prompt (optional), max length 600

saveCustomAiAvatarstring

Whether to save as a custom avatar (optional), true/false

offPeakboolean

Whether this is an off-peak task (optional), effective only when mode=avatar4/avatar4Fast. true means off-peak: 50% credits, fallback timeout 24 hours

boardIdstring

Associated Board ID (optional). When provided, the system creates a corresponding boardTask in aigc-backend; the response may return boardId and boardTaskIds

noticeUrlstring

Callback URL invoked when the task completes (optional). When set, the response returns a noticeUuid

Example request

{
  "avatarId": "avatar-001",
  "templateImageFileId": "file-123",
  "mode": "avatar4",
  "scriptMode": "text",
  "ttsText": "Hi everyone, I am a digital avatar.",
  "voiceId": "voice-888",
  "voiceModel": "elevenlabs-v3",
  "voiceSettings": {
    "volume": 100,
    "stability": 50
  },
  "audioFileId": "file-audio-001",
  "captionId": "caption-001",
  "customMotion": "smile, wave",
  "saveCustomAiAvatar": "false",
  "offPeak": true,
  "boardId": "board-12345",
  "noticeUrl": "https://example.com/topview/callback"
}

Response

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

codestring

Business status code, 200 on success

messagestring

Message

Example response

{
  "code": "200",
  "message": "Success",
  "result": {
    "taskId": "task-123456",
    "status": "init"
  }
}