Create Task

curl --request POST \
--url 'https://openapi.akool.com/api/open/v5/characterSwap/create' \
--header 'x-api-key: <api-key>' \
--header 'Content-Type: application/json' \
--data '{
  "media_type": "image",
  "target_url": "https://example.com/scene.jpg",
  "model_name": "akool-premium-multi-person",
  "mappings": [
    {
      "source_url": "https://example.com/character.jpg",
      "source_bbox": [
        10,
        20,
        200,
        400
      ],
      "target_bbox": [
        100,
        50,
        350,
        600
      ]
    }
  ]
}'

curl --request POST \
--url 'https://openapi.akool.com/api/open/v5/characterSwap/create' \
--header 'x-api-key: <api-key>' \
--header 'Content-Type: application/json' \
--data '{
  "media_type": "video",
  "target_url": "https://example.com/source.mp4",
  "model_name": "akool-premium-multi-person",
  "analyze_id": "670000000000000000000001",
  "mappings": [
    {
      "obj_id": 0,
      "img_url": "https://example.com/character.jpg"
    }
  ],
  "resolution": "480p",
  "keep_original_sound": true,
  "prompt": "Preserve the source scene."
}'

curl --request POST \
--url 'https://openapi.akool.com/api/open/v5/characterSwap/create' \
--header 'x-api-key: <api-key>' \
--header 'Content-Type: application/json' \
--data '{
  "media_type": "video",
  "target_url": "https://example.com/source.mp4",
  "model_name": "kling-v3.0-pro/character-swap",
  "image": "https://example.com/character.jpg",
  "character_orientation": "video",
  "resolution": "720p",
  "keep_original_sound": true,
  "prompt": "Preserve the original movement.",
  "negative_prompt": "blur"
}'

{
  "code": 1000,
  "msg": "OK",
  "data": {
    "list": [
      {
        "_id": "670000000000000000000002",
        "status": 1,
        "media_type": "image",
        "model_name": "akool-premium-multi-person",
        "deduction_credit": 6,
        "create_time": 1791777600000,
        "task_id": ""
      }
    ],
    "errors": []
  }
}

{
  "code": 1000,
  "msg": "OK",
  "data": {
    "list": [
      {
        "_id": "670000000000000000000002",
        "status": 1,
        "media_type": "video",
        "model_name": "akool-premium-multi-person",
        "deduction_credit": 6,
        "create_time": 1791777600000,
        "task_id": ""
      }
    ],
    "errors": []
  }
}

{
  "code": 1000,
  "msg": "OK",
  "data": {
    "list": [
      {
        "_id": "670000000000000000000002",
        "status": 1,
        "media_type": "video",
        "model_name": "kling-v3.0-pro/character-swap",
        "deduction_credit": 6,
        "create_time": 1791777600000,
        "task_id": ""
      }
    ],
    "errors": []
  }
}

POST

api

open

characterSwap

create

curl --request POST \
--url 'https://openapi.akool.com/api/open/v5/characterSwap/create' \
--header 'x-api-key: <api-key>' \
--header 'Content-Type: application/json' \
--data '{
  "media_type": "image",
  "target_url": "https://example.com/scene.jpg",
  "model_name": "akool-premium-multi-person",
  "mappings": [
    {
      "source_url": "https://example.com/character.jpg",
      "source_bbox": [
        10,
        20,
        200,
        400
      ],
      "target_bbox": [
        100,
        50,
        350,
        600
      ]
    }
  ]
}'

curl --request POST \
--url 'https://openapi.akool.com/api/open/v5/characterSwap/create' \
--header 'x-api-key: <api-key>' \
--header 'Content-Type: application/json' \
--data '{
  "media_type": "video",
  "target_url": "https://example.com/source.mp4",
  "model_name": "akool-premium-multi-person",
  "analyze_id": "670000000000000000000001",
  "mappings": [
    {
      "obj_id": 0,
      "img_url": "https://example.com/character.jpg"
    }
  ],
  "resolution": "480p",
  "keep_original_sound": true,
  "prompt": "Preserve the source scene."
}'

curl --request POST \
--url 'https://openapi.akool.com/api/open/v5/characterSwap/create' \
--header 'x-api-key: <api-key>' \
--header 'Content-Type: application/json' \
--data '{
  "media_type": "video",
  "target_url": "https://example.com/source.mp4",
  "model_name": "kling-v3.0-pro/character-swap",
  "image": "https://example.com/character.jpg",
  "character_orientation": "video",
  "resolution": "720p",
  "keep_original_sound": true,
  "prompt": "Preserve the original movement.",
  "negative_prompt": "blur"
}'

{
  "code": 1000,
  "msg": "OK",
  "data": {
    "list": [
      {
        "_id": "670000000000000000000002",
        "status": 1,
        "media_type": "image",
        "model_name": "akool-premium-multi-person",
        "deduction_credit": 6,
        "create_time": 1791777600000,
        "task_id": ""
      }
    ],
    "errors": []
  }
}

{
  "code": 1000,
  "msg": "OK",
  "data": {
    "list": [
      {
        "_id": "670000000000000000000002",
        "status": 1,
        "media_type": "video",
        "model_name": "akool-premium-multi-person",
        "deduction_credit": 6,
        "create_time": 1791777600000,
        "task_id": ""
      }
    ],
    "errors": []
  }
}

{
  "code": 1000,
  "msg": "OK",
  "data": {
    "list": [
      {
        "_id": "670000000000000000000002",
        "status": 1,
        "media_type": "video",
        "model_name": "kling-v3.0-pro/character-swap",
        "deduction_credit": 6,
        "create_time": 1791777600000,
        "task_id": ""
      }
    ],
    "errors": []
  }
}

POST https://openapi.akool.com/api/open/v5/characterSwap/create

Request Headers

Parameter	Value	Description
x-api-key	API Key	API key used for authorization. Authorization takes precedence when both headers are supplied.
Authorization	Bearer `{token}`	Get Token.
Content-Type	application/json	Required for JSON requests.

Choose the matching request example: Image replacement, Akool video replacement, or Kling video replacement. analyze_id is required only for Akool video. obj_id and img_url belong to mappings[], not analyze_id. Kling uses image and target_url; image replacement uses source_url, source_bbox and target_bbox inside mappings[].

Body Attributes

Parameter	Type	Required	Description
media_type	String	true	`image` or `video`.
target_url	String	true	Public source scene image or video URL.
model_name	String	false	Defaults to `akool-premium-multi-person`. Get supported IDs from the models endpoint.
mappings	Array	conditional	Image: 1–2 mappings with `source_url`, `source_bbox`, and `target_bbox`. Akool video: 1–5 mappings with `obj_id` and `img_url`.
mappings[].source_url	String	image	Reference character image URL.
mappings[].source_bbox	Array	image	Reference face bounding box `[x1,y1,x2,y2]` in original-image pixels.
mappings[].target_bbox	Array	image	Target face bounding box `[x1,y1,x2,y2]` in original-image pixels. The same target box cannot be mapped twice.
mappings[].obj_id	Integer	Akool video	Person ID from the analysis result.
mappings[].img_url	String	Akool video	Reference character image URL.
analyze_id	String	Akool video only	Completed person analysis _id for the identical source video URL; not needed for image or Kling video.
character_orientation	String	false	Kling video: `image` or `video`; defaults to `video`.
image	String	Kling video	Reference character URL for a single-person Kling replacement.
resolution	String	false	Image: automatic. Akool video: 480p or 720p. Kling: choose from the model’s supported values.
keep_original_sound	Boolean	false	Keep source video audio; defaults to true.
prompt	String	false	Video generation instructions: up to 2500 characters for Kling and 5000 for Akool. Overlong prompts are rejected before generation. Image replacement generates its instructions from mappings.
negative_prompt	String	false	Optional Kling video negative instructions, up to 5000 characters.
webhookUrl	String	false	Optional final-state callback URL; follow the Webhook guide.

Response Attributes

Parameter	Type	Description
code	Integer	Business response code; `1000` means the request succeeded.
msg	String	Response message.
data	Object	Batch creation result.
- list	Array	Successfully created tasks.
— _id	String	Task ID to use for result polling.
— task_id	String	Downstream algorithm/provider task ID; may be empty until submission. Use `_id`, not this value, for task-detail queries. It may change between workflow stages.
— status	Integer	Initial task status.
— media_type	String	Output media type: image or video.
— model_name	String	Selected model ID.
— deduction_credit	Number	Task billing amount.
— create_time	Number	Creation timestamp in milliseconds.
- errors	Array	Inputs that could not create a task. Inspect this array even when code is 1000.
— index	Integer	Zero-based plan/input index that failed during submission.
— error	String	Submission failure description.

Request examples

Select a scenario below or in the request sample to view matching request and response examples. URLs, IDs and model selections are illustrative; replace them with accessible resources, completed analyses and models available to your account. Response credit values are examples, not price quotations. Poll each returned _id until completion.

Image
Akool video
Kling video

Body

{
  "media_type": "image",
  "target_url": "https://example.com/scene.jpg",
  "model_name": "akool-premium-multi-person",
  "mappings": [
    {
      "source_url": "https://example.com/character.jpg",
      "source_bbox": [
        10,
        20,
        200,
        400
      ],
      "target_bbox": [
        100,
        50,
        350,
        600
      ]
    }
  ]
}

Body

{
  "media_type": "video",
  "target_url": "https://example.com/source.mp4",
  "model_name": "akool-premium-multi-person",
  "analyze_id": "670000000000000000000001",
  "mappings": [
    {
      "obj_id": 0,
      "img_url": "https://example.com/character.jpg"
    }
  ],
  "resolution": "480p",
  "keep_original_sound": true,
  "prompt": "Preserve the source scene."
}

Body

{
  "media_type": "video",
  "target_url": "https://example.com/source.mp4",
  "model_name": "kling-v3.0-pro/character-swap",
  "image": "https://example.com/character.jpg",
  "character_orientation": "video",
  "resolution": "720p",
  "keep_original_sound": true,
  "prompt": "Preserve the original movement.",
  "negative_prompt": "blur"
}

For input limits, billing, callbacks, and error codes, see the Character Swap V5 overview.

curl --request POST \
--url 'https://openapi.akool.com/api/open/v5/characterSwap/create' \
--header 'x-api-key: <api-key>' \
--header 'Content-Type: application/json' \
--data '{
  "media_type": "image",
  "target_url": "https://example.com/scene.jpg",
  "model_name": "akool-premium-multi-person",
  "mappings": [
    {
      "source_url": "https://example.com/character.jpg",
      "source_bbox": [
        10,
        20,
        200,
        400
      ],
      "target_bbox": [
        100,
        50,
        350,
        600
      ]
    }
  ]
}'

curl --request POST \
--url 'https://openapi.akool.com/api/open/v5/characterSwap/create' \
--header 'x-api-key: <api-key>' \
--header 'Content-Type: application/json' \
--data '{
  "media_type": "video",
  "target_url": "https://example.com/source.mp4",
  "model_name": "akool-premium-multi-person",
  "analyze_id": "670000000000000000000001",
  "mappings": [
    {
      "obj_id": 0,
      "img_url": "https://example.com/character.jpg"
    }
  ],
  "resolution": "480p",
  "keep_original_sound": true,
  "prompt": "Preserve the source scene."
}'

curl --request POST \
--url 'https://openapi.akool.com/api/open/v5/characterSwap/create' \
--header 'x-api-key: <api-key>' \
--header 'Content-Type: application/json' \
--data '{
  "media_type": "video",
  "target_url": "https://example.com/source.mp4",
  "model_name": "kling-v3.0-pro/character-swap",
  "image": "https://example.com/character.jpg",
  "character_orientation": "video",
  "resolution": "720p",
  "keep_original_sound": true,
  "prompt": "Preserve the original movement.",
  "negative_prompt": "blur"
}'

{
  "code": 1000,
  "msg": "OK",
  "data": {
    "list": [
      {
        "_id": "670000000000000000000002",
        "status": 1,
        "media_type": "image",
        "model_name": "akool-premium-multi-person",
        "deduction_credit": 6,
        "create_time": 1791777600000,
        "task_id": ""
      }
    ],
    "errors": []
  }
}

{
  "code": 1000,
  "msg": "OK",
  "data": {
    "list": [
      {
        "_id": "670000000000000000000002",
        "status": 1,
        "media_type": "video",
        "model_name": "akool-premium-multi-person",
        "deduction_credit": 6,
        "create_time": 1791777600000,
        "task_id": ""
      }
    ],
    "errors": []
  }
}

{
  "code": 1000,
  "msg": "OK",
  "data": {
    "list": [
      {
        "_id": "670000000000000000000002",
        "status": 1,
        "media_type": "video",
        "model_name": "kling-v3.0-pro/character-swap",
        "deduction_credit": 6,
        "create_time": 1791777600000,
        "task_id": ""
      }
    ],
    "errors": []
  }
}

Authorizations

x-api-key

string

header

required

Body

application/json

Image
Akool video
Kling video

media_type

enum<string>

required

Available options:

image

target_url

string<uri>

required

Public source scene image or video URL.

mappings

object[]

required

Image: 1–2 mappings with source_url, source_bbox, and target_bbox. Akool video: 1–5 mappings with obj_id and img_url.

Required array length: 1 - 2 elements

Show child attributes

model_name

enum<string>

Available options:

akool-premium-multi-person

analyze_id

string

Required only for Akool video: completed person analysis _id for the identical source video URL. Image and Kling video do not need it.

Pattern: ^[a-fA-F0-9]{24}$

character_orientation

enum<string>

Kling video: image or video; defaults to video.

Available options:

image,

video

image

string<uri>

Required only for Kling video: public reference-character image URL. target_url is the source video; both must contain a single person.

resolution

string

Image: selected automatically. Akool video: 480p or 720p, using the model default or 480p fallback. Kling video: select a supported value from models (720p fallback).

keep_original_sound

boolean

Keep source video audio; defaults to true. Applies to video requests.

prompt

string

Video generation instructions, up to 5000 characters. Image replacement generates its instructions from mappings.

Maximum string length: 5000

webhookUrl

string<uri>

Optional final-state callback URL; follow the Webhook guide.

negative_prompt

string

Optional Kling video negative instructions.

Maximum string length: 5000

Response

200 - application/json

Business response. Code 1000 means the request succeeded; inspect task status or data.errors for generation/submission outcomes.

code

integer

Example:

1000

msg

string

Example:

"OK"

data

object

Show child attributes

Authentication

Face Swap

Streaming Avatar

Talking Photo

Video Translation

Face Detection

Swap Studio V5

Image Generate

Image to Video

AI Tools Suite

Request examples

Authorizations

Body

Response

​Request examples

Authorizations

Body

Response

Request examples