---
title: "Query Task"
method: GET
path: "/v1/photo_avatar/task/query"
---

# Query Task

`GET /v1/photo_avatar/task/query`

Query the status and result of a Photo Avatar task by `taskId`. Recommended polling interval 3-5 seconds, timeout 5 minutes.

**Task status (status)**: `init` submitted and waiting; `running` processing; `success` succeeded; `fail` failed (`errorMsg` contains the reason).

**Credits**: `costCredit` is the credits consumed by this task (float). Settled on success, fully refunded on failure.

## Query parameters

- `taskId` string, required
- `needCloudFrontUrl` boolean

## Headers

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

## Response `200`

Query succeeded

- object
  - `code` string — Business status code, 200 on success
  - `message` string — Message
  - `result` object — Task query result
    - `taskId` string — Task ID
    - `status` 'init' | 'running' | 'success' | 'fail' — Task status
    - `errorMsg` string — Error message when the task fails
    - `costCredit` number, float — Credits consumed by the task (float)
    - `boardId` string — Associated Board ID (returned when the task comes from a Board)
    - `boardTaskId` string — Associated Board Task ID (returned when the task comes from a Board)
    - `finishedVideoCoverUrl` string — Cover URL of the generated video
    - `finishedVideoUrl` string — Generated video URL (with audio)
    - `aiAvatar` object — Avatar details
      - `aiavatarId` string — Avatar ID
      - `aiavatarName` string — Avatar name
      - `gender` string — Gender
      - `coverUrl` string — Avatar cover URL
      - `previewVideoUrl` string — Avatar preview video URL
      - `ethnicities` object[] — Avatar ethnicity info list
      - `voiceoverIdDefault` string — Default voice ID
      - `faceSquareConfig` object — Face bounding-box configuration
      - `type` 0 | 1 | 2 — Avatar type: 0-traditional avatar, 1-zero-shot avatar, 2-photo avatar

---

[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)