LogoQwen Image Edit

Rujukan API (Bahasa Melayu)

Panduan lengkap menggunakan API Qwen Image Edit

Rujukan API (Bahasa Melayu)

Dokumen ini menyediakan rujukan komprehensif untuk QwenImageEdit SDK, memperincikan objek utama, kaedah, dan pilihan konfigurasi yang tersedia untuk pembangun.

Objek QwenImageEdit

Objek QwenImageEdit adalah titik masuk utama untuk berinteraksi dengan API. Ia perlu dimulakan dengan kunci API anda dan pilihan konfigurasi lain.

Inisialisasi

import { QwenImageEdit } from '@qwen-image-edit/sdk';

const qwenImageEdit = new QwenImageEdit({
  apiKey: 'YOUR_API_KEY', // Diperlukan: Kunci API anda
  region: 'us-east-1',    // Pilihan: Wilayah API (cth., 'us-west-2', 'eu-central-1')
  timeout: 30000,          // Pilihan: Masa tamat permintaan dalam milisaat (lalai: 10000)
  retries: 3,              // Pilihan: Bilangan percubaan semula untuk permintaan yang gagal (lalai: 0)
  caching: {
    enabled: true,         // Pilihan: Dayakan caching (lalai: false)
    strategy: 'memory',    // Pilihan: Strategi caching ('memory', 'redis', 'filesystem')
    ttl: 3600,             // Pilihan: Masa untuk hidup cache dalam saat (lalai: 3600)
  },
  proxy: 'http://your.proxy.com:8080', // Pilihan: URL proksi untuk semua permintaan API
  logLevel: 'info',        // Pilihan: Tahap pengelogan ('debug', 'info', 'warn', 'error')
});

Pilihan Inisialisasi

  • apiKey (string, diperlukan): Kunci API unik anda untuk pengesahan dengan perkhidmatan QwenImageEdit.
  • region (string, pilihan): Wilayah pusat data yang akan disambungkan. Memilih wilayah yang paling dekat dengan pengguna anda boleh mengurangkan kependaman.
  • timeout (number, pilihan): Masa maksimum dalam milisaat untuk menunggu respons daripada API. Jika masa tamat dicapai, permintaan akan dibatalkan.
  • retries (number, pilihan): Bilangan kali SDK akan cuba semula permintaan yang gagal (cth., ralat rangkaian, had kadar).
  • caching (object, pilihan): Objek konfigurasi untuk strategi caching.
    • enabled (boolean): Menentukan sama ada caching didayakan.
    • strategy (string): Strategi caching yang akan digunakan. Pilihan termasuk memory (cache dalam memori aplikasi), redis (memerlukan pelayan Redis yang berasingan), atau filesystem (menyimpan cache ke cakera).
    • ttl (number): Masa untuk hidup cache dalam saat. Selepas tempoh ini, entri cache akan dianggap lapuk.
  • proxy (string, pilihan): URL proksi HTTP/HTTPS yang akan digunakan untuk semua permintaan keluar. Berguna dalam persekitaran korporat atau terhad.
  • logLevel (string, pilihan): Menetapkan tahap perincian pengelogan SDK. Tahap yang tersedia termasuk debug, info, warn, dan error.

Modul Imej

Modul image mengandungi semua kaedah yang berkaitan dengan manipulasi dan analisis imej.

image.removeBackground(options)

Menghilangkan latar belakang dari imej, menjadikannya telus atau menggantikannya dengan warna pepejal.

  • options.image (string, diperlukan): URL imej sumber.
  • options.outputFormat (string, pilihan): Format imej output (png, webp). png atau webp disyorkan untuk ketelusan.
  • options.backgroundColor (string, pilihan): Warna latar belakang untuk diganti (cth., #FFFFFF untuk putih).
const result = await qwenImageEdit.image.removeBackground({
  image: 'https://example.com/image.jpg',
  outputFormat: 'png',
});

image.resize(options)

Mengubah saiz imej kepada dimensi yang ditentukan.

  • options.image (string, diperlukan): URL imej sumber.
  • options.width (number, diperlukan): Lebar imej output dalam piksel.
  • options.height (number, diperlukan): Ketinggian imej output dalam piksel.
  • options.fit (string, pilihan): Cara imej harus dimuatkan ke dalam dimensi yang ditentukan (cover, contain, fill, inside, outside).
const result = await qwenImageEdit.image.resize({
  image: 'https://example.com/image.jpg',
  width: 800,
  height: 600,
});

image.applyFilter(options)

Mengaplikasikan penapis visual ke imej.

  • options.image (string, diperlukan): URL imej sumber.
  • options.filter (string, diperlukan): Nama penapis untuk diaplikasikan (cth., grayscale, sepia, blur, sharpen, invert).
  • options.value (number, pilihan): Nilai keamatan untuk penapis tertentu (cth., radius untuk blur).
const result = await qwenImageEdit.image.applyFilter({
  image: 'https://example.com/image.jpg',
  filter: 'grayscale',
});

image.addText(options)

Menambah teks ke imej pada kedudukan tertentu dengan pilihan gaya.

  • options.image (string, diperlukan): URL imej sumber.
  • options.text (string, diperlukan): Teks untuk ditambah.
  • options.x (number, diperlukan): Koordinat X untuk permulaan teks.
  • options.y (number, diperlukan): Koordinat Y untuk permulaan teks.
  • options.font (string, pilihan): Nama fon (cth., Arial, serif).
  • options.fontSize (number, pilihan): Saiz fon dalam piksel.
  • options.color (string, pilihan): Warna teks (cth., #FF0000 atau red).
const result = await qwenImageEdit.image.addText({
  image: 'https://example.com/image.jpg',
  text: 'Hello World',
  x: 50,
  y: 50,
  fontSize: 32,
  color: '#0000FF',
});

image.overlayImage(options)

Melapiskan imej lain di atas imej dasar.

  • options.baseImage (string, diperlukan): URL imej dasar.
  • options.overlayImage (string, diperlukan): URL imej yang akan dilapiskan.
  • options.x (number, diperlukan): Koordinat X untuk kedudukan imej overlay.
  • options.y (number, diperlukan): Koordinat Y untuk kedudukan imej overlay.
  • options.opacity (number, pilihan): Kelegapan imej overlay (0.0 hingga 1.0).
const result = await qwenImageEdit.image.overlayImage({
  baseImage: 'https://example.com/background.jpg',
  overlayImage: 'https://example.com/logo.png',
  x: 10,
  y: 10,
  opacity: 0.7,
});

image.crop(options)

Memotong bahagian tertentu dari imej.

  • options.image (string, diperlukan): URL imej sumber.
  • options.x (number, diperlukan): Koordinat X permulaan pemotongan.
  • options.y (number, diperlukan): Koordinat Y permulaan pemotongan.
  • options.width (number, diperlukan): Lebar kawasan pemotongan.
  • options.height (number, diperlukan): Ketinggian kawasan pemotongan.
const result = await qwenImageEdit.image.crop({
  image: 'https://example.com/image.jpg',
  x: 100,
  y: 100,
  width: 200,
  height: 150,
});

image.rotate(options)

Memutar imej mengikut sudut tertentu.

  • options.image (string, diperlukan): URL imej sumber.
  • options.angle (number, diperlukan): Sudut putaran dalam darjah (cth., 90, 180, 270).
const result = await qwenImageEdit.image.rotate({
  image: 'https://example.com/image.jpg',
  angle: 90,
});

image.convertFormat(options)

Menukar format imej.

  • options.image (string, diperlukan): URL imej sumber.
  • options.targetFormat (string, diperlukan): Format imej output (jpeg, png, webp, gif, tiff).
  • options.quality (number, pilihan): Kualiti output untuk format yang menyokongnya (0-100).
const result = await qwenImageEdit.image.convertFormat({
  image: 'https://example.com/image.jpg',
  targetFormat: 'webp',
  quality: 80,
});

image.batchProcess(options)

Melakukan berbilang operasi pada satu atau lebih imej dalam satu permintaan.

  • options.operations (array, diperlukan): Tatasusunan objek operasi, setiap satu mengandungi type operasi dan pilihan khusus operasi.
const results = await qwenImageEdit.image.batchProcess({
  operations: [
    {
      type: 'removeBackground',
      image: 'https://example.com/image1.jpg',
      outputFormat: 'png',
    },
    {
      type: 'resize',
      image: 'https://example.com/image2.jpg',
      width: 400,
      height: 300,
    },
  ],
});

image.getMetadata(options)

Mendapatkan metadata (cth., dimensi, format, saiz) dari imej.

  • options.image (string, diperlukan): URL imej sumber.
const metadata = await qwenImageEdit.image.getMetadata({
  image: 'https://example.com/image.jpg',
});

Kod Ralat Biasa

Berikut adalah senarai kod ralat biasa yang mungkin dikembalikan oleh API:

  • AUTHENTICATION_ERROR: Kunci API tidak sah atau hilang.
  • RATE_LIMIT_EXCEEDED: Had kadar panggilan API telah dicapai.
  • INVALID_IMAGE_URL: URL imej yang diberikan tidak sah atau tidak dapat diakses.
  • UNSUPPORTED_IMAGE_FORMAT: Format imej yang dimuat naik tidak disokong.
  • PROCESSING_FAILED: Ralat dalaman berlaku semasa memproses imej.
  • INVALID_ARGUMENT: Satu atau lebih parameter yang diberikan tidak sah atau hilang.

Modul Masa Depan

Kami sentiasa menambah baik dan mengembangkan QwenImageEdit SDK. Modul dan ciri masa depan yang dirancang termasuk:

  • Modul text: Operasi khusus untuk pengesanan, pengecaman, dan manipulasi teks lanjutan.
  • Modul object: Pengesanan, penyingkiran, dan penggantian objek dalam imej.
  • Modul scene: Analisis dan manipulasi adegan imej, seperti perubahan latar belakang yang kompleks atau penyesuaian pencahayaan.

Contoh Penggunaan (Bahasa Melayu)

Contoh praktikal dan potongan kod untuk pelbagai kes penggunaan

Konfigurasi

Panduan konfigurasi dan persediaan untuk Qwen Image Edit