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'
}
});
パラメータ
パラメータ | 型 | 必須 | 説明 |
---|---|---|---|
image | string | Buffer | File | ✅ | 編集する画像(ファイルパス、Buffer、またはFileオブジェクト) |
prompt | string | ✅ | 編集指示(自然言語) |
options.quality | string | ❌ | 出力品質(デフォルト: 'high') |
options.maxWidth | number | ❌ | 最大幅(ピクセル) |
options.maxHeight | number | ❌ | 最大高さ(ピクセル) |
options.format | string | ❌ | 出力フォーマット(デフォルト: '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'
}
});
パラメータ
パラメータ | 型 | 必須 | 説明 |
---|---|---|---|
image | string | Buffer | File | ✅ | 編集する画像 |
prompt | string | ✅ | 要素編集指示 |
options.quality | string | ❌ | 出力品質 |
options.preserveAspectRatio | boolean | ❌ | アスペクト比を保持(デフォルト: true) |
options.blendMode | string | ❌ | ブレンドモード |
使用例
// ロゴの追加
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
}
});
パラメータ
パラメータ | 型 | 必須 | 説明 |
---|---|---|---|
image | string | Buffer | File | ✅ | 元画像 |
styleImage | string | Buffer | File | ❌ | スタイル参照画像 |
style | string | ❌ | 事前定義スタイル名 |
intensity | number | ❌ | スタイル強度(0.0-1.0、デフォルト: 0.7) |
options.preserveContent | boolean | ❌ | コンテンツを保持(デフォルト: true) |
options.colorOnly | boolean | ❌ | 色のみ転送(デフォルト: 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
});
パラメータ
パラメータ | 型 | 必須 | 説明 |
---|---|---|---|
image | string | Buffer | File | ✅ | リサイズする画像 |
width | number | ❌ | 目標幅 |
height | number | ❌ | 目標高さ |
mode | string | ❌ | リサイズモード(デフォルト: 'fit') |
quality | number | ❌ | 品質(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_KEY | APIキーが無効 | 正しい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日あたりのリクエスト |
---|---|---|
無料 | 10 | 100 |
ベーシック | 60 | 1,000 |
プロ | 300 | 10,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']
)
🎯 次のステップ
質問がありますか? サポートチームにお気軽にお問い合わせください。