gemini-to-seedream-migration

从 Gemini 迁移到 SeeDream v4.5

按照这套经过验证、可用于生产环境的工作流，将 AI 图像生成从 Google Gemini 2.5 Flash Image 迁移到 BytePlus SeeDream v4.5。

快速开始

迁移概览：

• 将 Gemini SDK 替换为 BytePlus REST API
• 更新环境变量和验证逻辑
• 将 API 路由迁移到新客户端
• 测试并验证更改
• 更新文档

优势：

• 支持更高分辨率（最高 4K，而非 2K）
• 更好地控制图像尺寸和生成过程
• 内置提示词优化，可提升质量
• 成本可能更低（请查看 BytePlus 定价）
• 支持更多格式（新增 BMP、TIFF、GIF）

前提条件：

• 现有项目使用 Google Gemini 2.5 Flash Image
• BytePlus API 密钥（从 https://console.byteplus.com/ark/region:ark+ap-southeast-1/apiKey 获取）
• 带有图像生成端点的 TypeScript/JavaScript 项目

预计耗时： 完整迁移需要 3-4 小时

---

核心迁移工作流

阶段 1：环境设置

将 Gemini 环境变量替换为 BytePlus 配置。

步骤 1.1：更新 .env.example

查找并移除 Gemini 配置：

# REMOVE
GEMINI_API_KEY=your_google_ai_api_key_here

添加 BytePlus 配置：

# ADD
BYTEPLUS_API_KEY=your_byteplus_api_key_here

步骤 1.2：更新环境验证器

如果你使用了环境验证（推荐），请更新验证逻辑，将检查项从 GEMINI_API_KEY 改为 BYTEPLUS_API_KEY。

更改示例：

// OLD
{
  name: 'GEMINI_API_KEY',
  required: true,
  description: 'Google AI API key for image generation',
  setupUrl: 'https://aistudio.google.com/app/apikey',
}

// NEW
{
  name: 'BYTEPLUS_API_KEY',
  required: true,
  description: 'BytePlus SeeDream API key for image generation',
  setupUrl: 'https://console.byteplus.com/ark/region:ark+ap-southeast-1/apiKey',
}

步骤 1.3：将 API 密钥添加到本地环境

添加到你的 .env.local：

BYTEPLUS_API_KEY=your_actual_byteplus_api_key

步骤 1.4：验证环境

测试验证逻辑是否能正确检测新密钥：

npm run validate  # or your validation command

---

阶段 2：创建 BytePlus 客户端

为 BytePlus SeeDream v4.5 创建可复用的 REST API 客户端。

步骤 2.1：创建客户端文件

创建 lib/byteplus-client.ts（或项目中合适的路径）。

请参阅 references/client-template.ts，其中包含经过完整注释、可用于生产环境的模板。

关键实现要点：

• 使用原生 fetch API（无需 SDK）
• 将 base64 转换为 data URI 格式：data:image/png;base64,${base64String}
• 为所有 HTTP 状态码添加全面的错误处理
• 发出请求前验证 API 密钥
• 添加详细日志以便调试
• 返回符合应用预期的一致接口

步骤 2.2：配置模型参数

根据你的使用场景选择合适的参数：

模型 ID： seedream-4-5-251128（截至 2025 年 12 月的最新版本）

尺寸选项：

• 固定像素：2048x2560（纵向）、2560x2048（横向）、2048x2048（正方形）
• 语义尺寸：2K、4K（由模型确定具体尺寸）

提示词优化：

• mode: "standard" - 质量更高，速度较慢（约 45-60 秒）
• mode: "fast" - 质量良好，速度更快（约 15-30 秒）

其他设置：

• sequential_image_generation: "disabled" - 输出单张图像
• watermark: false - 不添加水印
• response_format: "b64_json" - 返回 Base64 格式

步骤 2.3：测试客户端

创建一个简单的测试来验证客户端是否正常工作：

const result = await generateImageWithByteplus({
  prompt: "A simple test image of a red circle",
  images: [] // or test images
})

console.log(result.imageUrl ? "Success!" : result.error)

---

阶段 3：迁移 API 路由

在所有 API 路由中，将 Gemini SDK 调用替换为 BytePlus 客户端。

步骤 3.1：移除 Gemini 导入

在每个 API 路由文件中：

// REMOVE
import { GoogleGenAI } from "@google/genai"

添加 BytePlus 导入：

// ADD
import { generateImageWithByteplus } from "@/lib/byteplus-client"

步骤 3.2：替换生成调用

之前（Gemini SDK）：

const genAI = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY! })

const result = await genAI.models.generateContent({
  model: "gemini-2.5-flash-image",
  contents: [{
    role: "user",
    parts: [
      { text: prompt },
      { inlineData: { mimeType: "image/png", data: base64Image1 } },
      { inlineData: { mimeType: "image/jpeg", data: base64Image2 } }
    ]
  }],
  config: {
    responseModalities: ["IMAGE"],
    imageConfig: { aspectRatio: "4:5" }
  }
})

// Extract image from candidates
const imagePart = result.candidates[0].content.parts.find(p => p.inlineData)
const base64Image = `data:${imagePart.inlineData.mimeType};base64,${imagePart.inlineData.data}`

之后（BytePlus REST）：

const result = await generateImageWithByteplus({
  prompt: prompt,
  images: [
    { data: base64Image1, mimeType: "image/png" },
    { data: base64Image2, mimeType: "image/jpeg" }
  ]
})

if (result.error) {
  return NextResponse.json({ error: result.error }, { status: 500 })
}

// Image already in data URI format
const base64Image = result.imageUrl

步骤 3.3：处理响应差异

BytePlus 不会在返回图像的同时返回文本。如果你的前端需要两者：

return NextResponse.json({
  imageUrl: result.imageUrl,
  text: "", // BytePlus doesn't generate text
  usage: result.usage
})

步骤 3.4：更新日志

替换 Gemini 专属的日志消息：

// OLD
console.log("[v0] Gemini API key available:", !!process.env.GEMINI_API_KEY)
console.log("[v0] Calling Gemini API...")

// NEW
console.log("[v0] BytePlus API key available:", !!process.env.BYTEPLUS_API_KEY)
console.log("[v0] Calling BytePlus SeeDream v4.5 API...")

---

阶段 4：清理依赖项

从项目依赖项中移除 Gemini SDK。

步骤 4.1：卸载 Gemini SDK

npm uninstall @google/genai

这会自动更新 package.json 和 package-lock.json。

步骤 4.2：确认已移除

检查是否还引用了 Gemini：

grep -i "genai\|gemini" package.json

预期结果：无匹配项（输出为空）。

步骤 4.3：重新构建

npm install
npx tsc --noEmit  # Verify no type errors

---

阶段 5：测试与验证

完整测试指南请参阅 references/testing-checklist.md。

快速验证：

1. 环境验证通过：npm run validate
2. TypeScript 编译通过：npx tsc --noEmit
3. Lint 检查通过：npm run lint
4. 构建成功：npm run build
5. 手动 API 测试可正确生成图像

测试场景：

• 正常场景：有效图像 + 提示词 → 生成图像
• API 密钥无效 → 返回 401，并显示清晰的消息
• 缺少图像 → 返回 400 错误
• 触发速率限制 → 返回 429，并显示重试消息
• 服务错误 → 返回 500，并显示重试消息

---

阶段 6：更新文档

更新所有文档，将 Gemini 替换为 BytePlus。

要更新的文件：

• README.md - 将“Gemini 2.5 Flash”替换为“BytePlus SeeDream v4.5”
• SETUP.md - 更新 API 密钥设置说明
• ARCHITECTURE.md - 更新 AI 集成部分
• 所有故障排除指南 - 更新错误代码和调试步骤

搜索剩余引用：

grep -ri "gemini\|google ai" *.md docs/*.md

---

主要差异：Gemini 与 BytePlus

详细的参数映射请参阅 references/api-comparison.md。

快速对比：

方面	Gemini 2.5 Flash	BytePlus SeeDream v4.5
集成	SDK (@google/genai)	REST API（原生 fetch）
身份验证	构造函数中的 API 密钥	请求头中的 Bearer 令牌
图像输入	inlineData 中的 Base64	image 数组中的 Data URI
分辨率	宽高比（4:5）	精确像素（2048x2560）
响应	candidates[].content.parts[]	data[0].b64_json
文本输出	支持	不支持

---

常见问题

详细解决方案请参阅 references/troubleshooting.md。

常见错误：

1. 忘记使用 Data URI 格式 - BytePlus 要求使用 data:image/png;base64,...，而非纯 Base64
2. 模型 ID 错误 - 使用 seedream-4-5-251128，而非 seedream-4.5
3. 缺少错误处理 - 处理所有 HTTP 状态代码（400、401、429、500）
4. 未验证 API 密钥 - 发起请求前检查密钥是否存在
5. 图像格式不正确 - 确保图像使用受支持的格式（PNG/JPEG/WEBP）

---

快速参考

Gemini SDK 模式

import { GoogleGenAI } from "@google/genai"

const genAI = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY! })

const result = await genAI.models.generateContent({
  model: "gemini-2.5-flash-image",
  contents: [{
    role: "user",
    parts: [
      { text: prompt },
      { inlineData: { mimeType, data: base64String } }
    ]
  }],
  config: {
    responseModalities: ["IMAGE"],
    imageConfig: { aspectRatio: "4:5" }
  }
})

BytePlus REST 模式

import { generateImageWithByteplus } from "@/lib/byteplus-client"

const result = await generateImageWithByteplus({
  prompt: prompt,
  images: [{ data: base64String, mimeType: "image/png" }]
})

if (result.error) {
  // Handle error
}

---

错误处理

完整指南请参阅 references/error-handling.md。

HTTP 状态代码：

• 400 - 请求无效（检查图像格式、大小、宽高比）
• 401 - 身份验证失败（API 密钥无效）
• 429 - 超出速率限制（实现退避机制）
• 500 - 服务错误（使用指数退避重试）

错误处理器示例：

if (!response.ok) {
  switch (response.status) {
    case 400:
      return { error: "Invalid image or prompt" }
    case 401:
      return { error: "BytePlus API authentication failed" }
    case 429:
      return { error: "Rate limit exceeded, please try again later" }
    case 500:
      return { error: "BytePlus service error, please retry" }
    default:
      return { error: "Failed to generate image" }
  }
}

---

成功标准

满足以下条件即表示迁移完成：

• ✅ 所有 API 路由均使用 BytePlus，而非 Gemini
• ✅ 环境验证通过
• ✅ TypeScript 编译通过（npx tsc --noEmit）
• ✅ Lint 检查通过（npm run lint）
• ✅ 构建成功
• ✅ 生成的图像符合质量预期
• ✅ 妥善处理所有错误场景
• ✅ 文档已更新
• ✅ 生产环境部署稳定

---

其他资源

• BytePlus API 文档： https://docs.byteplus.com/en/docs/ModelArk/1666945
• API 控制台： https://console.byteplus.com/ark/region:ark+ap-southeast-1/apiKey
• 模型定价： https://docs.byteplus.com/en/docs/ModelArk/1099320#image-generation
• 提示词指南： https://docs.byteplus.com/en/docs/ModelArk/1829186

---

故障排除

常见问题及解决方案请参阅 references/troubleshooting.md。

API 参数详情请参阅 references/api-comparison.md。

完整测试清单请参阅 references/testing-checklist.md。