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 ルートを新しいクライアントに移行します
• 変更をテストして検証します
• ドキュメントを更新します

メリット：

• より高い解像度に対応（2K に対して最大 4K）
• 画像の寸法と生成をより細かく制御できます
• 品質向上のためのプロンプト最適化機能を内蔵
• コストを削減できる可能性があります（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 をデータ 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" - 画像を 1 枚だけ出力します
• 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 配列内のデータ URI
解像度	アスペクト比（4:5）	正確なピクセル数（2048x2560）
レスポンス	candidates[].content.parts[]	data[0].b64_json
テキスト出力	対応	非対応

---

よくある落とし穴

詳細な解決策については、references/troubleshooting.md を参照してください。

よくある間違い：

1. データ URI 形式を忘れる - BytePlus ではプレーンな Base64 ではなく、data:image/png;base64,... が必要です
2. モデル ID が間違っている - seedream-4.5 ではなく seedream-4-5-251128 を使用します
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 ルートで Gemini ではなく BytePlus を使用している
• ✅ 環境検証に合格している
• ✅ 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 を参照してください。