# Kie AI Sora-2 API Java集成开发文档
## 1. 概述
本文档旨在指导开发者如何在Java项目中集成Kie AI Sora-2 API，实现文本到视频的生成功能。Kie AI Sora-2是一个强大的AI视频生成平台，支持通过API调用创建高质量的视频内容。
## 2. API基础信息
### 2.1 接口地址
- API前缀：`https://api.kie.ai`
- 接口文档：https://kie.ai/zh-CN/sora-2
### 2.2 认证方式
所有API请求都需要在请求头中添加Authorization：
```
Authorization: Bearer 55fd537f17575b13444221c37aa11f47
```
### 2.3 请求格式
- 所有请求使用HTTP POST方法
- 数据传输编码为UTF-8
- 所有数据均为JSON格式（Content-Type: application/json）
## 3. 依赖配置
在Maven项目中，需要添加以下依赖：
```xml
com.fasterxml.jackson.core
jackson-databind
2.15.2
org.apache.httpcomponents
httpclient
4.5.13
```
## 4. 接口集成实现
Kie AI集成了Sora-2模型，支持以下功能：
1. 文本生成视频 (sora-2-text-to-video)
2. 图片生成视频 (sora-2-image-to-video)
3. 任务状态查询 （query-task）
4. 去除sora2视频水印任务 （sora-watermark-remover）
5. 创建专业版本文生视频任务（sora-2-pro-text-to-video）
6. 创建专业版本图生视频生成任务（sora-2-pro-image-to-video）
### 4.0 接口列表
| 接口名称 | 请求方式 | 请求地址 | 描述 |
|---------------------------|------|-----------------------------------|----------------|
| sora-2-text-to-video | POST | /api/v1/jobs/createTask | 创建文生视频任务 |
| sora-2-image-to-video | POST | /api/v1/jobs/createTask | 创建图生视频任务 |
| sora-2-pro-text-to-video | POST | /api/v1/jobs/createTask | 创建专业版本文生视频任务 |
| sora-2-pro-image-to-video | POST | /api/v1/jobs/createTask | 创建专业版本图生视频生成任务 |
| sora-watermark-remover | POST | /api/v1/jobs/createTask | 去除sora2视频水印任务 |
| Query Task | GET | /api/v1/jobs/recordInfo | 查询任务状态 |
### 4.4 专业版本文生视频
根据接口文档信息实现controller方法sora-2-pro-text-to-video调用接口，返回响应结果数据
#### 4.4.1 请求参数
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| prompt | String | 是 | 视频生成的文本描述 |
| aspect_ratio | String | 是 | 视频宽高比，如"portrait"、"landscape"、"9:16"、"1:1"等 |
| n_frames | Integer | 否 | 视频时长（秒） |
| size | String | 否 | 视频质量，如"standard"、"high"等 |
| remove_watermark | Boolean | 否 | 是否移除水印，默认true |
#### 4.4.2 返回结果数据
```json
{
"code": 200,
"message": "success",
"data": {
"taskId": "task_12345678",
"model": "sora-2-pro-text-to-video",
"state": "success",
"param": "{\"model\":\"sora-2-pro-text-to-video\",\"callBackUrl\":\"https://your-domain.com/api/callback\",\"input\":{\"prompt\":\"A professor stands at the front of a lively classroom, enthusiastically giving a lecture. On the blackboard behind him are colorful chalk diagrams. With an animated gesture, he declares to the students: “Sora 2 is now available on Kie AI, making it easier than ever to create stunning videos.” The students listen attentively, some smiling and taking notes.\",\"aspect_ratio\":\"landscape\",\"remove_watermark\":true}}",
"resultJson": "{\"resultUrls\":[\"https://example.com/generated-video.mp4\"]}",
"failCode": "",
"failMsg": "",
"completeTime": 1698765432000,
"createTime": 1698765400000,
"updateTime": 1698765432000
}
}
```
### 4.5 专业版本图生视频
根据接口文档信息实现controller方法sora-2-pro-image-to-video调用接口，返回响应结果数据
#### 4.5.1 请求参数
| 参数名 | 类型 | 必填 | 说明 |
|--------|---------|----|---------------------------------------------|
| prompt | String | 是 | 视频生成的文本描述 | |
| aspect_ratio | String | 是 | 视频宽高比，如"portrait"、"landscape"、"9:16"、"1:1"等 |
| n_frames | Integer | 否 | 视频时长（秒） |
| size | String | 否 | 视频质量，如"standard"、"high"等 |
| image_urls | Array of String | 是 | 图片URL数组
| remove_watermark | Boolean | 否 | 是否移除水印，默认true |
#### 4.5.2 返回结果数据
```json
{
"code": 200,
"message": "success",
"data": {
"taskId": "task_12345678",
"model": "sora-2-pro-image-to-video",
"state": "success",
"param": "{\"model\":\"sora-2-pro-image-to-video\",\"callBackUrl\":\"https://your-domain.com/api/callback\",\"input\":{\"image_urls\":\"https://example.com/image.jpg\",\"aspect_ratio\":\"landscape\",\"remove_watermark\":true}}",
"resultJson": "{\"resultUrls\":[\"https://example.com/generated-video.mp4\"]}",
"failCode": "",
"failMsg": "",
"completeTime": 1698765432000,
"createTime": 1698765400000,
"updateTime": 1698765432000
}
}
```
### 4.6 去除视频水印
根据接口文档信息实现controller方法sora-watermark-remover调用接口，返回响应结果数据
#### 4.6.1 请求参数
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| video_url | String | 是 | 视频URL |
#### 4.6.2 返回结果数据
```json
{
"code": 200,
"message": "success",
"data": {
"taskId": "task_12345678",
"model": "sora-watermark-remover",
"state": "success",
"param": "{\"model\":\"sora-watermark-remover\",\"callBackUrl\":\"https://your-domain.com/api/callback\",\"input\":{\"video_url\":\"https://example.com/video.mp4\"}}",
"resultJson": "{\"resultUrls\":[\"https://example.com/generated-video-no-watermark.mp4\"]}",
"failCode": "",
"failMsg": "",
"completeTime": 1698765432000,
"createTime": 1698765400000,
"updateTime": 1698765432000
}
}
```
### 4.1 文生视频 (sora-2-text-to-video)
根据接口文档信息实现controller方法sora-2-text-to-video调用接口，返回响应结果数据
#### 4.1.1 请求参数
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| prompt | String | 是 | 视频生成的文本描述 |
| aspect_ratio | String | 是 | 视频宽高比，如"portrait"、"landscape"、"9:16"、"1:1"等 |
| remove_watermark | Boolean | 否 | 是否移除水印，默认true |
#### 4.1.2 返回结果数据
```json
{
"code": 200,
"message": "success",
"data": {
"taskId": "task_12345678",
"model": "sora-2-text-to-video",
"state": "success",
"param": "{\"model\":\"sora-2-text-to-video\",\"callBackUrl\":\"https://your-domain.com/api/callback\",\"input\":{\"prompt\":\"A professor stands at the front of a lively classroom, enthusiastically giving a lecture. On the blackboard behind him are colorful chalk diagrams. With an animated gesture, he declares to the students: “Sora 2 is now available on Kie AI, making it easier than ever to create stunning videos.” The students listen attentively, some smiling and taking notes.\",\"aspect_ratio\":\"landscape\",\"remove_watermark\":true}}",
"resultJson": "{\"resultUrls\":[\"https://example.com/generated-video.mp4\"]}",
"failCode": "",
"failMsg": "",
"completeTime": 1698765432000,
"createTime": 1698765400000,
"updateTime": 1698765432000
}
}
```
#### 4.1.3 实现说明
文生视频接口通过调用KieAIService的createTextToVideoTask方法实现。该方法会构建包含prompt、aspect_ratio等参数的请求载荷，然后通过HTTP POST请求发送到Kie AI Sora-2 API。
在Controller层，通过@PostMapping注解定义POST请求接口，接收客户端传递的JSON参数。首先验证必要参数prompt是否存在且非空，然后提取可选参数aspect_ratio和remove_watermark。
Service层使用HttpRequestUtils工具类发起带认证头的POST请求，请求地址为`https://api.kie.ai/api/v1/jobs/createTask`。认证头包含API密钥：
```
Authorization: Bearer {API_KEY}
```
请求成功后，API会返回包含taskId的JSON响应，该taskId可用于后续查询任务状态。
### 4.2 图生视频 (sora-2-image-to-video)
根据接口文档信息实现controller方法sora-2-image-to-video调用接口，返回响应结果数据
#### 4.2.1 请求参数
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| prompt | String | 是 | 视频生成的文本描述 |
| aspect_ratio | String | 是 | 视频宽高比，如"portrait"、"landscape"、"9:16"、"1:1"等 |
| n_frames | Integer | 否 | 视频时长（秒） |
| size | String | 否 | 视频质量，如"standard"、"high"等 |
| image_urls | Array of String | 是 | 图片URL数组
| remove_watermark | Boolean | 否 | 是否移除水印，默认true |
#### 4.2.2 返回结果数据
```json
{
"code": 200,
"message": "success",
"data": {
"taskId": "task_12345678",
"model": "sora-2-image-to-video",
"state": "success",
"param": "{\"model\":\"sora-2-image-to-video\",\"callBackUrl\":\"https://your-domain.com/api/callback\",\"input\":{\"image_urls\":\"https://example.com/image.jpg\",\"aspect_ratio\":\"landscape\",\"remove_watermark\":true}}",
"resultJson": "{\"resultUrls\":[\"https://example.com/generated-video.mp4\"]}",
"failCode": "",
"failMsg": "",
"completeTime": 1698765432000,
"createTime": 1698765400000,
"updateTime": 1698765432000
}
}
```
#### 4.2.3 实现说明
图生视频接口通过调用KieAIService的createImageToVideoTask方法实现。该方法会构建包含image_urls、aspect_ratio等参数的请求载荷，然后通过HTTP POST请求发送到Kie AI Sora-2 API。
在Controller层，通过@PostMapping注解定义POST请求接口，接收客户端传递的JSON参数。首先验证必要参数image_urls是否存在且非空，然后提取可选参数aspect_ratio、n_frames、fps和remove_watermark。
Service层使用HttpRequestUtils工具类发起带认证头的POST请求，请求地址为`https://api.kie.ai/api/v1/jobs/createTask`。认证头包含API密钥：
```
Authorization: Bearer {API_KEY}
```
请求成功后，API会返回包含taskId的JSON响应，该taskId可用于后续查询任务状态。与文生视频接口类似，但输入参数为图片URL而非文本描述。
### 4.3 专业版本文生视频 (sora-2-pro-text-to-video)
根据接口文档信息实现controller方法sora-2-pro-text-to-video调用接口，返回响应结果数据
#### 4.3.1 请求参数
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| prompt | String | 是 | 视频生成的文本描述 |
| aspect_ratio | String | 是 | 视频宽高比，如"portrait"、"landscape"、"9:16"、"1:1"等 |
| n_frames | Integer | 否 | 视频时长（秒） |
| size | String | 否 | 视频质量，如"standard"、"high"等 |
| remove_watermark | Boolean | 否 | 是否移除水印，默认true |
#### 4.3.2 返回结果数据
```json
{
"code": 200,
"message": "success",
"data": {
"taskId": "task_12345678",
"model": "sora-2-pro-text-to-video",
"state": "success",
"param": "{\"model\":\"sora-2-pro-text-to-video\",\"callBackUrl\":\"https://your-domain.com/api/callback\",\"input\":{\"prompt\":\"A professor stands at the front of a lively classroom, enthusiastically giving a lecture. On the blackboard behind him are colorful chalk diagrams. With an animated gesture, he declares to the students: “Sora 2 is now available on Kie AI, making it easier than ever to create stunning videos.” The students listen attentively, some smiling and taking notes.\",\"aspect_ratio\":\"landscape\",\"remove_watermark\":true}}",
"resultJson": "{\"resultUrls\":[\"https://example.com/generated-video.mp4\"]}",
"failCode": "",
"failMsg": "",
"completeTime": 1698765432000,
"createTime": 1698765400000,
"updateTime": 1698765432000
}
}
```
#### 4.3.3 实现说明
专业版本文生视频接口通过调用KieAIService的createProTextToVideoTask方法实现。该方法会构建包含prompt、aspect_ratio、size、style等参数的请求载荷，然后通过HTTP POST请求发送到Kie AI Sora-2 API。
在Controller层，通过@PostMapping注解定义POST请求接口，接收客户端传递的JSON参数。首先验证必要参数prompt是否存在且非空，然后提取可选参数aspect_ratio、n_frames、fps、remove_watermark、size和style。
Service层使用HttpRequestUtils工具类发起带认证头的POST请求，请求地址为`https://api.kie.ai/api/v1/jobs/createTask`。认证头包含API密钥：
```
Authorization: Bearer {API_KEY}
```
专业版本接口相比普通版本提供了更多参数配置选项，包括视频质量和风格等高级参数，可以生成更高质量和特定风格的视频内容。请求成功后，API会返回包含taskId的JSON响应，该taskId可用于后续查询任务状态。
### 4.4 专业版本图生视频 (sora-2-pro-image-to-video)
根据接口文档信息实现controller方法sora-2-pro-image-to-video调用接口，返回响应结果数据
#### 4.4.1 请求参数
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| prompt | String | 是 | 视频生成的文本描述 |
| aspect_ratio | String | 是 | 视频宽高比，如"portrait"、"landscape"、"9:16"、"1:1"等 |
| n_frames | Integer | 否 | 视频时长（秒） |
| size | String | 否 | 视频质量，如"standard"、"high"等 |
| image_urls | Array of String | 是 | 图片URL数组
| remove_watermark | Boolean | 否 | 是否移除水印，默认true |
#### 4.4.2 返回结果数据
```json
{
"code": 200,
"message": "success",
"data": {
"taskId": "task_12345678",
"model": "sora-2-pro-image-to-video",
"state": "success",
"param": "{\"model\":\"sora-2-pro-image-to-video\",\"callBackUrl\":\"https://your-domain.com/api/callback\",\"input\":{\"image_urls\":\"https://example.com/image.jpg\",\"aspect_ratio\":\"landscape\",\"remove_watermark\":true}}",
"resultJson": "{\"resultUrls\":[\"https://example.com/generated-video.mp4\"]}",
"failCode": "",
"failMsg": "",
"completeTime": 1698765432000,
"createTime": 1698765400000,
"updateTime": 1698765432000
}
}
```
#### 4.4.3 实现说明
专业版本图生视频接口通过调用KieAIService的createProImageToVideoTask方法实现。该方法会构建包含image_urls、aspect_ratio等参数的请求载荷，然后通过HTTP POST请求发送到Kie AI Sora-2 API。
在Controller层，通过@PostMapping注解定义POST请求接口，接收客户端传递的JSON参数。首先验证必要参数image_urls是否存在且非空，然后提取可选参数aspect_ratio、remove_watermark。
Service层使用HttpRequestUtils工具类发起带认证头的POST请求，请求地址为`https://api.kie.ai/api/v1/jobs/createTask`。认证头包含API密钥：
```
Authorization: Bearer {API_KEY}
```
专业版本接口相比普通版本提供了更多参数配置选项，包括视频质量和风格等高级参数，可以生成更高质量和特定风格的视频内容。请求成功后，API会返回包含taskId的JSON响应，该taskId可用于后续查询任务状态。与专业版本文生视频接口类似，但输入参数为图片URL而非文本描述。
### 4.5 去除视频水印 (sora-watermark-remover)
根据接口文档信息实现controller方法sora-watermark-remover调用接口，返回响应结果数据
#### 4.5.1 请求参数
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| video_url | String | 是 | 视频URL |
#### 4.5.2 返回结果数据
```json
{
"code": 200,
"message": "success",
"data": {
"taskId": "task_12345678",
"model": "sora-watermark-remover",
"state": "success",
"param": "{\"model\":\"sora-watermark-remover\",\"callBackUrl\":\"https://your-domain.com/api/callback\",\"input\":{\"video_url\":\"https://example.com/video.mp4\"}}",
"resultJson": "{\"resultUrls\":[\"https://example.com/generated-video-no-watermark.mp4\"]}",
"failCode": "",
"failMsg": "",
"completeTime": 1698765432000,
"createTime": 1698765400000,
"updateTime": 1698765432000
}
}
```
#### 4.5.3 实现说明
去除视频水印接口通过调用KieAIService的removeWatermark方法实现。该方法会构建包含video_url参数的请求载荷，然后通过HTTP POST请求发送到Kie AI Sora-2 API。
在Controller层，通过@PostMapping注解定义POST请求接口，接收客户端传递的JSON参数。首先验证必要参数video_url是否存在且非空。
Service层使用HttpRequestUtils工具类发起带认证头的POST请求，请求地址为`https://api.kie.ai/api/v1/jobs/createTask`。认证头包含API密钥：
```
Authorization: Bearer {API_KEY}
```
该接口专门用于处理已生成视频的水印去除任务。请求成功后，API会返回包含taskId的JSON响应，该taskId可用于后续查询任务状态。处理完成后，可以通过查询任务状态获取去水印后的视频URL。
### 4.6 查询任务状态 (query-task)
根据任务ID查询视频生成任务的状态
#### 4.6.1 请求参数
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| taskId | String | 是 | 任务ID |
#### 4.6.2 返回结果数据
``` json
{
"code": 200,
"message": "success",
"data": {
"taskId": "task_12345678",
"model": "sora-2-text-to-video",
"state": "success",
"param": "{\"model\":\"sora-2-text-to-video\",\"callBackUrl\":\"https://your-domain.com/api/callback\",\"input\":{\"prompt\":\"A professor stands at the front of a lively classroom, enthusiastically giving a lecture. On the blackboard behind him are colorful chalk diagrams. With an animated gesture, he declares to the students: “Sora 2 is now available on Kie AI, making it easier than ever to create stunning videos.” The students listen attentively, some smiling and taking notes.\",\"aspect_ratio\":\"landscape\",\"remove_watermark\":true}}",
"resultJson": "{\"resultUrls\":[\"https://example.com/generated-image.jpg\"]}",
"failCode": "",
"failMsg": "",
"completeTime": 1698765432000,
"createTime": 1698765400000,
"updateTime": 1698765432000
}
}
```
#### 4.6.3 实现说明
查询任务状态接口通过调用KieAIService的getTaskStatus方法实现。该方法会根据任务ID向Kie AI Sora-2 API发送HTTP GET请求，获取任务的当前状态和结果信息。
在Controller层，通过@GetMapping注解定义GET请求接口，路径参数为taskId。首先验证taskId参数是否存在且非空。
Service层使用HttpRequestUtils工具类发起带认证头的GET请求，请求地址为`https://api.kie.ai/api/v1/jobs/recordInfo?taskId={taskId}`。认证头包含API密钥：
```
Authorization: Bearer {API_KEY}
```
API会返回任务的详细状态信息，包括任务ID、模型名称、状态、参数、结果URL、失败信息等。客户端可以通过轮询此接口来获取任务的执行进度和最终结果。状态字段state可能的值包括：
- "pending": 任务等待处理
- "processing": 任务正在处理中
- "success": 任务执行成功
- "failed": 任务执行失败
## 核心组件
### 1. Service层 (KieAIService)
Service层负责与Kie AI Sora-2 API进行实际的HTTP通信，处理业务逻辑并返回结果。
#### 1.1 主要方法
- `createTextToVideoTask(String prompt, String aspectRatio, Integer n_frames, Integer fps, Boolean removeWatermark)`:
创建文本到视频生成任务。该方法接收用户提供的文本描述和其他可选参数，构造API请求载荷，并调用Kie AI Sora-2 API创建文生视频任务，返回任务ID。
- `createImageToVideoTask(String imageUrl, String aspectRatio, Integer n_frames, Integer fps, Boolean removeWatermark)`:
创建图片到视频生成任务。该方法接收用户提供的图片URL和其他可选参数，构造API请求载荷，并调用Kie AI Sora-2 API创建图生视频任务，返回任务ID。
- `getTaskStatus(String taskId)`:
查询任务状态。该方法根据任务ID调用Kie AI Sora-2 API查询视频生成任务的当前状态，并返回详细的状态信息。
- `callback()`:
处理回调通知。该方法接收Kie AI Sora-2 API发送的回调通知，包含任务ID、状态、结果URL等信息。根据任务状态更新本地数据库记录，触发后续处理流程。
-
- `removeWatermark(String videoUrl)`:
去除视频水印。该方法接收视频URL，调用Kie AI Sora-2 API的去水印功能，返回处理后的视频URL。
- `createProTextToVideoTask(String prompt, String aspectRatio, Integer n_frames, Integer fps, Boolean removeWatermark)`:
创建专业版本文生视频任务。该方法提供更高级的文生视频生成功能，支持更多参数配置。
- `createProImageToVideoTask(String imageUrl, String aspectRatio, Integer n_frames, Integer fps, Boolean removeWatermark)`:
创建专业版本图生视频生成任务。该方法提供更高级的图生视频生成功能，支持更多参数配置。
#### 1.2 实现细节
Service层使用`HttpRequestUtils`工具类来发起HTTP请求，通过Apache HttpClient库与Kie AI Sora-2 API进行通信。所有请求都包含必要的认证头信息：
```
Authorization: Bearer {API_KEY}
```
#### 1.3 代码示例
```java
@Service
public class KieAIService {
private static final Logger logger = LoggerFactory.getLogger(KieAIService.class);
// API配置
private static final String API_BASE_URL = "https://api.kie.ai";
private static final String API_KEY = "55fd537f17575b13444221c37aa11f47";
/**
* 创建文生视频任务
* @param prompt 视频生成的文本描述
* @param aspectRatio 视频宽高比
* @param n_frames 视频时长（秒）
* @param fps 视频帧率
* @param removeWatermark 是否移除水印
* @return 任务ID
*/
public String createTextToVideoTask(String prompt, String aspectRatio, Integer n_frames, Integer fps, Boolean removeWatermark) {
try {
// 构建API URL
String url = API_BASE_URL + "/api/v1/jobs/createTask";
// 构建请求参数
Map input = new HashMap<>();
input.put("prompt", prompt);
if (aspectRatio != null) input.put("aspect_ratio", aspectRatio);
if (n_frames != null) input.put("n_frames", n_frames);
if (fps != null) input.put("fps", fps);
if (removeWatermark != null) input.put("remove_watermark", removeWatermark);
Map payload = new HashMap<>();
payload.put("model", "sora-2-text-to-video");
payload.put("callBackUrl", "https://your-domain.com/api/callback");
payload.put("input", input);
// 转换为JSON字符串
String jsonPayload = JSON.toJSONString(payload);
logger.info("创建文生视频任务请求参数: {}", jsonPayload);
// 添加Authorization请求头
Map headers = new HashMap<>();
headers.put("Authorization", "Bearer " + API_KEY);
// 发起POST请求
String response = postWithHeaders(url, jsonPayload, headers);
logger.info("创建文生视频任务响应: {}", response);
// 解析响应获取任务ID
JSONObject result = JSON.parseObject(response);
if (result != null && result.containsKey("data")) {
JSONObject data = result.getJSONObject("data");
if (data != null && data.containsKey("taskId")) {
return data.getString("taskId");
}
}
return null;
} catch (Exception e) {
logger.error("创建文生视频任务失败: {}", e.getMessage(), e);
return null;
}
}
/**
* 查询任务状态
* @param taskId 任务ID
* @return 任务状态信息
*/
public String getTaskStatus(String taskId) {
try {
// 构建API URL
String url = API_BASE_URL + "/api/v1/jobs/recordInfo?taskId=" + taskId;
// 添加Authorization请求头
Map headers = new HashMap<>();
headers.put("Authorization", "Bearer " + API_KEY);
// 发起GET请求
String response = getWithHeaders(url, headers);
logger.info("查询任务状态响应: {}", response);
return response;
} catch (Exception e) {
logger.error("查询任务状态失败: {}", e.getMessage(), e);
return null;
}
}
/**
* 带请求头的POST请求方法
* @param url 请求URL
* @param jsonPayload JSON格式的请求参数
* @param headers 请求头
* @return 响应结果
*/
private String postWithHeaders(String url, String jsonPayload, Map headers) {
return HttpRequestUtils.postWithHeaders(url, jsonPayload, null, headers);
}
/**
* 带请求头的GET请求方法
* @param url 请求URL
* @param headers 请求头
* @return 响应结果
*/
private String getWithHeaders(String url, Map headers) {
return HttpRequestUtils.getWithHeaders(url, null, headers);
}
}
```
### 2. Controller层 (KieAI2VideoController)
Controller层提供RESTful API接口，接收客户端请求并调用Service层处理业务逻辑。
#### 2.1 接口列表
- `POST /api/kieai/text-to-video`:
创建文本到视频任务。请求体应包含prompt等参数，成功时返回任务ID。
- `POST /api/kieai/image-to-video`:
创建图片到视频任务。请求体应包含image_urls等参数，成功时返回任务ID。
- `GET /api/kieai/task/{taskId}`:
查询任务状态。路径参数taskId为任务ID，成功时返回任务的详细状态信息。
- `POST /api/kieai/watermark-remover`:
去除视频水印。请求体应包含video_url参数，成功时返回处理后的视频URL。
- `POST /api/kieai/pro-text-to-video`:
创建专业版本文生视频任务。提供更多参数配置选项，请求体应包含相应参数。
- `POST /api/kieai/pro-image-to-video`:
创建专业版本图生视频生成任务。提供更多参数配置选项，请求体应包含相应参数。
- `POST /api/kieai/callback`:
处理Kie AI Sora-2 API的回调通知。请求体应包含回调数据，成功时返回确认响应。
#### 2.2 实现细节
Controller层使用Spring Boot框架实现，通过注解定义RESTful接口。所有接口都返回统一的响应格式：
```json
{
"code": 200,
"message": "success",
"data": {}
}
```
接口使用Swagger注解进行文档化，支持在Swagger UI中查看和测试API。
#### 2.3 代码示例
```java
@RestController
@RequestMapping("/api/kieai")
@Tag(name = "Kie AI接口", description = "Kie AI Sora-2 API接口调用")
public class KieAI2VideoController {
private static final Logger logger = LoggerFactory.getLogger(KieAI2VideoController.class);
@Autowired
private KieAIService kieAIService;
/**
* 创建文生视频任务
* @param requestParams 请求参数
* @return 任务ID
*/
@PostMapping("/text-to-video")
@Operation(summary = "创建文生视频任务", description = "通过文本描述创建视频生成任务")
@ApiResponses({
@ApiResponse(responseCode = "200", description = "创建成功", content = @Content(schema = @Schema(implementation = String.class))),
@ApiResponse(responseCode = "400", description = "参数错误", content = @Content),
@ApiResponse(responseCode = "500", description = "创建失败", content = @Content)
})
public ResponseResult createTextToVideoTask(
@Parameter(description = "请求参数", required = true, schema = @Schema(implementation = JSONObject.class))
@RequestBody Map requestParams) {
try {
logger.info("创建文生视频任务，参数：{}", requestParams);
// 获取必要参数
String prompt = (String) requestParams.get("prompt");
if (prompt == null || prompt.isEmpty()) {
return ResponseResult.fail(400, "prompt参数不能为空");
}
// 获取可选参数
String aspectRatio = (String) requestParams.get("aspectRatio");
Integer n_frames = (Integer) requestParams.get("n_frames");
Integer fps = (Integer) requestParams.get("fps");
Boolean removeWatermark = (Boolean) requestParams.get("removeWatermark");
// 调用服务创建任务
String taskId = kieAIService.createTextToVideoTask(prompt, aspectRatio, n_frames, fps, removeWatermark);
if (taskId != null) {
return ResponseResult.success(taskId);
} else {
return ResponseResult.fail("创建文生视频任务失败");
}
} catch (Exception e) {
logger.error("创建文生视频任务失败：{}", e.getMessage(), e);
return ResponseResult.fail(500, "创建文生视频任务失败：" + e.getMessage());
}
}
/**
* 查询任务状态
* @param taskId 任务ID
* @return 任务状态信息
*/
@GetMapping("/task/{taskId}")
@Operation(summary = "查询任务状态", description = "根据任务ID查询视频生成任务的状态")
@ApiResponses({
@ApiResponse(responseCode = "200", description = "查询成功", content = @Content(schema = @Schema(implementation = String.class))),
@ApiResponse(responseCode = "400", description = "参数错误", content = @Content),
@ApiResponse(responseCode = "500", description = "查询失败", content = @Content)
})
public ResponseResult getTaskStatus(
@Parameter(description = "任务ID", required = true, example = "task_1234567890")
@PathVariable("taskId") String taskId) {
try {
logger.info("查询任务状态，任务ID：{}", taskId);
if (taskId == null || taskId.isEmpty()) {
return ResponseResult.fail(400, "taskId参数不能为空");
}
// 调用服务查询任务状态
String taskStatus = kieAIService.getTaskStatus(taskId);
if (taskStatus != null) {
return ResponseResult.success(taskStatus);
} else {
return ResponseResult.fail("查询任务状态失败");
}
} catch (Exception e) {
logger.error("查询任务状态失败：{}", e.getMessage(), e);
return ResponseResult.fail(500, "查询任务状态失败：" + e.getMessage());
}
}
}
```
## 5. Java代码示例
以下是使用Java调用Kie AI Sora-2 API创建视频生成任务的完整示例：
### 5.1 创建视频生成任务
```java
import com.alibaba.fastjson.JSON;
import com.alibaba.fastjson.JSONObject;
import org.apache.http.HttpEntity;
import org.apache.http.HttpResponse;
import org.apache.http.client.methods.HttpGet;
import org.apache.http.client.methods.HttpPost;
import org.apache.http.entity.StringEntity;
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.impl.client.HttpClients;
import org.apache.http.util.EntityUtils;
import java.util.HashMap;
import java.util.Map;
public class KieAIClient {
private static final String API_BASE_URL = "https://api.kie.ai";
private static final String API_KEY = "55fd537f17575b13444221c37aa11f47";
public static void main(String[] args) {
// 创建文生视频任务
String taskId = createTextToVideoTask(
"A professor stands at the front of a lively classroom, enthusiastically giving a lecture. On the blackboard behind him are colorful chalk diagrams. With an animated gesture, he declares to the students: “Sora 2 is now available on Kie AI, making it easier than ever to create stunning videos.” The students listen attentively, some smiling and taking notes.",
"landscape",
true
);
System.out.println("Task ID: " + taskId);
// 查询任务状态
if (taskId != null) {
String taskStatus = getTaskStatus(taskId);
System.out.println("Task Status: " + taskStatus);
}
}
/**
* 创建文生视频任务
* @param prompt 视频生成的文本描述
* @param aspectRatio 视频宽高比
* @param removeWatermark 是否移除水印
* @return 任务ID
*/
public static String createTextToVideoTask(String prompt, String aspectRatio, Boolean removeWatermark) {
try {
// 构建API URL
String url = API_BASE_URL + "/api/v1/jobs/createTask";
// 构建请求参数
Map input = new HashMap<>();
input.put("prompt", prompt);
input.put("aspect_ratio", aspectRatio);
if (removeWatermark != null) {
input.put("remove_watermark", removeWatermark);
}
Map payload = new HashMap<>();
payload.put("model", "sora-2-text-to-video");
payload.put("callBackUrl", "https://your-domain.com/api/callback");
payload.put("input", input);
// 转换为JSON字符串
String jsonPayload = JSON.toJSONString(payload);
// 发起POST请求
String response = postWithHeaders(url, jsonPayload);
// 解析响应获取任务ID
JSONObject result = JSON.parseObject(response);
if (result != null && result.containsKey("data")) {
JSONObject data = result.getJSONObject("data");
if (data != null && data.containsKey("taskId")) {
return data.getString("taskId");
}
}
return null;
} catch (Exception e) {
e.printStackTrace();
return null;
}
}
/**
* 创建图片到视频任务
* @param imageUrl 图片URL
* @param aspectRatio 视频宽高比
* @param removeWatermark 是否移除水印
* @return 任务ID
*/
public static String createImageToVideoTask(String imageUrl, String aspectRatio, Boolean removeWatermark) {
try {
// 构建API URL
String url = API_BASE_URL + "/api/v1/jobs/createTask";
// 构建请求参数
Map input = new HashMap<>();
input.put("image_urls", imageUrl);
input.put("aspect_ratio", aspectRatio);
if (removeWatermark != null) {
input.put("remove_watermark", removeWatermark);
}
Map payload = new HashMap<>();
payload.put("model", "sora-2-image-to-video");
payload.put("callBackUrl", "https://your-domain.com/api/callback");
payload.put("input", input);
// 转换为JSON字符串
String jsonPayload = JSON.toJSONString(payload);
// 发起POST请求
String response = postWithHeaders(url, jsonPayload);
// 解析响应获取任务ID
JSONObject result = JSON.parseObject(response);
if (result != null && result.containsKey("data")) {
JSONObject data = result.getJSONObject("data");
if (data != null && data.containsKey("taskId")) {
return data.getString("taskId");
}
}
return null;
} catch (Exception e) {
e.printStackTrace();
return null;
}
}
/**
* 查询任务状态
* @param taskId 任务ID
* @return 任务状态信息
*/
public static String getTaskStatus(String taskId) {
try {
// 构建API URL
String url = API_BASE_URL + "/api/v1/jobs/recordInfo?taskId=" + taskId;
// 发起GET请求
return getWithHeaders(url);
} catch (Exception e) {
e.printStackTrace();
return null;
}
}
/**
* 带请求头的POST请求方法
* @param url 请求URL
* @param jsonPayload JSON格式的请求参数
* @return 响应结果
*/
private static String postWithHeaders(String url, String jsonPayload) throws Exception {
CloseableHttpClient httpClient = HttpClients.createDefault();
try {
HttpPost httpPost = new HttpPost(url);
// 设置请求头
httpPost.setHeader("Content-Type", "application/json");
httpPost.setHeader("Authorization", "Bearer " + API_KEY);
// 设置请求体
StringEntity entity = new StringEntity(jsonPayload, "UTF-8");
httpPost.setEntity(entity);
// 发送请求并获取响应
HttpResponse response = httpClient.execute(httpPost);
HttpEntity responseEntity = response.getEntity();
if (responseEntity != null) {
return EntityUtils.toString(responseEntity, "UTF-8");
}
return null;
} finally {
httpClient.close();
}
}
/**
* 带请求头的GET请求方法
* @param url 请求URL
* @return 响应结果
*/
private static String getWithHeaders(String url) throws Exception {
CloseableHttpClient httpClient = HttpClients.createDefault();
try {
HttpGet httpGet = new HttpGet(url);
// 设置请求头
httpGet.setHeader("Authorization", "Bearer " + API_KEY);
// 发送请求并获取响应
HttpResponse response = httpClient.execute(httpGet);
HttpEntity responseEntity = response.getEntity();
if (responseEntity != null) {
return EntityUtils.toString(responseEntity, "UTF-8");
}
return null;
} finally {
httpClient.close();
}
}
}
```
### 5.2 完整的Maven依赖配置
```xml
org.apache.httpcomponents
httpclient
4.5.13
com.alibaba
fastjson
1.2.83
org.projectlombok
lombok
1.18.24
provided
```
### 5.3 使用说明
1. 将上述Java代码保存为`KieAIClient.java`文件
2. 确保项目中已添加所需的Maven依赖
3. 替换代码中的API_KEY为您的实际API密钥
4. 编译并运行代码，即可测试文生视频和任务状态查询功能
该示例代码展示了如何使用Java调用Kie AI Sora-2 API的核心功能：
- 创建文生视频任务
- 创建图生视频任务
- 查询任务状态
代码中包含了完整的HTTP请求处理逻辑，包括请求头设置、参数构建、响应解析等。您可以根据实际需求修改参数和处理逻辑。
## 6. 参数说明
### 6.1 请求参数
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| model | String | 是 | 模型名称，如"sora-2-text-to-video"、"sora-2-image-to-video"等 |
| callBackUrl | String | 否 | 回调地址，任务完成时会向该地址发送通知 |
| input | Object | 是 | 输入参数对象 |
### 6.2 input对象参数
#### 6.2.1 文生视频 (sora-2-text-to-video)
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| prompt | String | 是 | 视频生成的文本描述 |
| aspect_ratio | String | 是 | 视频宽高比，支持"portrait"（竖屏）、"landscape"（横屏）、"9:16"、"16:9"、"1:1"等 |
| remove_watermark | Boolean | 否 | 是否移除水印，默认true |
#### 6.2.2 图生视频 (sora-2-image-to-video)
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| prompt | String | 是 | 视频生成的文本描述 |
| aspect_ratio | String | 是 | 视频宽高比，支持"portrait"（竖屏）、"landscape"（横屏）、"square"（方形）、"9:16"、"16:9"、"1:1"等 |
| image_urls | Array of String | 是 | 图片URL数组
| remove_watermark | Boolean | 否 | 是否移除水印，默认true |
#### 6.2.3 专业版本文生视频 (sora-2-pro-text-to-video)
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| prompt | String | 是 | 视频生成的文本描述 |
| aspect_ratio | String | 是 | 视频宽高比，支持"portrait"（竖屏）、"landscape"（横屏）、"square"（方形）、"9:16"、"16:9"、"1:1"等 |
| n_frames | Integer | 否 | 视频时长（秒） |
| size | String | 否 | 视频质量，如"standard"、"high"等 |
| remove_watermark | Boolean | 否 | 是否移除水印，默认true |
#### 6.2.4 专业版本图生视频 (sora-2-pro-image-to-video)
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| prompt | String | 是 | 视频生成的文本描述 |
| aspect_ratio | String | 是 | 视频宽高比，支持"portrait"（竖屏）、"landscape"（横屏）、"square"（方形）、"9:16"、"16:9"、"1:1"等 |
| n_frames | Integer | 否 | 视频时长（秒） |
| size | String | 否 | 视频质量，如"standard"、"high"等 |
| image_urls | Array of String | 是 | 图片URL数组 ｜
| remove_watermark | Boolean | 否 | 是否移除水印，默认true |
#### 6.2.5 去除视频水印 (sora-watermark-remover)
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| video_url | String | 是 | 视频URL |
### 6.3 参数示例
#### 6.3.1 文生视频参数示例
```json
{
"model": "sora-2-text-to-video",
"callBackUrl": "https://your-domain.com/api/callback",
"input": {
"prompt": "A professor stands at the front of a lively classroom, enthusiastically giving a lecture. On the blackboard behind him are colorful chalk diagrams. With an animated gesture, he declares to the students: \"Sora 2 is now available on Kie AI, making it easier than ever to create stunning videos.\" The students listen attentively, some smiling and taking notes.",
"aspect_ratio": "landscape",
"n_frames": 5,
"fps": 24,
"remove_watermark": true
}
}
```
#### 6.3.2 图生视频参数示例
```json
{
"model": "sora-2-image-to-video",
"callBackUrl": "https://your-domain.com/api/callback",
"input": {
"image_urls": "https://example.com/image.jpg",
"aspect_ratio": "portrait",
"n_frames": 5,
"fps": 24,
"remove_watermark": true
}
}
```
#### 6.3.3 专业版本文生视频参数示例
```json
{
"model": "sora-2-pro-text-to-video",
"callBackUrl": "https://your-domain.com/api/callback",
"input": {
"prompt": "A professor stands at the front of a lively classroom, enthusiastically giving a lecture. On the blackboard behind him are colorful chalk diagrams. With an animated gesture, he declares to the students: \"Sora 2 is now available on Kie AI, making it easier than ever to create stunning videos.\" The students listen attentively, some smiling and taking notes.",
"aspect_ratio": "landscape",
"n_frames": 5,
"fps": 24,
"remove_watermark": true,
"size": "4k",
"style": "realistic"
}
}
```
#### 6.3.4 专业版本图生视频参数示例
```json
{
"model": "sora-2-pro-image-to-video",
"callBackUrl": "https://your-domain.com/api/callback",
"input": {
"image_urls": "https://example.com/image.jpg",
"aspect_ratio": "portrait",
"n_frames": 5,
"fps": 24,
"remove_watermark": true,
"size": "hd",
"style": "anime"
}
}
```
#### 6.3.5 去除视频水印参数示例
```json
{
"model": "sora-watermark-remover",
"callBackUrl": "https://your-domain.com/api/callback",
"input": {
"video_url": "https://example.com/video-with-watermark.mp4"
}
}
```
#### 6.3.6 callback 回调通知示例
```json
{
"code": 200,
"data": {
"completeTime": 1755599644000,
"consumeCredits": 100,
"costTime": 8,
"createTime": 1755599634000,
"model": "sora-2-text-to-video",
"param": "{\"callBackUrl\":\"https://your-domain.com/api/callback\",\"model\":\"sora-2-text-to-video\",\"input\":{\"prompt\":\"A professor stands at the front of a lively classroom, enthusiastically giving a lecture. On the blackboard behind him are colorful chalk diagrams. With an animated gesture, he declares to the students: “Sora 2 is now available on Kie AI, making it easier than ever to create stunning videos.” The students listen attentively, some smiling and taking notes.\",\"aspect_ratio\":\"landscape\",\"remove_watermark\":true}}",
"remainedCredits": 2510330,
"resultJson": "{\"resultUrls\":[\"https://example.com/generated-image.jpg\"]}",
"state": "success",
"taskId": "e989621f54392584b05867f87b160672",
"updateTime": 1755599644000
},
"msg": "Playground task completed successfully."
}
```
## 7. 响应格式
### 7.1 成功响应示例
```json
{
"code": 200,
"message": "success",
"data": {
"taskId": "task_12345678",
"model": "sora-2-text-to-video",
"state": "success",
"param": "{\"model\":\"sora-2-text-to-video\",\"callBackUrl\":\"https://your-domain.com/api/callback\",\"input\":{\"prompt\":\"A professor stands at the front of a lively classroom, enthusiastically giving a lecture. On the blackboard behind him are colorful chalk diagrams. With an animated gesture, he declares to the students: “Sora 2 is now available on Kie AI, making it easier than ever to create stunning videos.” The students listen attentively, some smiling and taking notes.\",\"aspect_ratio\":\"landscape\",\"remove_watermark\":true}}",
"resultJson": "{\"resultUrls\":[\"https://example.com/generated-image.jpg\"]}",
"failCode": "",
"failMsg": "",
"completeTime": 1698765432000,
"createTime": 1698765400000,
"updateTime": 1698765432000
}
}
```
### 7.2 错误响应示例
```json
{
"code": 400,
"message": "Invalid input parameters",
"data": null
}
```
## 8. 状态码说明
### 8.1 HTTP状态码
| 状态码 | 说明 |
|--------|------|
| 200 | 请求成功 |
| 400 | 请求参数错误 |
| 401 | 未授权，API密钥无效 |
| 403 | 禁止访问 |
| 429 | 请求过于频繁，触发限流 |
| 500 | 服务器内部错误 |
| 503 | 服务不可用 |
### 8.2 任务状态码
| 状态码 | 说明 |
|--------|------|
| pending | 任务等待处理 |
| processing | 任务正在处理中 |
| success | 任务执行成功 |
| failed | 任务执行失败 |
## 9. 最佳实践
### 9.1 异常处理
在实际应用中，建议对网络请求进行异常处理，包括超时处理和重试机制：
```java
public static String createVideoTaskWithRetry(int maxRetries) {
for (int i = 0; i < maxRetries; i++) {
try {
String taskId = createVideoTask();
if (taskId != null) {
return taskId;
}
} catch (Exception e) {
System.err.println("第" + (i+1) + "次尝试失败: " + e.getMessage());
// 等待一段时间后重试
try {
Thread.sleep(1000 * (i + 1)); // 递增等待时间
} catch (InterruptedException ie) {
Thread.currentThread().interrupt();
break;
}
}
}
return null;
}
```
### 9.2 回调处理
建议实现回调接口来处理任务完成的通知：
```java
@RestController
@RequestMapping("/api/callback")
public class KieAICallbackController {
@PostMapping
public ResponseEntity handleCallback(@RequestBody Map payload) {
try {
String taskId = (String) payload.get("task_id");
String status = (String) payload.get("status");
String videoUrl = (String) payload.get("video_url");
// 处理任务完成后的逻辑
if ("completed".equals(status)) {
// 保存视频URL到数据库
saveVideoUrl(taskId, videoUrl);
System.out.println("视频生成完成，任务ID: " + taskId + ", 视频地址: " + videoUrl);
} else if ("failed".equals(status)) {
// 处理失败情况
System.err.println("视频生成失败，任务ID: " + taskId);
}
return ResponseEntity.ok("success");
} catch (Exception e) {
return ResponseEntity.status(500).body("error");
}
}
private void saveVideoUrl(String taskId, String videoUrl) {
// 实现保存视频URL的逻辑
}
}
```
## 10. 注意事项
1. **API密钥安全**：请妥善保管API密钥，不要在客户端代码中暴露
2. **请求频率限制**：遵守API的请求频率限制，避免被限流
3. **回调地址**：确保回调地址可以被外网访问
4. **错误处理**：合理处理各种异常情况，包括网络异常、API错误等
5. **日志记录**：记录关键操作日志，便于问题排查
## 11. 常见问题
### 11.1 如何获取API密钥？
请联系Kie AI官方获取API密钥。
### 11.2 视频生成需要多长时间？
视频生成时间取决于视频长度和复杂度，通常在几分钟内完成。
### 11.3 如何处理生成失败的任务？
可以通过查询任务状态接口获取失败原因，并根据需要重新提交任务。
### 11.4 是否支持批量生成？
支持批量生成，但需要注意API的并发限制。