> ## Documentation Index
> Fetch the complete documentation index at: https://docs.akool.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Character Swap V5 API Overview

> Models, workflow, input limits, and billing for Character Swap V5.

<Info>
  Replace characters in an image or video with reference characters.

  For Akool video replacement, analyze the video first, then pass the completed analysis ID and person mappings. For Kling video replacement, provide `image` and the video in `target_url`; the scene must contain a single person. Character replacement preserves the scene while changing its character.
</Info>

## API Endpoints

* [List Models](/ai-tools-suite/swap-studio/character-swap-v5/models) — `GET`
* [Create Task](/ai-tools-suite/swap-studio/character-swap-v5/create) — `POST`
* [Get Task Result](/ai-tools-suite/swap-studio/character-swap-v5/get-result) — `GET`
* [Analyze Source Material](/ai-tools-suite/swap-studio/character-swap-v5/analyze) — `POST`
* [Get Analysis Result](/ai-tools-suite/swap-studio/character-swap-v5/analysis-result) — `GET`

## Getting Started

1. List the models available for this feature.
2. If required by your model, analyze the source and wait for the analysis to complete.
3. Create a task using the model-specific parameters.
4. Poll task results or receive the final webhook notification.

## Billing

Generation is priced using the selected model configuration and your account/team pricing. Image generation is charged per task; video pricing also depends on duration and resolution. Credits are reserved before queueing and finalized through the existing generation billing flow. Creation errors do not produce a billable task. Read `deduction_credit` per created task rather than treating the sample value as a price quotation. AIGC website membership discounts do not automatically apply to OpenAPI; account and team pricing can change the final credit amount.

## Response Code Description

<Note>A business code other than 1000 indicates that the API request failed. For batch creation, also check data.errors.</Note>

| **Code** | **Description** |
| - | - |
| 1000 | Request succeeded. Inspect task status for generation results. |
| 1003 | Invalid input, unsupported model/parameters, unavailable feature, or task/analysis not found. |
| 1008 | Content does not exist (general platform error). |
| 1009 | Permission denied. |
| 1101 | Invalid or expired authorization. |
| 1102 | Authorization is missing. |
| 1104 | Insufficient credits. |

See the [Webhook guide](/ai-tools-suite/webhook) for callback verification and the [complete error list](/ai-tools-suite/error-code) for other account errors.

## Callback

If `webhookUrl` is supplied, final task notifications follow the existing encrypted and signed [Webhook format](/ai-tools-suite/webhook). After verification and decryption, read `_id`, `status`, `type`, and `url`. Fetch task detail to obtain operation-specific fields, including additional hairstyle views. Return HTTP 200 to acknowledge delivery.

## Input limits

Akool video replacement supports 3–20 seconds and 1–5 distinct analyzed people. Kling character replacement supports 3–30 seconds; image orientation supports at most 10 seconds. Image replacement accepts 1–2 face mappings and selects output size automatically from the target image.

For Kling replacement, the selected character model and its configured motion model must both be available to your account. Resolution must be compatible with the configured motion model.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.