跳转到主要内容
POST
/
api
/
v1
/
jobs
/
createTask
使用 sora-2-characters 生成角色动画
curl --request POST \
  --url https://api.kie.ai/api/v1/jobs/createTask \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "model": "sora-2-characters",
  "callBackUrl": "https://your-domain.com/api/callback",
  "input": {
    "character_file_url": [
      "https://static.aiquickdraw.com/tools/example/character1.mp4"
    ],
    "character_prompt": "一个友好的卡通角色，有着富有表现力的眼睛和流畅的动作",
    "safety_instruction": "确保动画适合家庭观看，不包含暴力或不适当的内容"
  }
}
'
{
  "character_id_list": "example_123456789"
}

​
文件上传要求

在使用角色动画 API 之前，您需要上传角色视频：
1

上传角色视频

访问我们的文件上传 API 来上传您的角色视频。要求：
  • 文件类型：MP4、WebM 或 AVI 格式
  • 持续时间：每个视频 1-4 秒之间
  • 最大文件大小：每个文件 10MB
  • 内容：您想要制作动画的角色动作或动作
每个动画任务只能上传一个角色视频。
2

获取上传 URL

成功上传后，您将收到可用于 character_file_url 参数的文件 URL。
3

提交动画任务

在您的 API 请求中使用获得的 URL 来生成角色动画。

​
附加参数

除了角色视频 URL 之外，您还可以提供附加参数来增强您的角色动画：
  • character_prompt：角色描述和期望的动画风格（最多 5000 个字符）
  • safety_instruction：动画的安全指南和内容限制（最多 5000 个字符）
这两个参数都是可选的，但建议使用以更好地控制动画输出。
文件存储提醒：通过我们的文件上传 API 上传的文件仅临时存储 14 天。在此期限后，角色 URL 将变得无效，并在使用角色动画 API 时导致错误。我们建议使用第三方永久存储解决方案（如 AWS S3、Google Cloud Storage 或其他云存储服务）来确保您的角色视频文件的长期可用性。
确保您的角色视频时长在 1-4 秒之间。超出此持续时间的视频可能会导致处理错误。

​
查询任务状态

提交任务后，使用统一查询端点来检查进度并检索结果：

获取任务详情

了解如何查询任务状态并检索生成结果

​
查询任务详情响应格式

任务成功完成时（state: "success"），resultJson 字段包含： 
{
  "character_id_list": "example_123456789"
}
character_id_list 可用于在后续操作中引用生成的角色动画。
对于生产环境，我们建议使用 callBackUrl 参数来接收生成完成时的自动通知，而不是轮询状态端点。

​
相关资源

市场概览

探索所有可用模型

文件上传 API

了解如何上传您的角色视频

通用 API

检查积分和账户使用情况

授权

​
Authorization
string
header
必填

所有 API 都需要通过 Bearer Token 进行身份验证。

获取 API Key：

  1. 访问 API Key 管理页面 获取您的 API Key

使用方法： 在请求头中添加： Authorization: Bearer YOUR_API_KEY

注意事项：

  • 请妥善保管您的 API Key，不要与他人分享
  • 如果您怀疑 API Key 已被泄露，请立即在管理页面中重置

请求体

application/json
​
model
enum<string>
默认值:sora-2-characters
必填

要使用的模型名称。必需字段。

  • 此端点必须为 sora-2-characters
可用选项:
sora-2-characters
示例:

"sora-2-characters"

​
callBackUrl
string<uri>

用于接收生成任务完成更新的 URL。可选但推荐用于生产环境。

  • 系统将在生成完成时向此 URL POST 任务状态和结果
  • 回调包含生成的内容 URL 和任务信息
  • 您的回调端点应接受带有 JSON 负载的 POST 请求
  • 或者，使用获取任务详情端点来轮询任务状态
示例:

"https://your-domain.com/api/callback"

​
input
object

生成任务的输入参数

响应

请求成功

​
code
enum<integer>

响应状态码

  • 200：成功 - 请求已成功处理
  • 401：未授权 - 身份验证凭据缺失或无效
  • 402：积分不足 - 账户没有足够的积分来执行操作
  • 404：未找到 - 请求的资源或端点不存在
  • 422：验证错误 - 请求参数未能通过验证检查
  • 429：速率限制 - 此资源的请求限制已超出
  • 455：服务不可用 - 系统当前正在维护
  • 500：服务器错误 - 处理请求时发生意外错误
  • 501：生成失败 - 内容生成任务失败
  • 505：功能已禁用 - 请求的功能当前已禁用
可用选项:
200,
401,
402,
404,
422,
429,
455,
500,
501,
505
​
msg
string

响应消息，失败时为错误描述

示例:

"success"

​
data
object