API リファレンス

Qwen Image Edit API 完全使用ガイド

API リファレンス

Qwen Image Edit APIの完全なリファレンスガイドです。すべてのメソッド、パラメータ、レスポンス形式について詳しく説明します。

🔐 認証

APIキーの設定

import { QwenImageEdit } from 'qwen-image-edit';

const editor = new QwenImageEdit({
  apiKey: 'qwen_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
  region: 'ap-northeast-1' // オプション
});

環境変数での設定

# .env ファイル
QWEN_API_KEY=qwen_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
QWEN_REGION=ap-northeast-1
// 環境変数から自動読み込み
const editor = new QwenImageEdit();

🎯 コアメソッド

editText()

画像内のテキストを編集します。

const result = await editor.editText({
  image: string | Buffer | File,
  prompt: string,
  options?: {
    quality?: 'low' | 'medium' | 'high',
    maxWidth?: number,
    maxHeight?: number,
    format?: 'jpg' | 'png' | 'webp'
  }
});

パラメータ

パラメータ必須説明
imagestring | Buffer | File編集する画像(ファイルパス、Buffer、またはFileオブジェクト)
promptstring編集指示(自然言語)
options.qualitystring出力品質(デフォルト: 'high')
options.maxWidthnumber最大幅(ピクセル)
options.maxHeightnumber最大高さ(ピクセル)
options.formatstring出力フォーマット(デフォルト: 'jpg')

レスポンス

interface EditTextResponse {
  imageUrl: string;        // 編集済み画像のURL
  credits: number;         // 使用クレジット数
  processingTime: number;  // 処理時間(ミリ秒)
  metadata: {
    originalSize: { width: number; height: number };
    outputSize: { width: number; height: number };
    detectedText?: string[];
  };
}

使用例

// 基本的な使用
const result = await editor.editText({
  image: './product.jpg',
  prompt: '価格を「¥1,000」から「¥800」に変更してください'
});

// 高度なオプション
const result = await editor.editText({
  image: './banner.jpg',
  prompt: 'タイトルを「セール中」に変更し、赤色にしてください',
  options: {
    quality: 'high',
    maxWidth: 1200,
    format: 'png'
  }
});

editElement()

画像に要素を追加、削除、または変更します。

const result = await editor.editElement({
  image: string | Buffer | File,
  prompt: string,
  options?: {
    quality?: 'low' | 'medium' | 'high',
    preserveAspectRatio?: boolean,
    blendMode?: 'normal' | 'multiply' | 'overlay'
  }
});

パラメータ

パラメータ必須説明
imagestring | Buffer | File編集する画像
promptstring要素編集指示
options.qualitystring出力品質
options.preserveAspectRatiobooleanアスペクト比を保持(デフォルト: true)
options.blendModestringブレンドモード

使用例

// ロゴの追加
const result = await editor.editElement({
  image: './photo.jpg',
  prompt: '右下角に会社ロゴを小さく追加してください'
});

// 透かしの追加
const result = await editor.editElement({
  image: './image.jpg',
  prompt: '中央に半透明の「サンプル」という透かしを追加してください',
  options: {
    blendMode: 'overlay'
  }
});

// 要素の削除
const result = await editor.editElement({
  image: './watermarked.jpg',
  prompt: '透かしを削除してください'
});

transferStyle()

画像のスタイルを転送または変更します。

const result = await editor.transferStyle({
  image: string | Buffer | File,
  styleImage?: string | Buffer | File,
  style?: string,
  intensity?: number,
  options?: {
    preserveContent?: boolean,
    colorOnly?: boolean
  }
});

パラメータ

パラメータ必須説明
imagestring | Buffer | File元画像
styleImagestring | Buffer | Fileスタイル参照画像
stylestring事前定義スタイル名
intensitynumberスタイル強度(0.0-1.0、デフォルト: 0.7)
options.preserveContentbooleanコンテンツを保持(デフォルト: true)
options.colorOnlyboolean色のみ転送(デフォルト: false)

事前定義スタイル

  • oil-painting - 油絵風
  • watercolor - 水彩画風
  • anime - アニメ風
  • vintage - ヴィンテージ風
  • black-white - モノクロ
  • sepia - セピア調
  • pop-art - ポップアート風
  • impressionist - 印象派風

使用例

// 事前定義スタイルの使用
const result = await editor.transferStyle({
  image: './portrait.jpg',
  style: 'oil-painting',
  intensity: 0.8
});

// カスタムスタイル画像の使用
const result = await editor.transferStyle({
  image: './photo.jpg',
  styleImage: './artwork.jpg',
  intensity: 0.6,
  options: {
    preserveContent: true
  }
});

analyzeImage()

画像を分析して詳細情報を取得します。

const result = await editor.analyzeImage({
  image: string | Buffer | File,
  analysisTypes: string[],
  options?: {
    language?: string,
    includeConfidence?: boolean
  }
});

分析タイプ

  • text - テキスト検出・認識
  • objects - オブジェクト検出
  • faces - 顔検出
  • colors - 色分析
  • quality - 画質評価
  • style - スタイル分析
  • composition - 構図分析

使用例

const analysis = await editor.analyzeImage({
  image: './complex-image.jpg',
  analysisTypes: ['text', 'objects', 'quality'],
  options: {
    language: 'ja',
    includeConfidence: true
  }
});

console.log('検出されたテキスト:', analysis.analysis.text?.content);
console.log('検出されたオブジェクト:', analysis.analysis.objects);
console.log('画質スコア:', analysis.analysis.quality?.overall);

🛠️ ユーティリティメソッド

resizeImage()

画像のサイズを変更します。

const result = await editor.resizeImage({
  image: string | Buffer | File,
  width?: number,
  height?: number,
  mode?: 'fit' | 'fill' | 'crop',
  quality?: number
});

パラメータ

パラメータ必須説明
imagestring | Buffer | Fileリサイズする画像
widthnumber目標幅
heightnumber目標高さ
modestringリサイズモード(デフォルト: 'fit')
qualitynumber品質(1-100、デフォルト: 90)

リサイズモード

  • fit - アスペクト比を保持してフィット
  • fill - 指定サイズに拡張(アスペクト比変更あり)
  • crop - 中央クロップでフィット

enhanceImage()

画像の品質を向上させます。

const result = await editor.enhanceImage({
  image: string | Buffer | File,
  enhancements: string[],
  intensity?: number
});

強化タイプ

  • quality - 全体的な画質向上
  • sharpness - シャープネス向上
  • brightness - 明度調整
  • contrast - コントラスト向上
  • saturation - 彩度向上
  • noise-reduction - ノイズ除去

cleanImage()

画像から不要な要素を除去します。

const result = await editor.cleanImage({
  image: string | Buffer | File,
  removeTypes: string[]
});

除去タイプ

  • watermarks - 透かし
  • logos - ロゴ
  • text - テキスト
  • artifacts - アーティファクト
  • noise - ノイズ

⚙️ 高度な設定

クライアント設定

const editor = new QwenImageEdit({
  apiKey: 'your-api-key',
  region: 'ap-northeast-1',
  timeout: 30000,           // タイムアウト(ミリ秒)
  maxRetries: 3,            // 最大再試行回数
  retryDelay: 1000,         // 再試行間隔(ミリ秒)
  baseURL: 'https://api.qwen.com/v1', // カスタムベースURL
  headers: {                // カスタムヘッダー
    'User-Agent': 'MyApp/1.0'
  }
});

プロキシ設定

const editor = new QwenImageEdit({
  apiKey: 'your-api-key',
  proxy: {
    host: 'proxy.example.com',
    port: 8080,
    auth: {
      username: 'user',
      password: 'pass'
    }
  }
});

SSL設定

const editor = new QwenImageEdit({
  apiKey: 'your-api-key',
  ssl: {
    rejectUnauthorized: false,  // 自己署名証明書を許可
    ca: fs.readFileSync('ca.pem'), // カスタムCA証明書
    cert: fs.readFileSync('cert.pem'), // クライアント証明書
    key: fs.readFileSync('key.pem')    // クライアント秘密鍵
  }
});

🚨 エラーハンドリング

エラータイプ

interface QwenError extends Error {
  code: string;
  statusCode?: number;
  details?: any;
}

一般的なエラーコード

エラーコード説明対処法
INVALID_API_KEYAPIキーが無効正しいAPIキーを設定
INSUFFICIENT_CREDITSクレジット不足クレジットを追加
RATE_LIMIT_EXCEEDEDレート制限超過しばらく待ってから再試行
IMAGE_TOO_LARGE画像サイズが大きすぎる画像を圧縮
UNSUPPORTED_FORMATサポートされていない形式サポートされている形式に変換
NETWORK_ERRORネットワークエラー接続を確認して再試行
TIMEOUTタイムアウトタイムアウト値を増加
SERVER_ERRORサーバーエラーしばらく待ってから再試行

エラーハンドリングの例

try {
  const result = await editor.editText({
    image: './image.jpg',
    prompt: 'テキストを編集してください'
  });
  
  console.log('成功:', result.imageUrl);
} catch (error) {
  switch (error.code) {
    case 'INVALID_API_KEY':
      console.error('APIキーを確認してください');
      break;
      
    case 'INSUFFICIENT_CREDITS':
      console.error('クレジットが不足しています');
      // クレジット購入ページにリダイレクト
      break;
      
    case 'RATE_LIMIT_EXCEEDED':
      console.error('レート制限に達しました。しばらく待ってから再試行してください');
      // 指数バックオフで再試行
      break;
      
    case 'IMAGE_TOO_LARGE':
      console.error('画像サイズが大きすぎます。圧縮してから再試行してください');
      // 画像を自動圧縮
      break;
      
    default:
      console.error('予期しないエラー:', error.message);
  }
}

📊 制限とクォータ

レート制限

プラン1分あたりのリクエスト1日あたりのリクエスト
無料10100
ベーシック601,000
プロ30010,000
エンタープライズ1,000無制限

画像制限

制限項目最大値
ファイルサイズ10MB
画像幅4096px
画像高さ4096px
バッチサイズ50画像

サポートされている形式

入力形式

  • JPEG (.jpg, .jpeg)
  • PNG (.png)
  • WebP (.webp)
  • BMP (.bmp)
  • TIFF (.tiff, .tif)

出力形式

  • JPEG (.jpg)
  • PNG (.png)
  • WebP (.webp)

🔗 Webhook

Webhook設定

const editor = new QwenImageEdit({
  apiKey: 'your-api-key',
  webhook: {
    url: 'https://your-app.com/webhook',
    secret: 'webhook-secret',
    events: ['edit.completed', 'edit.failed']
  }
});

非同期処理

// 非同期処理の開始
const job = await editor.editTextAsync({
  image: './large-image.jpg',
  prompt: 'テキストを編集してください',
  webhook: {
    url: 'https://your-app.com/webhook/edit-complete'
  }
});

console.log('ジョブID:', job.jobId);

// ジョブステータスの確認
const status = await editor.getJobStatus(job.jobId);
console.log('ステータス:', status.status); // 'pending', 'processing', 'completed', 'failed'

Webhookペイロード

interface WebhookPayload {
  event: string;
  jobId: string;
  timestamp: string;
  data: {
    imageUrl?: string;
    credits?: number;
    error?: {
      code: string;
      message: string;
    };
  };
}

📚 SDK

JavaScript/TypeScript

npm install qwen-image-edit
import { QwenImageEdit } from 'qwen-image-edit';

const editor = new QwenImageEdit({
  apiKey: process.env.QWEN_API_KEY
});

Python

pip install qwen-image-edit
from qwen_image_edit import QwenImageEdit

editor = QwenImageEdit(
    api_key=os.getenv('QWEN_API_KEY')
)

PHP

composer require qwen/image-edit
<?php
use Qwen\ImageEdit\QwenImageEdit;

$editor = new QwenImageEdit([
    'apiKey' => $_ENV['QWEN_API_KEY']
]);
?>

Java

<dependency>
    <groupId>com.qwen</groupId>
    <artifactId>image-edit</artifactId>
    <version>1.0.0</version>
</dependency>
import com.qwen.imageedit.QwenImageEdit;

QwenImageEdit editor = new QwenImageEdit.Builder()
    .apiKey(System.getenv("QWEN_API_KEY"))
    .build();

Go

go get github.com/qwen/image-edit-go
import "github.com/qwen/image-edit-go"

editor := imageedit.NewClient(os.Getenv("QWEN_API_KEY"))

Ruby

gem install qwen-image-edit
require 'qwen/image_edit'

editor = Qwen::ImageEdit.new(
  api_key: ENV['QWEN_API_KEY']
)

🎯 次のステップ

💡 実践例

実用的な使用例とベストプラクティス

例を見る →

⚙️ 設定

パフォーマンス最適化と高度な設定

設定ガイド →

🚀 高度な機能

非同期処理とバッチ操作

高度な機能 →

🛠️ トラブルシューティング

よくある問題と解決方法

トラブルシューティング →

質問がありますか? サポートチームにお気軽にお問い合わせください。