Référence API
Guide complet pour utiliser l'API Qwen Image Edit
Référence API
Documentation complète de l'API Qwen Image Edit avec tous les paramètres, méthodes et exemples d'utilisation.
🔐 Authentification
Configuration de Base
import { QwenImageEdit } from 'qwen-image-edit';
// Initialisation avec clé API
const editor = new QwenImageEdit({
apiKey: process.env.QWEN_API_KEY,
region: 'eu-west-1', // Optionnel
timeout: 30000 // 30 secondes
});
Variables d'Environnement
# Fichier .env
QWEN_API_KEY=votre_cle_api_ici
QWEN_REGION=eu-west-1
QWEN_TIMEOUT=30000
Régions Disponibles
Région | Code | Localisation |
---|---|---|
Europe Ouest | eu-west-1 | Irlande |
Asie Pacifique | ap-southeast-1 | Singapour |
Amérique du Nord | us-east-1 | Virginie |
Asie Est | ap-northeast-1 | Tokyo |
📝 Méthodes Principales
editText()
Modifie le texte dans une image en conservant le style et la mise en page.
const resultat = await editor.editText({
image: string | Buffer | File,
prompt: string,
options?: {
preserveStyle?: boolean,
language?: string,
fontSize?: 'small' | 'medium' | 'large',
fontWeight?: 'normal' | 'bold',
color?: string,
backgroundColor?: string,
position?: 'auto' | 'top' | 'center' | 'bottom',
exactMatch?: boolean,
sourceLanguage?: string,
targetLanguage?: string,
preserveLayout?: boolean,
quality?: 'low' | 'medium' | 'high',
outputFormat?: 'jpg' | 'png' | 'webp',
outputPath?: string
}
});
Paramètres
Paramètre | Type | Description | Défaut |
---|---|---|---|
image | string | Buffer | File | Chemin vers l'image, buffer ou objet File | Requis |
prompt | string | Description de la modification à effectuer | Requis |
preserveStyle | boolean | Conserver le style original du texte | true |
language | string | Langue du texte (ISO 639-1) | 'auto' |
fontSize | string | Taille de police relative | 'medium' |
fontWeight | string | Poids de la police | 'normal' |
color | string | Couleur du texte (hex, rgb, nom) | 'auto' |
backgroundColor | string | Couleur de fond du texte | 'transparent' |
position | string | Position du texte dans l'image | 'auto' |
exactMatch | boolean | Correspondance exacte du texte | false |
sourceLanguage | string | Langue source pour traduction | 'auto' |
targetLanguage | string | Langue cible pour traduction | null |
preserveLayout | boolean | Conserver la mise en page | true |
quality | string | Qualité de l'image de sortie | 'high' |
outputFormat | string | Format de l'image de sortie | 'jpg' |
outputPath | string | Chemin de sauvegarde local | null |
Réponse
interface EditTextResponse {
imageUrl: string; // URL de l'image modifiée
originalText?: string; // Texte original détecté
modifiedText?: string; // Nouveau texte appliqué
confidence: number; // Score de confiance (0-1)
credits: number; // Crédits consommés
processingTime: number; // Temps de traitement (ms)
metadata: {
width: number;
height: number;
format: string;
size: number; // Taille en octets
};
}
Exemples
// Modification simple
const resultat = await editor.editText({
image: './affiche.jpg',
prompt: 'Remplacer "2023" par "2024"'
});
// Traduction avec style préservé
const traduction = await editor.editText({
image: './menu-en.jpg',
prompt: 'Traduire tout le texte en français',
options: {
sourceLanguage: 'en',
targetLanguage: 'fr',
preserveStyle: true
}
});
// Modification avec style personnalisé
const stylise = await editor.editText({
image: './titre.jpg',
prompt: 'Changer le titre en "Nouveau Produit"',
options: {
fontSize: 'large',
fontWeight: 'bold',
color: '#FF0000',
backgroundColor: '#FFFFFF'
}
});
editElement()
Ajoute, modifie ou supprime des éléments visuels dans une image.
const resultat = await editor.editElement({
image: string | Buffer | File,
prompt: string,
options?: {
elementType?: 'logo' | 'badge' | 'watermark' | 'shape' | 'icon',
position?: 'top-left' | 'top-center' | 'top-right' | 'center-left' | 'center' | 'center-right' | 'bottom-left' | 'bottom-center' | 'bottom-right',
size?: 'small' | 'medium' | 'large' | number,
opacity?: number,
color?: string,
backgroundColor?: string,
borderRadius?: number,
shadow?: boolean,
rotation?: number,
blendMode?: 'normal' | 'multiply' | 'overlay' | 'soft-light',
logoUrl?: string,
iconName?: string,
quality?: 'low' | 'medium' | 'high',
outputFormat?: 'jpg' | 'png' | 'webp',
outputPath?: string
}
});
Paramètres
Paramètre | Type | Description | Défaut |
---|---|---|---|
image | string | Buffer | File | Image source | Requis |
prompt | string | Description de l'élément à ajouter/modifier | Requis |
elementType | string | Type d'élément | 'auto' |
position | string | Position de l'élément | 'center' |
size | string | number | Taille de l'élément | 'medium' |
opacity | number | Opacité (0-1) | 1.0 |
color | string | Couleur principale | 'auto' |
backgroundColor | string | Couleur de fond | 'transparent' |
borderRadius | number | Rayon des coins (px) | 0 |
shadow | boolean | Ajouter une ombre | false |
rotation | number | Rotation en degrés | 0 |
blendMode | string | Mode de fusion | 'normal' |
logoUrl | string | URL du logo à insérer | null |
iconName | string | Nom de l'icône (bibliothèque intégrée) | null |
Exemples
// Ajouter un logo
const avecLogo = await editor.editElement({
image: './produit.jpg',
prompt: 'Ajouter le logo de l\'entreprise en bas à droite',
options: {
elementType: 'logo',
position: 'bottom-right',
size: 'small',
opacity: 0.8,
logoUrl: './logo.png'
}
});
// Ajouter un badge de promotion
const avecBadge = await editor.editElement({
image: './article.jpg',
prompt: 'Ajouter un badge "NOUVEAU" rouge',
options: {
elementType: 'badge',
position: 'top-left',
color: '#FF0000',
backgroundColor: '#FFFFFF',
borderRadius: 10,
shadow: true
}
});
// Ajouter un filigrane
const avecFiligrane = await editor.editElement({
image: './photo.jpg',
prompt: 'Ajouter "© 2024" en filigrane',
options: {
elementType: 'watermark',
position: 'center',
opacity: 0.3,
rotation: -45,
size: 'large'
}
});
transferStyle()
Applique un style artistique ou photographique à une image.
const resultat = await editor.transferStyle({
image: string | Buffer | File,
stylePrompt: string,
options?: {
intensity?: number,
preserveFaces?: boolean,
preserveText?: boolean,
colorPalette?: 'original' | 'warm' | 'cool' | 'monochrome' | 'vintage' | 'vibrant',
artisticStyle?: 'realistic' | 'artistic' | 'cartoon' | 'sketch' | 'watercolor' | 'oil-painting',
era?: '1920s' | '1950s' | '1970s' | '1980s' | '1990s' | '2000s',
mood?: 'bright' | 'dark' | 'dramatic' | 'soft' | 'energetic' | 'calm',
contrast?: 'low' | 'medium' | 'high',
saturation?: number,
brightness?: number,
quality?: 'low' | 'medium' | 'high',
outputFormat?: 'jpg' | 'png' | 'webp',
outputPath?: string
}
});
Paramètres
Paramètre | Type | Description | Défaut |
---|---|---|---|
image | string | Buffer | File | Image source | Requis |
stylePrompt | string | Description du style à appliquer | Requis |
intensity | number | Intensité de l'effet (0-1) | 0.8 |
preserveFaces | boolean | Préserver les visages | true |
preserveText | boolean | Préserver le texte | true |
colorPalette | string | Palette de couleurs | 'original' |
artisticStyle | string | Style artistique | 'realistic' |
era | string | Époque historique | null |
mood | string | Ambiance générale | null |
contrast | string | Niveau de contraste | 'medium' |
saturation | number | Saturation (0-2) | 1.0 |
brightness | number | Luminosité (0-2) | 1.0 |
Exemples
// Style vintage
const vintage = await editor.transferStyle({
image: './portrait.jpg',
stylePrompt: 'Appliquer un style vintage années 70',
options: {
era: '1970s',
colorPalette: 'warm',
intensity: 0.7,
preserveFaces: true
}
});
// Style aquarelle
const aquarelle = await editor.transferStyle({
image: './paysage.jpg',
stylePrompt: 'Transformer en peinture aquarelle',
options: {
artisticStyle: 'watercolor',
intensity: 0.9,
colorPalette: 'soft',
preserveText: false
}
});
// Style cinématographique
const cinema = await editor.transferStyle({
image: './scene.jpg',
stylePrompt: 'Look cinématographique avec tons bleus et oranges',
options: {
mood: 'dramatic',
contrast: 'high',
saturation: 0.8,
colorPalette: 'cinematic'
}
});
analyzeImage()
Analyse le contenu d'une image et extrait des informations détaillées.
const analyse = await editor.analyzeImage({
image: string | Buffer | File,
options?: {
detectText?: boolean,
detectObjects?: boolean,
detectFaces?: boolean,
detectColors?: boolean,
detectStyle?: boolean,
detectQuality?: boolean,
language?: string,
confidence?: number
}
});
Paramètres
Paramètre | Type | Description | Défaut |
---|---|---|---|
image | string | Buffer | File | Image à analyser | Requis |
detectText | boolean | Détecter le texte | true |
detectObjects | boolean | Détecter les objets | true |
detectFaces | boolean | Détecter les visages | true |
detectColors | boolean | Analyser les couleurs | true |
detectStyle | boolean | Analyser le style | false |
detectQuality | boolean | Évaluer la qualité | false |
language | string | Langue pour la détection de texte | 'auto' |
confidence | number | Seuil de confiance minimum (0-1) | 0.5 |
Réponse
interface AnalyzeImageResponse {
text?: {
content: string;
language: string;
confidence: number;
boundingBox: {
x: number;
y: number;
width: number;
height: number;
};
}[];
objects?: {
name: string;
confidence: number;
boundingBox: {
x: number;
y: number;
width: number;
height: number;
};
}[];
faces?: {
confidence: number;
age?: number;
gender?: string;
emotion?: string;
boundingBox: {
x: number;
y: number;
width: number;
height: number;
};
}[];
colors?: {
dominant: string[];
palette: {
color: string;
percentage: number;
}[];
averageColor: string;
};
style?: {
category: string;
confidence: number;
characteristics: string[];
};
quality?: {
score: number;
resolution: string;
sharpness: number;
noise: number;
exposure: string;
};
metadata: {
width: number;
height: number;
format: string;
size: number;
};
}
Exemple
const analyse = await editor.analyzeImage({
image: './photo-complexe.jpg',
options: {
detectText: true,
detectObjects: true,
detectFaces: true,
detectColors: true,
detectStyle: true,
detectQuality: true,
confidence: 0.7
}
});
console.log('Texte détecté :', analyse.text);
console.log('Objets trouvés :', analyse.objects);
console.log('Visages détectés :', analyse.faces);
console.log('Couleurs dominantes :', analyse.colors.dominant);
console.log('Style artistique :', analyse.style);
console.log('Score de qualité :', analyse.quality.score);
🛠️ Méthodes Utilitaires
resizeImage()
Redimensionne une image avec options avancées.
const redimensionnee = await editor.resizeImage({
image: string | Buffer | File,
width?: number,
height?: number,
options?: {
mode?: 'fit' | 'fill' | 'crop' | 'stretch',
position?: 'center' | 'top' | 'bottom' | 'left' | 'right',
background?: string,
quality?: 'low' | 'medium' | 'high',
outputFormat?: 'jpg' | 'png' | 'webp',
outputPath?: string
}
});
enhanceImage()
Améliore automatiquement la qualité d'une image.
const amelioree = await editor.enhanceImage({
image: string | Buffer | File,
options?: {
autoContrast?: boolean,
autoColor?: boolean,
autoSharpness?: boolean,
denoiseLevel?: 'low' | 'medium' | 'high',
upscaleFactor?: 1 | 2 | 4,
quality?: 'low' | 'medium' | 'high',
outputFormat?: 'jpg' | 'png' | 'webp',
outputPath?: string
}
});
cleanImage()
Supprime des éléments indésirables d'une image.
const nettoyee = await editor.cleanImage({
image: string | Buffer | File,
prompt: string,
options?: {
removeType?: 'object' | 'text' | 'watermark' | 'background',
precision?: 'low' | 'medium' | 'high',
fillMethod?: 'auto' | 'blur' | 'clone' | 'solid',
fillColor?: string,
quality?: 'low' | 'medium' | 'high',
outputFormat?: 'jpg' | 'png' | 'webp',
outputPath?: string
}
});
⚙️ Configuration Avancée
Options Globales
const editor = new QwenImageEdit({
apiKey: 'votre_cle',
region: 'eu-west-1',
timeout: 30000,
retries: 3,
retryDelay: 1000,
maxConcurrency: 5,
cache: {
enabled: true,
ttl: 3600,
maxSize: 100
},
proxy: {
host: 'proxy.example.com',
port: 8080,
auth: {
username: 'user',
password: 'pass'
}
},
logging: {
level: 'info',
destination: './logs/qwen.log'
}
});
Gestion des Événements
// Écouter les événements
editor.on('request', (data) => {
console.log('Requête envoyée :', data);
});
editor.on('response', (data) => {
console.log('Réponse reçue :', data);
});
editor.on('error', (error) => {
console.error('Erreur :', error);
});
editor.on('retry', (attempt, error) => {
console.log(`Tentative ${attempt} après erreur :`, error.message);
});
🚨 Gestion d'Erreurs
Types d'Erreurs
interface QwenError extends Error {
code: string;
statusCode?: number;
details?: any;
retryable?: boolean;
}
Codes d'Erreur Courants
Code | Description | Solution |
---|---|---|
INVALID_API_KEY | Clé API invalide | Vérifier la clé API |
QUOTA_EXCEEDED | Quota dépassé | Attendre ou upgrader |
RATE_LIMITED | Limite de taux atteinte | Réduire la fréquence |
IMAGE_TOO_LARGE | Image trop volumineuse | Réduire la taille |
UNSUPPORTED_FORMAT | Format non supporté | Utiliser JPG/PNG/WebP |
PROCESSING_FAILED | Échec du traitement | Vérifier l'image et le prompt |
NETWORK_ERROR | Erreur réseau | Vérifier la connexion |
TIMEOUT | Délai d'attente dépassé | Augmenter le timeout |
Gestion d'Erreurs
try {
const resultat = await editor.editText({
image: './image.jpg',
prompt: 'Modifier le texte'
});
console.log('Succès :', resultat.imageUrl);
} catch (error) {
switch (error.code) {
case 'INVALID_API_KEY':
console.error('Clé API invalide. Vérifiez votre configuration.');
break;
case 'QUOTA_EXCEEDED':
console.error('Quota dépassé. Attendez ou upgradez votre plan.');
break;
case 'RATE_LIMITED':
console.error('Limite de taux atteinte. Réessayez dans quelques secondes.');
// Retry automatique après délai
setTimeout(() => {
// Réessayer la requête
}, 5000);
break;
case 'IMAGE_TOO_LARGE':
console.error('Image trop volumineuse. Taille max : 10MB');
break;
case 'PROCESSING_FAILED':
console.error('Échec du traitement :', error.details);
break;
default:
console.error('Erreur inconnue :', error.message);
}
}
📊 Limites et Quotas
Limites par Plan
Plan | Requêtes/mois | Taille max | Concurrence | Support |
---|---|---|---|---|
Gratuit | 100 | 5MB | 1 | Communauté |
Pro | 10,000 | 10MB | 5 | |
Business | 100,000 | 25MB | 10 | Prioritaire |
Enterprise | Illimité | 50MB | 20 | Dédié |
Vérification du Quota
// Obtenir les informations de quota
const quota = await editor.getQuotaInfo();
console.log('Quota actuel :', quota);
// {
// plan: 'pro',
// requestsUsed: 1250,
// requestsLimit: 10000,
// requestsRemaining: 8750,
// resetDate: '2024-02-01T00:00:00Z',
// creditsUsed: 2500,
// creditsLimit: 20000
// }
🔗 Webhooks
Configuration
const editor = new QwenImageEdit({
apiKey: 'votre_cle',
webhooks: {
endpoint: 'https://votre-site.com/webhook',
secret: 'votre_secret_webhook',
events: ['processing.completed', 'processing.failed']
}
});
Traitement Asynchrone
// Démarrer un traitement asynchrone
const job = await editor.editTextAsync({
image: './grande-image.jpg',
prompt: 'Modifier le texte',
callbackUrl: 'https://votre-site.com/callback'
});
console.log('Job ID :', job.id);
// Vérifier le statut
const statut = await editor.getJobStatus(job.id);
console.log('Statut :', statut);
// {
// id: 'job_123',
// status: 'processing', // 'pending', 'processing', 'completed', 'failed'
// progress: 75,
// estimatedTime: 30, // secondes restantes
// result?: { imageUrl: '...', credits: 5 }
// }
📚 SDKs Disponibles
JavaScript/TypeScript
npm install qwen-image-edit
Python
pip install qwen-image-edit
from qwen_image_edit import QwenImageEdit
editor = QwenImageEdit(api_key="votre_cle")
result = editor.edit_text(
image="./image.jpg",
prompt="Modifier le texte"
)
PHP
composer require qwen/image-edit
use Qwen\ImageEdit\QwenImageEdit;
$editor = new QwenImageEdit(['api_key' => 'votre_cle']);
$result = $editor->editText([
'image' => './image.jpg',
'prompt' => 'Modifier le texte'
]);
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("votre_cle");
EditTextResponse result = editor.editText(
EditTextRequest.builder()
.image("./image.jpg")
.prompt("Modifier le texte")
.build()
);
Go
go get github.com/qwen/image-edit-go
import "github.com/qwen/image-edit-go"
editor := imageedit.New("votre_cle")
result, err := editor.EditText(context.Background(), &imageedit.EditTextRequest{
Image: "./image.jpg",
Prompt: "Modifier le texte",
})
Ruby
gem install qwen-image-edit
require 'qwen/image_edit'
editor = Qwen::ImageEdit.new(api_key: 'votre_cle')
result = editor.edit_text(
image: './image.jpg',
prompt: 'Modifier le texte'
)
Ressources Supplémentaires :