--- updatedAt: 2026-06-26T10:28:40.000Z agentTools: projectIndex: https://docs.topview.ai/llms.txt --- # Submit Task 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. # OpenAPI definition ```json { "openapi": "3.0.0", "info": { "version": "1.0.0", "title": "Photo Avatar - Submit Task" }, "servers": [ { "url": "https://api.topview.ai" } ], "paths": { "/v1/photo_avatar/task/submit": { "post": { "summary": "Submit Task", "description": "Submit an asynchronous Photo Avatar task. Returns a `taskId`; poll the [Query Task](/v1/photo_avatar/task/query) endpoint for the result.\n\n**Script source (scriptMode)**:\n- `text`: text-to-speech, requires `ttsText` and `voiceId`; `voiceModel` and `voiceSettings` are optional.\n- `audio`: use an uploaded audio file, requires `audioFileId`.\n\n**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.", "operationId": "submitPhotoAvatarTaskEn", "parameters": [ { "in": "header", "name": "Topview-Uid", "schema": { "type": "string", "default": "" }, "required": true, "description": "User ID" }, { "in": "header", "name": "Authorization", "schema": { "type": "string", "default": "Bearer " }, "required": true, "description": "API key, format: Bearer {apiKey}" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "avatarId": { "type": "string", "description": "Avatar template ID (public or custom). Provide either avatarId or templateImageFileId to specify the avatar", "example": "avatar-001" }, "templateImageFileId": { "type": "string", "description": "fileId of an uploaded model image (obtained from the upload endpoint). Alternative to avatarId", "example": "file-123" }, "mode": { "type": "string", "description": "Generation mode: `avatar2` / `avatar4` / `avatar4Fast`", "enum": [ "avatar2", "avatar4", "avatar4Fast" ], "example": "avatar4" }, "scriptMode": { "type": "string", "description": "Script source: `text` for text-to-speech (requires ttsText, voiceId); `audio` to use an uploaded audio file (requires audioFileId)", "enum": [ "text", "audio" ], "example": "text" }, "ttsText": { "type": "string", "description": "Voiceover script. Required when scriptMode=text", "example": "Hi everyone, I am a digital avatar." }, "voiceId": { "type": "string", "description": "Voice ID. Required when scriptMode=text", "example": "voice-888" }, "voiceModel": { "type": "string", "description": "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.\n- `elevenlabs-v2.5`: ElevenLabs V2.5\n- `elevenlabs-v3`: ElevenLabs V3\n- `minimax-v2.5`: MINIMAX V2.5", "enum": [ "elevenlabs-v2.5", "elevenlabs-v3", "minimax-v2.5" ], "example": "elevenlabs-v3" }, "voiceSettings": { "type": "object", "description": "Advanced voice settings (effective only when scriptMode=text and voiceModel is provided, optional).", "properties": { "volume": { "type": "integer", "minimum": 0, "maximum": 200, "description": "Volume, range 0-200. Out-of-range values return an error (4000)", "example": 100 }, "stability": { "type": "integer", "minimum": 0, "maximum": 100, "description": "Stability, range 0-100. Out-of-range values return an error (4000)", "example": 50 } } }, "audioFileId": { "type": "string", "description": "Audio file fileId (obtained from the upload endpoint). Required when scriptMode=audio", "example": "file-audio-001" }, "captionId": { "type": "string", "description": "Caption ID (optional)", "example": "caption-001" }, "customMotion": { "type": "string", "description": "Motion/expression prompt (optional), max length 600", "example": "smile, wave" }, "saveCustomAiAvatar": { "type": "string", "description": "Whether to save as a custom avatar (optional), true/false", "example": "false" }, "offPeak": { "type": "boolean", "description": "Whether this is an off-peak task (optional), effective only when mode=avatar4/avatar4Fast. true means off-peak: 50% credits, fallback timeout 24 hours", "example": true }, "boardId": { "type": "string", "description": "Associated Board ID (optional). When provided, the system creates a corresponding boardTask in aigc-backend; the response may return boardId and boardTaskIds", "example": "board-12345" }, "noticeUrl": { "type": "string", "description": "Callback URL invoked when the task completes (optional). When set, the response returns a noticeUuid", "example": "https://example.com/topview/callback" } } }, "examples": { "text-mode": { "summary": "Text-to-speech (with voice model)", "value": { "avatarId": "avatar-001", "mode": "avatar4", "scriptMode": "text", "ttsText": "Hi everyone, I am a digital avatar.", "voiceId": "voice-888", "voiceModel": "elevenlabs-v3", "voiceSettings": { "volume": 100, "stability": 50 }, "offPeak": true } }, "audio-mode": { "summary": "Use an uploaded audio file", "value": { "avatarId": "avatar-001", "mode": "avatar4", "scriptMode": "audio", "audioFileId": "file-audio-001" } } } } } }, "responses": { "200": { "description": "Accepted (the task has been created and entered the processing pipeline; poll the query endpoint for the execution result)", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "example": "200", "description": "Business status code, 200 on success" }, "message": { "type": "string", "example": "Success", "description": "Message" }, "result": { "type": "object", "description": "Submission result (TaskPair)", "properties": { "taskId": { "type": "string", "description": "Task ID, used to poll the query endpoint", "example": "task-123456" }, "status": { "type": "string", "description": "Acceptance status returned after submission; get the execution status (init/running/success/fail) via the query endpoint", "enum": [ "init", "running", "success", "fail" ], "example": "init" }, "errorMsg": { "type": "string", "description": "Error message on failure (may be present when acceptance fails)" }, "subTaskId": { "type": "string", "description": "Sub-task ID (returned in some scenarios; usually not returned by this endpoint)" }, "boardTaskIds": { "type": "array", "items": { "type": "string" }, "description": "List of Board sub-task IDs returned when associated with a Board" }, "boardId": { "type": "string", "description": "Board ID returned when associated with a Board" }, "noticeUuid": { "type": "string", "description": "UUID of the async callback notification (returned when noticeUrl is set in the request body)" } } } } }, "example": { "code": "200", "message": "Success", "result": { "taskId": "task-123456", "status": "init", "boardId": "board-12345", "boardTaskIds": [ "bt-12345" ] } } } } } } } } }, "x-readme": { "explorer-enabled": true, "proxy-enabled": true } } ```