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égionCodeLocalisation
Europe Ouesteu-west-1Irlande
Asie Pacifiqueap-southeast-1Singapour
Amérique du Nordus-east-1Virginie
Asie Estap-northeast-1Tokyo

📝 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ètreTypeDescriptionDéfaut
imagestring | Buffer | FileChemin vers l'image, buffer ou objet FileRequis
promptstringDescription de la modification à effectuerRequis
preserveStylebooleanConserver le style original du textetrue
languagestringLangue du texte (ISO 639-1)'auto'
fontSizestringTaille de police relative'medium'
fontWeightstringPoids de la police'normal'
colorstringCouleur du texte (hex, rgb, nom)'auto'
backgroundColorstringCouleur de fond du texte'transparent'
positionstringPosition du texte dans l'image'auto'
exactMatchbooleanCorrespondance exacte du textefalse
sourceLanguagestringLangue source pour traduction'auto'
targetLanguagestringLangue cible pour traductionnull
preserveLayoutbooleanConserver la mise en pagetrue
qualitystringQualité de l'image de sortie'high'
outputFormatstringFormat de l'image de sortie'jpg'
outputPathstringChemin de sauvegarde localnull

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ètreTypeDescriptionDéfaut
imagestring | Buffer | FileImage sourceRequis
promptstringDescription de l'élément à ajouter/modifierRequis
elementTypestringType d'élément'auto'
positionstringPosition de l'élément'center'
sizestring | numberTaille de l'élément'medium'
opacitynumberOpacité (0-1)1.0
colorstringCouleur principale'auto'
backgroundColorstringCouleur de fond'transparent'
borderRadiusnumberRayon des coins (px)0
shadowbooleanAjouter une ombrefalse
rotationnumberRotation en degrés0
blendModestringMode de fusion'normal'
logoUrlstringURL du logo à insérernull
iconNamestringNom 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ètreTypeDescriptionDéfaut
imagestring | Buffer | FileImage sourceRequis
stylePromptstringDescription du style à appliquerRequis
intensitynumberIntensité de l'effet (0-1)0.8
preserveFacesbooleanPréserver les visagestrue
preserveTextbooleanPréserver le textetrue
colorPalettestringPalette de couleurs'original'
artisticStylestringStyle artistique'realistic'
erastringÉpoque historiquenull
moodstringAmbiance généralenull
contraststringNiveau de contraste'medium'
saturationnumberSaturation (0-2)1.0
brightnessnumberLuminosité (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ètreTypeDescriptionDéfaut
imagestring | Buffer | FileImage à analyserRequis
detectTextbooleanDétecter le textetrue
detectObjectsbooleanDétecter les objetstrue
detectFacesbooleanDétecter les visagestrue
detectColorsbooleanAnalyser les couleurstrue
detectStylebooleanAnalyser le stylefalse
detectQualitybooleanÉvaluer la qualitéfalse
languagestringLangue pour la détection de texte'auto'
confidencenumberSeuil 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

CodeDescriptionSolution
INVALID_API_KEYClé API invalideVérifier la clé API
QUOTA_EXCEEDEDQuota dépasséAttendre ou upgrader
RATE_LIMITEDLimite de taux atteinteRéduire la fréquence
IMAGE_TOO_LARGEImage trop volumineuseRéduire la taille
UNSUPPORTED_FORMATFormat non supportéUtiliser JPG/PNG/WebP
PROCESSING_FAILEDÉchec du traitementVérifier l'image et le prompt
NETWORK_ERRORErreur réseauVérifier la connexion
TIMEOUTDé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

PlanRequêtes/moisTaille maxConcurrenceSupport
Gratuit1005MB1Communauté
Pro10,00010MB5Email
Business100,00025MB10Prioritaire
EnterpriseIllimité50MB20Dé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 :