# Run an AI Avatar task.

AI tasks are asynchronous. Prefer webhook-based completion handling when the feature supports webhooks. Configure your webhook endpoint, verify webhook signatures, and use the received task_id to query the task result after a success or error notification. See the webhook integration guide for setup and verification details.

If webhooks are not supported for the feature, or if your integration cannot use webhooks, implement polling. After starting an AI task, keep polling the task status endpoint at the given polling_interval until the task status is either success or error.

Do not stop polling a running task for longer than the allowed polling window. If the task is not polled in time, the task may expire; a later status check can return InvalidTaskId even if processing finished, and the consumed units may still be charged.

Endpoint: POST /s2s/v2.0/task/ai-avatar
Security: BearerAuthenticationV2

## Request fields (application/json):

  - `template_id` (string, required)
    ID of the template. List predefined templates first, and use the id of a template.
    Example: "good_template_001"

  - `output_count` (integer, required)
    The number of generated images. It must be between 1 to 200.
    Example: 20

  - `body` (Run task with src file url (object) or Run task with src file ID (object), required) — one of:
    - Run task with src file url:
      - `src_file_url` (string, required)
        Url of the file to run task. The url should be publicly accessible.
        Example: "https://example.com/selfie.jpg"
    - Run task with src file ID:
      - `src_file_id` (string, required)
        ID of file to run task. File ID from upload file API.
        Example: "pfNK5PuRe0MrwLHcGA3DOmB1ahwfXTbYHjv+KoBIxbE="

## Response 200 fields (application/json):

  - `status` (integer)
    Response status
    Example: 200

  - `data` (object)

  - `data.task_id` (string)
    ID of this task. Task result is valid to query by this ID for 24 hours.
    Example: "grH0CvsgXuAIHLUzD0V1Ol34hoet3R1tvdbtiVHrDb6_UqCLKIejAIajwxrhOAfe"

## Response 400 fields (application/json):

  - `status` (integer)
    Response status
    Example: 400

  - `error` (string)
    Error message
    Example: "The operation could not be completed"

  - `error_code` (string)
    Error code:
  * InvalidParameters - Invalid request parameters
  * CreditInsufficiency - Insufficient unit to run
  * BadRequest - Unexpected request parameter
  * InvalidStyleGroup - Invalid style group id
  * InvalidStyle - Invalid style id
    Enum: "InvalidParameters", "CreditInsufficiency", "InvalidStyleGroup", "InvalidStyle", "BadRequest"

## Response 401 fields (application/json):

  - `status` (integer)
    Response status
    Example: 401

  - `error` (string)
    Example: "Invalid API key"

## Response 429 fields (application/json):

  - `status` (integer)
    Response status
    Example: 429

  - `error` (string)
    Example: "Too many requests"