910 lines
28 KiB
Markdown
910 lines
28 KiB
Markdown
# Kie AI Nano Banana API Java集成产品需求文档 (PRD)
|
||
|
||
## 1. 产品概述
|
||
|
||
### 1.1 产品背景
|
||
Nano Banana API是Google Gemini 2.5 Flash Image Preview模型的别名，是一个先进的AI图像生成和编辑平台。通过Kie AI平台提供的API接口，开发者可以以更低的成本（约0.02美元/图片）访问这一强大的AI图像处理能力，相比Google官方API（0.039美元/图片）节省近50%的成本。
|
||
|
||
### 1.2 产品定位
|
||
为Java开发者提供便捷、经济的AI图像生成和编辑解决方案，支持文本生成图像、图像编辑、背景替换、角色一致性保持等核心功能。
|
||
|
||
### 1.3 目标用户
|
||
- Java后端开发者
|
||
- 内容创作平台开发团队
|
||
- 电商图像处理系统
|
||
- 社交媒体应用开发者
|
||
- AI图像处理服务提供商
|
||
|
||
## 2. 核心功能需求
|
||
|
||
### 2.1 功能模块概览
|
||
基于Nano Banana API的核心能力，本次集成将实现以下功能模块：
|
||
|
||
| 功能模块 | 描述 | 优先级 |
|
||
|---------|------|--------|
|
||
| 文本生成图像 | 根据自然语言描述生成高质量图像 | P0 |
|
||
| 图像编辑 | 基于指令对现有图像进行精确编辑 | P0 |
|
||
| 背景替换 | 智能替换或增强图像背景 | P1 |
|
||
| 角色一致性 | 在不同场景中保持角色外观一致 | P1 |
|
||
| 任务状态查询 | 查询异步任务的处理状态和结果 | P0 |
|
||
|
||
### 2.2 API接口设计
|
||
|
||
#### 2.2.1 接口基础信息
|
||
- **统一接口地址**: `https://api.kie.ai/api/v1/jobs/createTask`
|
||
- **请求方法**: POST
|
||
- **认证方式**: Bearer Token
|
||
- **请求格式**: JSON (UTF-8)
|
||
- **响应格式**: JSON
|
||
|
||
#### 2.2.2 认证配置
|
||
```
|
||
Authorization: Bearer {API_KEY}
|
||
Content-Type: application/json
|
||
```
|
||
|
||
#### 2.2.3 通用请求结构
|
||
所有功能都使用统一的接口地址，通过 `model` 参数区分不同的功能模块：
|
||
|
||
```json
|
||
{
|
||
"model": "模型名称",
|
||
"callBackUrl": "回调地址（可选）",
|
||
"input": {
|
||
// 具体功能参数
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 2.2.4 支持的模型类型
|
||
| 模型名称 | 功能描述 | 对应功能模块 |
|
||
|---------|---------|-------------|
|
||
| google/nano-banana | 文本生成图像 | 文本生成图像 |
|
||
| google/nano-banana-edit | 图像编辑 | 图像编辑/背景替换/角色一致性 |
|
||
|
||
## 3. 详细功能规格
|
||
|
||
### 3.1 文本生成图像 (google/nano-banana)
|
||
|
||
#### 3.1.1 业务场景
|
||
- 内容创作：根据文章内容自动生成配图
|
||
- 电商营销：根据产品描述生成宣传图片
|
||
- 社交媒体：为用户文本内容生成视觉化表达
|
||
|
||
#### 3.1.2 接口规格
|
||
**请求路径**: `POST https://api.kie.ai/api/v1/jobs/createTask`
|
||
|
||
**请求参数**:
|
||
```json
|
||
{
|
||
"model": "google/nano-banana",
|
||
"callBackUrl": "https://your-domain.com/api/callback",
|
||
"input": {
|
||
"prompt": "图像生成的文本描述",
|
||
"output_format": "输出格式",
|
||
"image_size": "图像尺寸比例"
|
||
}
|
||
}
|
||
```
|
||
|
||
**参数说明**:
|
||
| 参数名 | 类型 | 必填 | 说明 | 示例值 |
|
||
|--------|------|------|------|--------|
|
||
| model | String | 是 | 模型名称，固定值 | "google/nano-banana" |
|
||
| callBackUrl | String | 否 | 异步回调地址 | "https://your-domain.com/api/callback" |
|
||
| input.prompt | String | 是 | 图像生成的文本描述 | "A surreal painting of a giant banana floating in space, stars and galaxies in the background, vibrant colors, digital art" |
|
||
| input.output_format | String | 否 | 输出格式 | "png", "jpg", "webp" |
|
||
| input.image_size | String | 否 | 图像尺寸比例 | "1:1", "16:9", "9:16", "4:3" |
|
||
|
||
**请求示例**:
|
||
```bash
|
||
curl -X POST "https://api.kie.ai/api/v1/jobs/createTask" \
|
||
-H "Content-Type: application/json" \
|
||
-H "Authorization: Bearer YOUR_API_KEY" \
|
||
-d '{
|
||
"model": "google/nano-banana",
|
||
"callBackUrl": "https://your-domain.com/api/callback",
|
||
"input": {
|
||
"prompt": "A surreal painting of a giant banana floating in space, stars and galaxies in the background, vibrant colors, digital art",
|
||
"output_format": "png",
|
||
"image_size": "1:1"
|
||
}
|
||
}'
|
||
```
|
||
|
||
**响应格式**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": {
|
||
"taskId": "nano_text_12345678",
|
||
"model": "google/nano-banana",
|
||
"state": "processing",
|
||
"createTime": 1698765400000
|
||
}
|
||
}
|
||
```
|
||
|
||
### 3.2 图像编辑 (google/nano-banana-edit)
|
||
|
||
#### 3.2.1 业务场景
|
||
- 产品图片优化：调整商品图片的细节
|
||
- 人像美化：对人物照片进行精细调整
|
||
- 场景修改：修改图片中的特定元素
|
||
- 创意设计：将照片转换为角色模型等创意内容
|
||
|
||
#### 3.2.2 接口规格
|
||
**请求路径**: `POST https://api.kie.ai/api/v1/jobs/createTask`
|
||
|
||
**请求参数**:
|
||
```json
|
||
{
|
||
"model": "google/nano-banana-edit",
|
||
"callBackUrl": "https://your-domain.com/api/callback",
|
||
"input": {
|
||
"prompt": "编辑指令描述",
|
||
"image_urls": ["图像URL数组"],
|
||
"output_format": "输出格式",
|
||
"image_size": "图像尺寸比例"
|
||
}
|
||
}
|
||
```
|
||
|
||
**参数说明**:
|
||
| 参数名 | 类型 | 必填 | 说明 | 示例值 |
|
||
|--------|------|------|------|--------|
|
||
| model | String | 是 | 模型名称，固定值 | "google/nano-banana-edit" |
|
||
| callBackUrl | String | 否 | 异步回调地址 | "https://your-domain.com/api/callback" |
|
||
| input.prompt | String | 是 | 编辑指令描述 | "turn this photo into a character figure. Behind it, place a box with the character's image printed on it" |
|
||
| input.image_urls | Array | 是 | 原始图像URL数组 | ["https://example.com/image.png"] |
|
||
| input.output_format | String | 否 | 输出格式 | "png", "jpg", "webp" |
|
||
| input.image_size | String | 否 | 图像尺寸比例 | "1:1", "16:9", "9:16", "4:3" |
|
||
|
||
**请求示例**:
|
||
```bash
|
||
curl -X POST "https://api.kie.ai/api/v1/jobs/createTask" \
|
||
-H "Content-Type: application/json" \
|
||
-H "Authorization: Bearer YOUR_API_KEY" \
|
||
-d '{
|
||
"model": "google/nano-banana-edit",
|
||
"callBackUrl": "https://your-domain.com/api/callback",
|
||
"input": {
|
||
"prompt": "turn this photo into a character figure. Behind it, place a box with the character'\''s image printed on it, and a computer showing the Blender modeling process on its screen. In front of the box, add a round plastic base with the character figure standing on it. set the scene indoors if possible",
|
||
"image_urls": [
|
||
"https://file.aiquickdraw.com/custom-page/akr/section-images/1756223420389w8xa2jfe.png"
|
||
],
|
||
"output_format": "png",
|
||
"image_size": "1:1"
|
||
}
|
||
}'
|
||
```
|
||
|
||
**响应格式**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": {
|
||
"taskId": "nano_edit_12345678",
|
||
"model": "google/nano-banana-edit",
|
||
"state": "processing",
|
||
"createTime": 1698765400000
|
||
}
|
||
}
|
||
```
|
||
|
||
### 3.3 背景替换 (google/nano-banana-edit)
|
||
|
||
#### 3.3.1 业务场景
|
||
- 电商产品图：统一产品背景风格
|
||
- 证件照处理：更换证件照背景
|
||
- 营销素材：为产品图片添加品牌背景
|
||
|
||
#### 3.3.2 接口规格
|
||
**请求路径**: `POST https://api.kie.ai/api/v1/jobs/createTask`
|
||
|
||
**请求参数**:
|
||
```json
|
||
{
|
||
"model": "google/nano-banana-edit",
|
||
"callBackUrl": "https://your-domain.com/api/callback",
|
||
"input": {
|
||
"prompt": "背景替换描述",
|
||
"image_urls": ["原始图像URL"],
|
||
"output_format": "输出格式",
|
||
"image_size": "图像尺寸比例"
|
||
}
|
||
}
|
||
```
|
||
|
||
**参数说明**:
|
||
| 参数名 | 类型 | 必填 | 说明 | 示例值 |
|
||
|--------|------|------|------|--------|
|
||
| model | String | 是 | 模型名称，固定值 | "google/nano-banana-edit" |
|
||
| callBackUrl | String | 否 | 异步回调地址 | "https://your-domain.com/api/callback" |
|
||
| input.prompt | String | 是 | 背景替换描述 | "replace background with white studio background" |
|
||
| input.image_urls | Array | 是 | 原始图像URL数组 | ["https://example.com/image.png"] |
|
||
| input.output_format | String | 否 | 输出格式 | "png", "jpg", "webp" |
|
||
| input.image_size | String | 否 | 图像尺寸比例 | "1:1", "16:9", "9:16", "4:3" |
|
||
|
||
**响应格式**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": {
|
||
"taskId": "nano_bg_12345678",
|
||
"model": "google/nano-banana-edit",
|
||
"state": "processing",
|
||
"createTime": 1698765400000
|
||
}
|
||
}
|
||
```
|
||
|
||
### 3.4 角色一致性 (google/nano-banana-edit)
|
||
|
||
#### 3.4.1 业务场景
|
||
- 动画制作：保持角色在不同场景的一致性
|
||
- 品牌营销：维持品牌吉祥物形象统一
|
||
- 故事创作：确保故事角色外观连贯
|
||
|
||
#### 3.4.2 接口规格
|
||
**请求路径**: `POST https://api.kie.ai/api/v1/jobs/createTask`
|
||
|
||
**请求参数**:
|
||
```json
|
||
{
|
||
"model": "google/nano-banana-edit",
|
||
"callBackUrl": "https://your-domain.com/api/callback",
|
||
"input": {
|
||
"prompt": "角色场景描述",
|
||
"image_urls": ["参考角色图像URL"],
|
||
"output_format": "输出格式",
|
||
"image_size": "图像尺寸比例"
|
||
}
|
||
}
|
||
```
|
||
|
||
**参数说明**:
|
||
| 参数名 | 类型 | 必填 | 说明 | 示例值 |
|
||
|--------|------|------|------|--------|
|
||
| model | String | 是 | 模型名称，固定值 | "google/nano-banana-edit" |
|
||
| callBackUrl | String | 否 | 异步回调地址 | "https://your-domain.com/api/callback" |
|
||
| input.prompt | String | 是 | 角色场景描述 | "keep the character consistent, place in a forest scene" |
|
||
| input.image_urls | Array | 是 | 参考角色图像URL数组 | ["https://example.com/character.png"] |
|
||
| input.output_format | String | 否 | 输出格式 | "png", "jpg", "webp" |
|
||
| input.image_size | String | 否 | 图像尺寸比例 | "1:1", "16:9", "9:16", "4:3" |
|
||
|
||
**响应格式**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": {
|
||
"taskId": "nano_char_12345678",
|
||
"model": "google/nano-banana-edit",
|
||
"state": "processing",
|
||
"createTime": 1698765400000
|
||
}
|
||
}
|
||
```
|
||
|
||
### 3.5 任务状态查询
|
||
|
||
#### 3.5.1 业务场景
|
||
- 异步任务监控：实时跟踪图像生成进度
|
||
- 结果获取：获取完成任务的结果图像
|
||
- 错误处理：处理任务失败情况
|
||
|
||
#### 3.5.2 接口规格
|
||
**请求路径**: `GET https://api.kie.ai/api/v1/jobs/{taskId}`
|
||
|
||
**请求参数**:
|
||
| 参数名 | 类型 | 必填 | 说明 | 示例值 |
|
||
|--------|------|------|------|--------|
|
||
| taskId | String | 是 | 任务ID | "nano_12345678" |
|
||
|
||
**响应格式**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": {
|
||
"taskId": "nano_12345678",
|
||
"model": "google/nano-banana",
|
||
"state": "success",
|
||
"progress": 100,
|
||
"resultUrls": [
|
||
"https://cdn.kie.ai/results/nano_12345678_1.png"
|
||
],
|
||
"createTime": 1698765400000,
|
||
"completeTime": 1698765432000,
|
||
"errorMessage": null
|
||
}
|
||
}
|
||
```
|
||
|
||
**状态说明**:
|
||
| 状态值 | 说明 | 处理建议 |
|
||
|--------|------|----------|
|
||
| queuing | 任务排队中 | 继续轮询 |
|
||
| generating | 任务处理中 | 继续轮询 |
|
||
| success | 任务完成 | 获取结果 |
|
||
| fail | 任务失败 | 查看错误信息 |
|
||
|
||
## 4. 技术实现规范
|
||
|
||
### 4.1 项目结构
|
||
基于现有项目结构，在 `com.integration.api` 包下新增 nano-banana 相关功能模块：
|
||
|
||
```
|
||
models-integration/
|
||
├── src/main/java/com/integration/api/
|
||
│ ├── Application.java # 主启动类
|
||
│ ├── config/
|
||
│ │ ├── SwaggerConfig.java # 现有Swagger配置
|
||
│ │ └── NanoBananaConfig.java # 新增：Nano Banana API配置
|
||
│ ├── controller/
|
||
│ │ ├── ArticleController.java # 现有文章控制器
|
||
│ │ ├── KieAI2VideoController.java # 现有KieAI视频生成控制器
|
||
│ │ ├── KieAICallbackController.java # 现有回调控制器
|
||
│ │ └── KieAI2ImageController.java # 新增：Kie AI图像生成控制器
|
||
│ ├── dto/
|
||
│ │ ├── CreateTaskRequest.java # 新增：统一任务创建请求
|
||
│ │ ├── TextToImageInput.java # 新增：文本生图输入参数
|
||
│ │ ├── ImageEditInput.java # 新增：图像编辑输入参数
|
||
│ │ ├── NanoBananaResponse.java # 新增：响应基类
|
||
│ │ ├── CreateTaskResponse.java # 新增：创建任务响应
|
||
│ │ └── QueryTaskResponse.java # 新增：查询任务响应
|
||
│ ├── helper/
|
||
│ │ ├── ConfigConstant.java # 现有配置常量
|
||
│ │ ├── DigestUtil.java # 现有摘要工具
|
||
│ │ ├── HttpRequestUtils.java # 现有HTTP工具
|
||
│ │ ├── XbbException.java # 现有异常类
|
||
│ │ └── NanoBananaHelper.java # 新增：Nano Banana工具类
|
||
│ ├── mapper/
|
||
│ │ ├── ArticleMapper.java # 现有文章映射器
|
||
│ │ └── NanoBananaTaskMapper.java # 新增：任务映射器
|
||
│ ├── model/
|
||
│ │ ├── Article.java # 现有文章实体
|
||
│ │ ├── NanoBananaTask.java # 新增：任务实体
|
||
│ │ ├── ResponseResult.java # 现有响应结果
|
||
│ │ ├── Sora2Request.java # 现有Sora2请求
|
||
│ │ ├── TaskStatus.java # 现有任务状态
|
||
│ │ └── request/ # 现有请求模型目录
|
||
│ ├── enums/
|
||
│ │ ├── ModelType.java # 新增：模型类型枚举
|
||
│ │ ├── NanoBananaTaskState.java # 新增：任务状态枚举
|
||
│ │ ├── OutputFormat.java # 新增：输出格式枚举
|
||
│ │ └── ImageSize.java # 新增：图像尺寸枚举
|
||
│ └── service/
|
||
│ ├── ArticleService.java # 现有文章服务接口
|
||
│ ├── KieAIService.java # 现有KieAI服务
|
||
│ ├── NanoBananaService.java # 新增：Nano Banana服务接口
|
||
│ └── impl/
|
||
│ ├── ArticleServiceImpl.java # 现有文章服务实现
|
||
│ └── NanoBananaServiceImpl.java # 新增：Nano Banana服务实现
|
||
├── src/main/resources/
|
||
│ ├── application.yml # 应用配置（需更新）
|
||
│ └── logback.xml # 日志配置
|
||
├── pom.xml # Maven依赖配置（需更新）
|
||
└── logs/ # 日志文件目录
|
||
```
|
||
|
||
### 4.2 核心依赖
|
||
基于现有项目依赖，无需新增额外依赖，现有依赖已满足 Nano Banana API 集成需求：
|
||
|
||
```xml
|
||
<!-- 现有依赖已包含以下核心组件 -->
|
||
<dependencies>
|
||
<!-- Spring Boot Web Starter -->
|
||
<dependency>
|
||
<groupId>org.springframework.boot</groupId>
|
||
<artifactId>spring-boot-starter-web</artifactId>
|
||
<version>2.7.5</version>
|
||
</dependency>
|
||
|
||
<!-- Spring Boot Validation -->
|
||
<dependency>
|
||
<groupId>org.springframework.boot</groupId>
|
||
<artifactId>spring-boot-starter-validation</artifactId>
|
||
<version>2.7.5</version>
|
||
</dependency>
|
||
|
||
<!-- HTTP Client (现有OkHttp和HttpAsyncClient) -->
|
||
<dependency>
|
||
<groupId>com.squareup.okhttp3</groupId>
|
||
<artifactId>okhttp</artifactId>
|
||
<version>3.14.9</version>
|
||
</dependency>
|
||
<dependency>
|
||
<groupId>org.apache.httpcomponents</groupId>
|
||
<artifactId>httpasyncclient</artifactId>
|
||
<version>4.1</version>
|
||
</dependency>
|
||
|
||
<!-- JSON处理 (现有FastJSON) -->
|
||
<dependency>
|
||
<groupId>com.alibaba</groupId>
|
||
<artifactId>fastjson</artifactId>
|
||
<version>1.2.48.sec06</version>
|
||
</dependency>
|
||
|
||
<!-- Lombok -->
|
||
<dependency>
|
||
<groupId>org.projectlombok</groupId>
|
||
<artifactId>lombok</artifactId>
|
||
<version>1.18.24</version>
|
||
<optional>true</optional>
|
||
</dependency>
|
||
|
||
<!-- 日志 -->
|
||
<dependency>
|
||
<groupId>ch.qos.logback</groupId>
|
||
<artifactId>logback-classic</artifactId>
|
||
<version>1.2.11</version>
|
||
</dependency>
|
||
|
||
<!-- Swagger3文档 -->
|
||
<dependency>
|
||
<groupId>org.springdoc</groupId>
|
||
<artifactId>springdoc-openapi-ui</artifactId>
|
||
<version>1.7.0</version>
|
||
</dependency>
|
||
</dependencies>
|
||
```
|
||
|
||
### 4.3 配置文件
|
||
在现有 `application.yml` 基础上新增 Nano Banana API 相关配置：
|
||
|
||
```yaml
|
||
# 现有配置保持不变，新增以下配置
|
||
nano-banana:
|
||
api:
|
||
base-url: https://api.kie.ai/api/v1
|
||
api-key: ${NANO_BANANA_API_KEY:your-api-key}
|
||
timeout: 30000
|
||
retry-count: 3
|
||
retry-delay: 1000
|
||
callback:
|
||
base-url: ${server.domain:http://localhost:8080}
|
||
path: /api/nano-banana/callback
|
||
task:
|
||
max-concurrent: 10
|
||
cleanup-interval: 3600000 # 1小时清理一次过期任务
|
||
expire-time: 86400000 # 24小时任务过期时间
|
||
|
||
# 现有配置示例（保持不变）
|
||
server:
|
||
port: 8080
|
||
servlet:
|
||
context-path: /
|
||
|
||
spring:
|
||
application:
|
||
name: models-integration
|
||
datasource:
|
||
type: com.alibaba.druid.pool.DruidDataSource
|
||
driver-class-name: com.mysql.cj.jdbc.Driver
|
||
url: jdbc:mysql://localhost:3306/models_integration?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai
|
||
username: ${DB_USERNAME:root}
|
||
password: ${DB_PASSWORD:123456}
|
||
|
||
# 日志配置（现有基础上新增）
|
||
logging:
|
||
level:
|
||
com.integration.api: DEBUG
|
||
org.springframework.web: INFO
|
||
pattern:
|
||
console: "%d{yyyy-MM-dd HH:mm:ss} [%thread] %-5level %logger{36} - %msg%n"
|
||
```
|
||
|
||
### 4.4 核心模型类
|
||
基于现有项目实体设计模式，新增 Nano Banana 任务模型类：
|
||
|
||
#### 4.4.1 NanoBananaTask 模型类
|
||
```java
|
||
package com.integration.api.model;
|
||
|
||
import com.baomidou.mybatisplus.annotation.IdType;
|
||
import com.baomidou.mybatisplus.annotation.TableId;
|
||
import com.baomidou.mybatisplus.annotation.TableName;
|
||
import io.swagger.annotations.ApiModel;
|
||
import io.swagger.annotations.ApiModelProperty;
|
||
import lombok.Data;
|
||
import lombok.EqualsAndHashCode;
|
||
import lombok.experimental.Accessors;
|
||
|
||
import java.io.Serializable;
|
||
import java.util.Date;
|
||
|
||
/**
|
||
* Nano Banana任务管理表
|
||
*/
|
||
@Data
|
||
@EqualsAndHashCode(callSuper = false)
|
||
@Accessors(chain = true)
|
||
@TableName("nano_banana_task")
|
||
@ApiModel(value="NanoBananaTask对象", description="Nano Banana任务管理表")
|
||
public class NanoBananaTask implements Serializable {
|
||
|
||
private static final long serialVersionUID = 1L;
|
||
|
||
@ApiModelProperty(value = "任务ID")
|
||
@TableId(value = "id", type = IdType.AUTO)
|
||
private Long id;
|
||
|
||
@ApiModelProperty(value = "外部任务ID")
|
||
private String taskId;
|
||
|
||
@ApiModelProperty(value = "模型类型")
|
||
private String modelType;
|
||
|
||
@ApiModelProperty(value = "任务状态")
|
||
private String status;
|
||
|
||
@ApiModelProperty(value = "提示词")
|
||
private String prompt;
|
||
|
||
@ApiModelProperty(value = "输入图片URLs")
|
||
private String imageUrls;
|
||
|
||
@ApiModelProperty(value = "输出格式")
|
||
private String outputFormat;
|
||
|
||
@ApiModelProperty(value = "图片尺寸")
|
||
private String imageSize;
|
||
|
||
@ApiModelProperty(value = "回调URL")
|
||
private String callbackUrl;
|
||
|
||
@ApiModelProperty(value = "结果图片URLs")
|
||
private String resultUrls;
|
||
|
||
@ApiModelProperty(value = "错误信息")
|
||
private String errorMessage;
|
||
|
||
@ApiModelProperty(value = "创建时间")
|
||
private Date createTime;
|
||
|
||
@ApiModelProperty(value = "更新时间")
|
||
private Date updateTime;
|
||
|
||
@ApiModelProperty(value = "完成时间")
|
||
private Date completeTime;
|
||
|
||
@ApiModelProperty(value = "用户ID")
|
||
private String userId;
|
||
|
||
@ApiModelProperty(value = "备注")
|
||
private String remark;
|
||
}
|
||
```
|
||
|
||
#### 4.4.2 数据传输对象类
|
||
基于现有项目的包结构，在 `dto` 包下创建请求响应传参对象：
|
||
|
||
**CreateTaskRequest.java**
|
||
```java
|
||
package com.integration.api.dto;
|
||
|
||
import io.swagger.annotations.ApiModel;
|
||
import io.swagger.annotations.ApiModelProperty;
|
||
import lombok.Data;
|
||
import javax.validation.constraints.NotBlank;
|
||
import javax.validation.constraints.NotNull;
|
||
|
||
@Data
|
||
@ApiModel(description = "创建任务请求")
|
||
public class CreateTaskRequest {
|
||
|
||
@ApiModelProperty(value = "模型类型", required = true)
|
||
@NotBlank(message = "模型类型不能为空")
|
||
private String model;
|
||
|
||
@ApiModelProperty(value = "回调URL")
|
||
private String callBackUrl;
|
||
|
||
@ApiModelProperty(value = "输入参数", required = true)
|
||
@NotNull(message = "输入参数不能为空")
|
||
private Object input;
|
||
}
|
||
```
|
||
|
||
**TextToImageInput.java**
|
||
```java
|
||
package com.integration.api.dto;
|
||
|
||
import io.swagger.annotations.ApiModel;
|
||
import io.swagger.annotations.ApiModelProperty;
|
||
import lombok.Data;
|
||
import javax.validation.constraints.NotBlank;
|
||
|
||
@Data
|
||
@ApiModel(description = "文本生图输入参数")
|
||
public class TextToImageInput {
|
||
|
||
@ApiModelProperty(value = "提示词", required = true)
|
||
@NotBlank(message = "提示词不能为空")
|
||
private String prompt;
|
||
|
||
@ApiModelProperty(value = "输出格式", example = "png")
|
||
private String output_format = "png";
|
||
|
||
@ApiModelProperty(value = "图片尺寸", example = "1:1")
|
||
private String image_size = "1:1";
|
||
}
|
||
```
|
||
|
||
**ImageEditInput.java**
|
||
```java
|
||
package com.integration.api.dto;
|
||
|
||
import io.swagger.annotations.ApiModel;
|
||
import io.swagger.annotations.ApiModelProperty;
|
||
import lombok.Data;
|
||
import javax.validation.constraints.NotBlank;
|
||
import javax.validation.constraints.NotEmpty;
|
||
import java.util.List;
|
||
|
||
@Data
|
||
@ApiModel(description = "图像编辑输入参数")
|
||
public class ImageEditInput {
|
||
|
||
@ApiModelProperty(value = "提示词", required = true)
|
||
@NotBlank(message = "提示词不能为空")
|
||
private String prompt;
|
||
|
||
@ApiModelProperty(value = "图片URLs", required = true)
|
||
@NotEmpty(message = "图片URLs不能为空")
|
||
private List<String> image_urls;
|
||
|
||
@ApiModelProperty(value = "输出格式", example = "png")
|
||
private String output_format = "png";
|
||
|
||
@ApiModelProperty(value = "图片尺寸", example = "1:1")
|
||
private String image_size = "1:1";
|
||
}
|
||
```
|
||
|
||
#### 4.4.3 枚举类
|
||
**ModelType.java**
|
||
```java
|
||
package com.integration.api.enums;
|
||
|
||
import lombok.AllArgsConstructor;
|
||
import lombok.Getter;
|
||
|
||
@Getter
|
||
@AllArgsConstructor
|
||
public enum ModelType {
|
||
TEXT_TO_IMAGE("google/nano-banana", "文本生成图像"),
|
||
IMAGE_EDIT("google/nano-banana-edit", "图像编辑");
|
||
|
||
private final String code;
|
||
private final String description;
|
||
|
||
public static ModelType fromCode(String code) {
|
||
for (ModelType type : values()) {
|
||
if (type.getCode().equals(code)) {
|
||
return type;
|
||
}
|
||
}
|
||
throw new IllegalArgumentException("不支持的模型类型: " + code);
|
||
}
|
||
}
|
||
```
|
||
|
||
**NanoBananaTaskState.java**
|
||
```java
|
||
package com.integration.api.enums;
|
||
|
||
import lombok.AllArgsConstructor;
|
||
import lombok.Getter;
|
||
|
||
@Getter
|
||
@AllArgsConstructor
|
||
public enum NanoBananaTaskState {
|
||
PENDING("pending", "等待中"),
|
||
PROCESSING("processing", "处理中"),
|
||
COMPLETED("completed", "已完成"),
|
||
FAILED("failed", "失败");
|
||
|
||
private final String code;
|
||
private final String description;
|
||
|
||
public static NanoBananaTaskState fromCode(String code) {
|
||
for (NanoBananaTaskState state : values()) {
|
||
if (state.getCode().equals(code)) {
|
||
return state;
|
||
}
|
||
}
|
||
throw new IllegalArgumentException("不支持的任务状态: " + code);
|
||
}
|
||
}
|
||
```
|
||
|
||
**OutputFormat.java**
|
||
```java
|
||
package com.integration.api.enums;
|
||
|
||
import lombok.AllArgsConstructor;
|
||
import lombok.Getter;
|
||
|
||
@Getter
|
||
@AllArgsConstructor
|
||
public enum OutputFormat {
|
||
PNG("png", "PNG格式"),
|
||
JPG("jpg", "JPG格式"),
|
||
JPEG("jpeg", "JPEG格式"),
|
||
WEBP("webp", "WEBP格式");
|
||
|
||
private final String code;
|
||
private final String description;
|
||
}
|
||
```
|
||
|
||
**ImageSize.java**
|
||
```java
|
||
package com.integration.api.enums;
|
||
|
||
import lombok.AllArgsConstructor;
|
||
import lombok.Getter;
|
||
|
||
@Getter
|
||
@AllArgsConstructor
|
||
public enum ImageSize {
|
||
SQUARE("1:1", "正方形"),
|
||
PORTRAIT_9_16("9:16", "竖版9:16"),
|
||
LANDSCAPE_16_9("16:9", "横版16:9"),
|
||
LANDSCAPE_4_3("4:3", "横版4:3");
|
||
|
||
private final String code;
|
||
private final String description;
|
||
}
|
||
```
|
||
|
||
## 5. 接口实现要点
|
||
|
||
### 5.1 异常处理策略
|
||
- **网络异常**: 自动重试机制，最多重试3次
|
||
- **API限流**: 实现请求队列和并发控制
|
||
- **参数验证**: 统一参数校验和错误提示
|
||
- **超时处理**: 设置合理的超时时间（30秒）
|
||
|
||
### 5.2 安全考虑
|
||
- **API密钥管理**: 使用环境变量存储敏感信息
|
||
- **请求签名**: 实现请求参数签名验证
|
||
- **访问控制**: 添加IP白名单和访问频率限制
|
||
- **数据加密**: 敏感数据传输加密
|
||
|
||
### 5.3 性能优化
|
||
- **连接池**: 使用HTTP连接池提高性能
|
||
- **异步处理**: 长时间任务采用异步处理模式
|
||
- **缓存策略**: 对频繁查询的任务状态进行缓存
|
||
- **监控告警**: 添加API调用监控和异常告警
|
||
|
||
## 6. 测试策略
|
||
|
||
### 6.1 单元测试
|
||
- Controller层接口测试
|
||
- Service层业务逻辑测试
|
||
- 工具类方法测试
|
||
- 异常处理测试
|
||
|
||
### 6.2 集成测试
|
||
- API接口端到端测试
|
||
- 异步任务处理测试
|
||
- 错误场景测试
|
||
- 性能压力测试
|
||
|
||
### 6.3 测试数据
|
||
```java
|
||
// 测试用例示例
|
||
public class NanoBananaTestData {
|
||
public static final String TEST_PROMPT = "一只可爱的橙色小猫坐在阳光明媚的窗台上";
|
||
public static final String TEST_IMAGE_URL = "https://example.com/test-image.jpg";
|
||
public static final String TEST_API_KEY = "test-api-key-12345";
|
||
}
|
||
```
|
||
|
||
## 7. 部署和运维
|
||
|
||
### 7.1 环境配置
|
||
- **开发环境**: 使用测试API密钥，启用详细日志
|
||
- **测试环境**: 模拟生产环境配置，进行性能测试
|
||
- **生产环境**: 使用正式API密钥，启用监控告警
|
||
|
||
### 7.2 监控指标
|
||
- API调用成功率
|
||
- 平均响应时间
|
||
- 任务处理时长
|
||
- 错误率统计
|
||
- 并发请求数
|
||
|
||
### 7.3 日志规范
|
||
```java
|
||
// 日志记录示例
|
||
log.info("开始处理文本生成图像任务, taskId: {}, prompt: {}", taskId, prompt);
|
||
log.warn("API调用超时, taskId: {}, 耗时: {}ms", taskId, duration);
|
||
log.error("任务处理失败, taskId: {}, 错误信息: {}", taskId, errorMsg);
|
||
```
|
||
|
||
## 8. 成本分析
|
||
|
||
### 8.1 API调用成本
|
||
- **Kie AI平台**: 0.02美元/图片
|
||
- **Google官方**: 0.039美元/图片
|
||
- **成本节省**: 约48.7%
|
||
|
||
### 8.2 开发成本
|
||
- **开发周期**: 预计2-3周
|
||
- **人力投入**: 1名高级Java开发工程师
|
||
- **测试周期**: 1周
|
||
|
||
### 8.3 运维成本
|
||
- **服务器资源**: 中等配置云服务器
|
||
- **监控工具**: 使用开源监控方案
|
||
- **维护成本**: 每月约2-4小时
|
||
|
||
## 9. 风险评估
|
||
|
||
### 9.1 技术风险
|
||
- **API稳定性**: Kie AI平台服务可用性依赖
|
||
- **性能瓶颈**: 高并发场景下的处理能力
|
||
- **兼容性**: 不同Java版本的兼容性问题
|
||
|
||
### 9.2 业务风险
|
||
- **成本控制**: API调用量超预期导致成本上升
|
||
- **质量保证**: 生成图像质量不符合业务要求
|
||
- **合规风险**: 生成内容的版权和合规性问题
|
||
|
||
### 9.3 风险缓解措施
|
||
- 实施API调用量监控和预警
|
||
- 建立图像质量评估机制
|
||
- 制定内容审核和过滤策略
|
||
- 准备备用API服务商方案
|
||
|
||
## 10. 项目里程碑
|
||
|
||
### 10.1 第一阶段 (Week 1-2)
|
||
- [ ] 完成基础架构搭建
|
||
- [ ] 实现文本生成图像功能
|
||
- [ ] 实现任务状态查询功能
|
||
- [ ] 完成单元测试
|
||
|
||
### 10.2 第二阶段 (Week 3)
|
||
- [ ] 实现图像编辑功能
|
||
- [ ] 实现背景替换功能
|
||
- [ ] 完成集成测试
|
||
- [ ] 性能优化
|
||
|
||
### 10.3 第三阶段 (Week 4)
|
||
- [ ] 实现角色一致性功能
|
||
- [ ] 完善异常处理和监控
|
||
- [ ] 部署测试环境
|
||
- [ ] 文档完善
|
||
|
||
## 11. 验收标准
|
||
|
||
### 11.1 功能验收
|
||
- [ ] 所有API接口正常调用
|
||
- [ ] 异步任务处理机制完善
|
||
- [ ] 错误处理和重试机制有效
|
||
- [ ] 性能指标达到预期
|
||
|
||
### 11.2 质量验收
|
||
- [ ] 单元测试覆盖率 > 80%
|
||
- [ ] 集成测试通过率 100%
|
||
- [ ] 代码质量检查通过
|
||
- [ ] 安全扫描无高危漏洞
|
||
|
||
### 11.3 文档验收
|
||
- [ ] API接口文档完整
|
||
- [ ] 部署运维文档齐全
|
||
- [ ] 用户使用指南清晰
|
||
- [ ] 故障排除手册完备
|
||
|
||
---
|