# Kling 3.0 Motion Control

使用此模型提交视频生成任务，再通过返回的任务 ID 查询结果。

模型 ID `official-kling-v3-motion-control`

## 快速开始

创建 [API 密钥](/me?section=api-keys)并设置 `I2V_API_KEY`。每个新任务设置一个 `IDEMPOTENCY_KEY`，重试同一次提交时复用原幂等键和请求体。

### 提交任务

`POST https://api.i2v.ai/api/v1/jobs/createTask`

```bash
curl "https://api.i2v.ai/api/v1/jobs/createTask" \
  -H "Authorization: Bearer $I2V_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -d '{
  "model": "official-kling-v3-motion-control",
  "inputs": {
    "prompt": "A calm lake at sunrise",
    "resolution": "720p",
    "duration": 5
  }
}'
```

HTTP 200 表示任务已受理。保存返回的 `taskId`。

```json
{"taskId":"YOUR_TASK_ID"}
```

### 查询结果

```bash
curl "https://api.i2v.ai/api/v1/jobs/recordInfo?taskId=YOUR_TASK_ID" \
  -H "Authorization: Bearer $I2V_API_KEY"
```

将 `YOUR_TASK_ID` 替换为返回的任务 ID。状态为 `waiting` 或 `generating` 时退避轮询。`success` 时读取 `output[].url`，`fail` 时检查 `error`。

## 请求参数

模型输入放在 `inputs` 对象中。素材 URL 需要可公开访问。必需素材及参数组合取决于具体生成模式。

| 字段 | 类型 | 必填 | 默认值 | 说明 |
| --- | --- | --- | --- | --- |
| `inputs.prompt` | string | 否 | — | 可选的表演或画面引导。 上限 2500 字符. |
| `inputs.resolution` | string | 否 | 720p | 输出分辨率。 可选值 `720p`, `1080p`. |
| `inputs.duration` | number | 否 | 5 | 视频时长，单位为秒。 可选值 `3`, `4`, `5`, `6`, `7`, `8`, `9`, `10`, `11`, `12`, `13`, `14`, `15`. |
| `inputs.urls` | string[] | 否 | — | 关键帧图片地址，前两项分别为首帧和尾帧。 上限 2 个 URL. |
| `inputs.referenceImageUrls` | string[] | 否 | — | 恰好一张角色图，脸部、肩部与躯干需清晰可见。 上限 1 个 URL. |
| `inputs.videoUrl` | string | 否 | — | 动作参考视频，输出时长跟随该视频。 |

### 请求顶层字段

| 字段 | 类型 | 必填 | 默认值 | 说明 |
| --- | --- | --- | --- | --- |
| `model` | string | 是 | `official-kling-v3-motion-control` | 公开模型 ID，使用本页显示的准确值。 |
| `maxCostUsd` | string | 否 | — | 可选的美元费用上限，以最多八位小数的字符串传入。报价超出上限时会在生成前返回 HTTP 409。 |
| `callBackUrl` | string | 否 | — | 可选的公共 HTTPS 回调地址。签名配置见[任务回调](/docs/webhooks)。 |
| `expectedRevision` | number | 否 | — | 可选的模型发布版本，用于乐观并发校验。 |

## 响应结构

以下为成功响应示例，结果链接为占位值。实际美元费用由提交参数决定。任务待完成时，部分字段可能为 null。

```json
{
  "taskId": "YOUR_TASK_ID",
  "model": "official-kling-v3-motion-control",
  "status": "success",
  "billing": null,
  "output": [
    {
      "url": "https://example.com/result.mp4"
    }
  ],
  "error": null,
  "createTime": 1760000000000,
  "completeTime": 1760000060000
}
```

| 状态 | 含义 |
| --- | --- |
| `waiting` | 排队中 |
| `generating` | 生成中 |
| `success` | 已完成，读取 output[].url。 |
| `fail` | 生成失败，查看 error.code 和 error.message。 |

## 代码示例

### Node.js

```javascript
const baseUrl = "https://api.i2v.ai";
if (!process.env.I2V_API_KEY || !process.env.IDEMPOTENCY_KEY) {
  throw new Error('Set I2V_API_KEY and a stable IDEMPOTENCY_KEY before submitting.');
}
const headers = {
  Authorization: `Bearer ${process.env.I2V_API_KEY}`,
  'Content-Type': 'application/json',
  'Idempotency-Key': process.env.IDEMPOTENCY_KEY,
};
const response = await fetch(baseUrl + '/api/v1/jobs/createTask', {
  method: 'POST', headers,
  body: JSON.stringify({
  "model": "official-kling-v3-motion-control",
  "inputs": {
    "prompt": "A calm lake at sunrise",
    "resolution": "720p",
    "duration": 5
  }
}),
});
const created = await response.json();
if (!response.ok) throw new Error(JSON.stringify(created));

const deadline = Date.now() + 30 * 60_000;
let delayMs = 2_000;
let output;
while (Date.now() < deadline) {
  const result = await fetch(baseUrl + '/api/v1/jobs/recordInfo?taskId=' + encodeURIComponent(created.taskId), { headers });
  const task = await result.json();
  if (!result.ok || task.status === 'fail') throw new Error(JSON.stringify(task));
  if (task.status === 'success') {
    output = task.output;
    break;
  }
  await new Promise(resolve => setTimeout(resolve, delayMs));
  delayMs = Math.min(delayMs * 1.5, 30_000);
}
if (!output) throw new Error('Polling timed out. Resume with taskId ' + created.taskId);
console.log(output.map(item => item.url));
```

### Python

```python
import json
import os
import time
import urllib.parse
import urllib.request

base_url = "https://api.i2v.ai"
headers = {
    'Authorization': 'Bearer ' + os.environ['I2V_API_KEY'],
    'Content-Type': 'application/json',
    'Idempotency-Key': os.environ['IDEMPOTENCY_KEY'],
}
payload = json.loads("{\"model\":\"official-kling-v3-motion-control\",\"inputs\":{\"prompt\":\"A calm lake at sunrise\",\"resolution\":\"720p\",\"duration\":5}}")
request = urllib.request.Request(
    base_url + '/api/v1/jobs/createTask',
    data=json.dumps(payload).encode(), headers=headers, method='POST',
)
with urllib.request.urlopen(request, timeout=60) as response:
    created = json.load(response)

deadline = time.monotonic() + 30 * 60
delay = 2
while time.monotonic() < deadline:
    query = urllib.parse.urlencode({'taskId': created['taskId']})
    request = urllib.request.Request(base_url + '/api/v1/jobs/recordInfo?' + query, headers=headers)
    with urllib.request.urlopen(request, timeout=60) as response:
        task = json.load(response)
    if task['status'] == 'fail':
        raise RuntimeError(task['error'])
    if task['status'] == 'success':
        print([item['url'] for item in task['output']])
        break
    time.sleep(delay)
    delay = min(delay * 1.5, 30)
else:
    raise TimeoutError('Polling timed out. Resume with taskId ' + created['taskId'])
```

### Transfer a dance performance

```json
{
  "model": "official-kling-v3-motion-control",
  "inputs": {
    "referenceImageUrls": [
      "https://example.com/character.png"
    ],
    "videoUrl": "https://example.com/dance.mp4",
    "resolution": "1080p"
  }
}
```

## 美元价格

以下价格来自已发布模型目录，请核对对应配置和计费单位。

| 模式 | 分辨率 | 时长 | USD | 计费单位 |
| --- | --- | --- | --- | --- |
| standard | 720p | 5 | 0.14551282 USD | second |
| standard | 1080p | 5 | 0.19358974 USD | second |

## 错误与重试

常见提交错误包括 `400 invalid_params`、`401 unauthorized`、`402 insufficient_balance`、`409 conflict`、`429 concurrency_limit` / `rate_limit`。恢复流程见[错误与重试](/docs/errors)，签名完成通知见[任务回调](/docs/webhooks)。