1250 lines
51 KiB
Markdown
1250 lines
51 KiB
Markdown
# 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
|
||
<dependencies>
|
||
<!-- Jackson for JSON processing -->
|
||
<dependency>
|
||
<groupId>com.fasterxml.jackson.core</groupId>
|
||
<artifactId>jackson-databind</artifactId>
|
||
<version>2.15.2</version>
|
||
</dependency>
|
||
|
||
<!-- HttpClient for HTTP requests -->
|
||
<dependency>
|
||
<groupId>org.apache.httpcomponents</groupId>
|
||
<artifactId>httpclient</artifactId>
|
||
<version>4.5.13</version>
|
||
</dependency>
|
||
</dependencies>
|
||
```
|
||
|
||
## 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<String, Object> 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<String, Object> 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<String, String> 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<String, String> 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<String, String> headers) {
|
||
return HttpRequestUtils.postWithHeaders(url, jsonPayload, null, headers);
|
||
}
|
||
|
||
/**
|
||
* 带请求头的GET请求方法
|
||
* @param url 请求URL
|
||
* @param headers 请求头
|
||
* @return 响应结果
|
||
*/
|
||
private String getWithHeaders(String url, Map<String, String> 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<String> createTextToVideoTask(
|
||
@Parameter(description = "请求参数", required = true, schema = @Schema(implementation = JSONObject.class))
|
||
@RequestBody Map<String, Object> 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<String> 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<String, Object> input = new HashMap<>();
|
||
input.put("prompt", prompt);
|
||
input.put("aspect_ratio", aspectRatio);
|
||
if (removeWatermark != null) {
|
||
input.put("remove_watermark", removeWatermark);
|
||
}
|
||
|
||
Map<String, Object> 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<String, Object> input = new HashMap<>();
|
||
input.put("image_urls", imageUrl);
|
||
input.put("aspect_ratio", aspectRatio);
|
||
if (removeWatermark != null) {
|
||
input.put("remove_watermark", removeWatermark);
|
||
}
|
||
|
||
Map<String, Object> 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
|
||
<dependencies>
|
||
<!-- Apache HttpClient -->
|
||
<dependency>
|
||
<groupId>org.apache.httpcomponents</groupId>
|
||
<artifactId>httpclient</artifactId>
|
||
<version>4.5.13</version>
|
||
</dependency>
|
||
|
||
<!-- Fastjson -->
|
||
<dependency>
|
||
<groupId>com.alibaba</groupId>
|
||
<artifactId>fastjson</artifactId>
|
||
<version>1.2.83</version>
|
||
</dependency>
|
||
|
||
<!-- Lombok (可选，用于简化Java代码) -->
|
||
<dependency>
|
||
<groupId>org.projectlombok</groupId>
|
||
<artifactId>lombok</artifactId>
|
||
<version>1.18.24</version>
|
||
<scope>provided</scope>
|
||
</dependency>
|
||
</dependencies>
|
||
```
|
||
|
||
### 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<String> handleCallback(@RequestBody Map<String, Object> 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的并发限制。 |