Kling 3.0 Motion Control

Kling 3.0 Motion Control transfers the motion from a reference video onto the character in a reference image — preserving the character's identity, appearance, and background — to produce a new video where your character performs the reference action. Outputs are 720P or 1080P, up to 30 seconds.

Models

Pricing

Billed per second of output video (= reference video length) × resolution:

The reference video duration is probed automatically on the server for billing — if probing fails (URL unreachable or unsupported format), task creation returns a 400 error and no credits are charged. Credits are pre-charged when the task is created; failed tasks are refunded automatically.

Create Task

POST https://api.aivideoapi.ai/v1/videos/generations

Request Body

Input Parameters

The duration parameter is not supported: the output video length follows the reference video, capped by character_orientation (image ≤ 10s, video ≤ 30s). All media must be public HTTP(S) URLs.

Examples

Basic motion transfer

curl -X POST https://api.aivideoapi.ai/v1/videos/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-v3-motion-control",
    "callback_url": "https://your-server.com/webhook",
    "input": {
      "input_urls": ["https://example.com/character.png"],
      "video_urls": ["https://example.com/reference-motion.mp4"],
      "character_orientation": "video",
      "mode": "720p"
    }
  }'

1080P with a prompt

curl -X POST https://api.aivideoapi.ai/v1/videos/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-v3-motion-control",
    "callback_url": "https://your-server.com/webhook",
    "input": {
      "input_urls": ["https://example.com/dancer.png"],
      "video_urls": ["https://example.com/dance-clip.mp4"],
      "character_orientation": "image",
      "mode": "1080p",
      "prompt": "The character performs the dance smoothly with no distortion"
    }
  }'

Response

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "8b6a5162-5c91-4a42-8e80-4c8ef5486f24"
  }
}

Query Task

curl https://api.aivideoapi.ai/v1/tasks/{taskId} \
  -H "Authorization: Bearer sk-your-api-key"

Status transitions: pending -> processing -> completed or failed.

If the task fails, pre-charged credits are refunded automatically.

Callback

Pass callback_url when creating the task and the system will POST to your URL when the task completes or fails. See Callback Guide for request headers and the retry strategy.

On completion

{
  "id": "8b6a5162-5c91-4a42-8e80-4c8ef5486f24",
  "status": "completed",
  "model": "kling-v3-motion-control",
  "created_at": 1781136227,
  "completed_at": 1781136589,
  "output": {
    "urls": [
      "https://file.aivideoapi.ai/videos/2026/06/15/abc.mp4"
    ],
    "metadata": {
      "model": "kling-3.0/motion-control"
    }
  }
}

On failure

{
  "id": "57c8772c-f834-46f3-9b7d-81f92e104050",
  "status": "failed",
  "model": "kling-v3-motion-control",
  "created_at": 1781136227,
  "error": {
    "code": "upstream_error",
    "message": "Video generation failed"
  }
}

Important Notes

• Return a 2xx status code as soon as possible after receiving the callback (within 3 seconds recommended). Non-2xx responses or timeouts (10 seconds) trigger retries — up to 3 attempts, spaced 3 and 10 minutes apart.
• Use X-Task-Id for idempotent handling on your side to avoid duplicate records for the same task.
• The authoritative task state is always GET /v1/tasks/{taskId}; if all 3 callbacks fail you can still poll as a fallback.

Error Codes

When a request fails, the API returns a JSON error response:

{
  "error": {
    "code": "insufficient_credits",
    "message": "Your credit balance is too low. Please top up.",
    "type": "billing_error"
  }
}

Error Reference

Common Scenarios

invalid_request (400)

Returned when required fields are missing or invalid.

{
  "error": {
    "code": "invalid_request",
    "message": "'model' is required.",
    "type": "invalid_request_error"
  }
}

insufficient_credits (402)

Your balance is too low. Check your balance with GET /v1/credits and top up in Dashboard > Billing.

invalid_api_key (401)

Possible causes:

• The key does not start with sk-
• The key has been disabled or deleted
• The user account has been banned

upstream_error (503)

The upstream AI provider returned an error. This may happen when:

• The input contains sensitive or prohibited content
• The provider is temporarily unavailable
• The request parameters are not supported by the provider

Credits are automatically refunded when a task fails due to upstream errors.