API 文档

Qwen Image Edit API 通过简单的 HTTP 端点提供强大的图像编辑功能。本指南涵盖所有可用端点、参数和使用示例。

身份验证

所有 API 请求都需要使用 API 密钥进行身份验证。在请求头中包含您的 API 密钥：

const headers = {
  'Authorization': `Bearer ${API_KEY}`,
  'Content-Type': 'application/json'
};

基础 URL

https://qwenimageedit.top/api

端点

文本编辑

在图像中编辑或添加文本，同时保持原有样式和上下文。

端点： POST /api/image/text-edit

参数：

参数	类型	必需	描述
`image`	File/URL	是	要编辑的源图像
`instruction`	string	是	文本编辑指令
`position`	object	否	文本位置坐标
`style`	object	否	文本样式偏好

请求示例：

const response = await fetch('/api/image/text-edit', {
  method: 'POST',
  headers,
  body: JSON.stringify({
    image: 'https://example.com/image.jpg',
    instruction: '将文本"Hello"改为"欢迎"',
    position: { x: 100, y: 50 },
    style: {
      fontSize: 24,
      color: '#000000',
      fontFamily: 'Arial'
    }
  })
});

const result = await response.json();

响应：

{
  "success": true,
  "editedImage": "https://example.com/edited-image.jpg",
  "processingTime": 2.5,
  "creditsUsed": 1
}

语义编辑

对图像进行高级语义更改，如风格转换或对象操作。

端点： POST /api/image/semantic-edit

参数：

参数	类型	必需	描述
`image`	File/URL	是	要编辑的源图像
`prompt`	string	是	语义编辑指令
`strength`	number	否	编辑强度 (0.1-1.0)
`preserveAreas`	array	否	编辑时要保留的区域

请求示例：

const response = await fetch('/api/image/semantic-edit', {
  method: 'POST',
  headers,
  body: JSON.stringify({
    image: 'https://example.com/portrait.jpg',
    prompt: '转换为印象派绘画风格',
    strength: 0.8,
    preserveAreas: [
      { x: 50, y: 50, width: 200, height: 200 }
    ]
  })
});

const result = await response.json();

批量处理

在单个请求中处理多个图像以提高效率。

端点： POST /api/image/batch-edit

参数：

参数	类型	必需	描述
`images`	array	是	图像 URL 或文件数组
`operations`	array	是	编辑操作数组
`parallel`	boolean	否	并行处理图像

请求示例：

const response = await fetch('/api/image/batch-edit', {
  method: 'POST',
  headers,
  body: JSON.stringify({
    images: [
      'https://example.com/image1.jpg',
      'https://example.com/image2.jpg'
    ],
    operations: [
      {
        type: 'text-edit',
        instruction: '添加水印"© 2024"',
        position: { x: 10, y: 10 }
      }
    ],
    parallel: true
  })
});

错误处理

API 返回标准 HTTP 状态码和详细错误消息：

{
  "success": false,
  "error": {
    "code": "INVALID_IMAGE",
    "message": "提供的图像格式不受支持",
    "details": "支持的格式：JPEG、PNG、WebP"
  }
}

常见错误代码：

INVALID_API_KEY: 无效或缺失的 API 密钥
INSUFFICIENT_CREDITS: 操作积分不足
INVALID_IMAGE: 不支持的图像格式或损坏的文件
PROCESSING_FAILED: 图像处理失败
RATE_LIMIT_EXCEEDED: 请求过于频繁

速率限制

免费版: 每分钟 10 次请求
专业版: 每分钟 100 次请求
企业版: 自定义限制

SDK 和库

JavaScript/TypeScript

npm install @qwen-image-edit/sdk

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

const client = new QwenImageEdit({
  apiKey: 'your-api-key',
  baseUrl: 'https://qwenimageedit.top/api'
});

const result = await client.textEdit({
  image: 'path/to/image.jpg',
  instruction: '将文本颜色改为红色'
});

Python

pip install qwen-image-edit

from qwen_image_edit import QwenImageEdit

client = QwenImageEdit(api_key='your-api-key')

result = client.text_edit(
    image='path/to/image.jpg',
    instruction='将文本颜色改为红色'
)

Webhooks

对于长时间运行的操作，您可以使用 webhooks 在处理完成时接收通知：

const response = await fetch('/api/image/text-edit', {
  method: 'POST',
  headers,
  body: JSON.stringify({
    image: 'https://example.com/large-image.jpg',
    instruction: '复杂编辑任务',
    webhook: {
      url: 'https://your-app.com/webhook',
      secret: 'webhook-secret'
    }
  })
});

最佳实践

图像质量: 使用高分辨率图像（最小 512x512）以获得更好的结果
清晰指令: 提供具体、清晰的编辑指令
错误处理: 始终实施适当的错误处理
速率限制: 遵守速率限制并实施指数退避
缓存: 尽可能缓存结果以减少 API 调用

支持

技术支持和问题咨询：

API 参考 (简体中文)

本文档为 QwenImageEdit SDK 提供全面的参考，详细介绍了主要对象、方法和可供开发者使用的配置选项。

QwenImageEdit 对象

QwenImageEdit 对象是与 API 交互的主要入口点。它需要使用您的 API 密钥和其他配置选项进行初始化。

初始化

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

const qwenImageEdit = new QwenImageEdit({
  apiKey: 'YOUR_API_KEY', // 必需：您的 API 密钥
  region: 'us-east-1',    // 可选：API 区域（例如，'us-west-2', 'eu-central-1'）
  timeout: 30000,          // 可选：请求超时时间（毫秒，默认值：10000）
  retries: 3,              // 可选：失败请求的重试次数（默认值：0）
  caching: {
    enabled: true,         // 可选：启用缓存（默认值：false）
    strategy: 'memory',    // 可选：缓存策略（'memory', 'redis', 'filesystem'）
    ttl: 3600,             // 可选：缓存生存时间（秒，默认值：3600）
  },
  proxy: 'http://your.proxy.com:8080', // 可选：所有 API 请求的代理 URL
  logLevel: 'info',        // 可选：日志级别（'debug', 'info', 'warn', 'error'）
});

初始化选项

apiKey (string, 必需): 用于向 QwenImageEdit 服务进行身份验证的唯一 API 密钥。
region (string, 可选): 要连接的数据中心区域。选择离用户最近的区域可以减少延迟。
timeout (number, 可选): 等待 API 响应的最大时间（毫秒）。如果达到超时，请求将被取消。
retries (number, 可选): SDK 将重试失败请求（例如，网络错误、速率限制）的次数。
caching (object, 可选): 缓存策略的配置对象。
- enabled (boolean): 确定是否启用缓存。
- strategy (string): 要使用的缓存策略。选项包括 memory (在应用程序内存中缓存)、redis (需要单独的 Redis 服务器) 或 filesystem (将缓存保存到磁盘)。
- ttl (number): 缓存的生存时间（秒）。在此期间之后，缓存条目将被视为过期。
proxy (string, 可选): 用于所有出站请求的 HTTP/HTTPS 代理 URL。在企业或受限环境中很有用。
logLevel (string, 可选): 设置 SDK 日志的详细程度。可用级别包括 debug、info、warn 和 error。

图像模块

image 模块包含所有与图像操作和分析相关的方法。

`image.removeBackground(options)`

从图像中移除背景，使其透明或替换为纯色。

options.image (string, 必需): 源图像 URL。
options.outputFormat (string, 可选): 输出图像格式 (png, webp)。png 或 webp 推荐用于透明度。
options.backgroundColor (string, 可选): 要替换的背景颜色（例如，#FFFFFF 表示白色）。

const result = await qwenImageEdit.image.removeBackground({
  image: 'https://example.com/image.jpg',
  outputFormat: 'png',
});

`image.resize(options)`

调整图像大小到指定尺寸。

options.image (string, 必需): 源图像 URL。
options.width (number, 必需): 输出图像的宽度（像素）。
options.height (number, 必需): 输出图像的高度（像素）。
options.fit (string, 可选): 图像应如何适应指定尺寸（cover, contain, fill, inside, outside）。

const result = await qwenImageEdit.image.resize({
  image: 'https://example.com/image.jpg',
  width: 800,
  height: 600,
});

`image.applyFilter(options)`

对图像应用视觉滤镜。

options.image (string, 必需): 源图像 URL。
options.filter (string, 必需): 要应用的滤镜名称（例如，grayscale, sepia, blur, sharpen, invert）。
options.value (number, 可选): 特定滤镜的强度值（例如，blur 的半径）。

const result = await qwenImageEdit.image.applyFilter({
  image: 'https://example.com/image.jpg',
  filter: 'grayscale',
});

`image.addText(options)`

在图像的指定位置添加文本并设置样式选项。

options.image (string, 必需): 源图像 URL。
options.text (string, 必需): 要添加的文本。
options.x (number, 必需): 文本起始点的 X 坐标。
options.y (number, 必需): 文本起始点的 Y 坐标。
options.font (string, 可选): 字体名称（例如，Arial, serif）。
options.fontSize (number, 可选): 字体大小（像素）。
options.color (string, 可选): 文本颜色（例如，#FF0000 或 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)`

在基础图像上叠加另一张图像。

options.baseImage (string, 必需): 基础图像 URL。
options.overlayImage (string, 必需): 要叠加的图像 URL。
options.x (number, 必需): 叠加图像的 X 坐标。
options.y (number, 必需): 叠加图像的 Y 坐标。
options.opacity (number, 可选): 叠加图像的不透明度（0.0 到 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)`

裁剪图像的特定区域。

options.image (string, 必需): 源图像 URL。
options.x (number, 必需): 裁剪区域的起始 X 坐标。
options.y (number, 必需): 裁剪区域的起始 Y 坐标。
options.width (number, 必需): 裁剪区域的宽度。
options.height (number, 必需): 裁剪区域的高度。

const result = await qwenImageEdit.image.crop({
  image: 'https://example.com/image.jpg',
  x: 100,
  y: 100,
  width: 200,
  height: 150,
});

`image.rotate(options)`

按指定角度旋转图像。

options.image (string, 必需): 源图像 URL。
options.angle (number, 必需): 旋转角度（度，例如 90, 180, 270）。

const result = await qwenImageEdit.image.rotate({
  image: 'https://example.com/image.jpg',
  angle: 90,
});

`image.convertFormat(options)`

转换图像格式。

options.image (string, 必需): 源图像 URL。
options.targetFormat (string, 必需): 目标图像格式（jpeg, png, webp, gif, tiff）。
options.quality (number, 可选): 支持该格式的输出质量（0-100）。

const result = await qwenImageEdit.image.convertFormat({
  image: 'https://example.com/image.jpg',
  targetFormat: 'webp',
  quality: 80,
});

`image.batchProcess(options)`

在一个请求中对一个或多个图像执行多个操作。

options.operations (array, 必需): 操作对象数组，每个对象包含操作 type 和特定于操作的选项。

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)`

获取图像的元数据（例如，尺寸、格式、大小）。

options.image (string, 必需): 源图像 URL。

const metadata = await qwenImageEdit.image.getMetadata({
  image: 'https://example.com/image.jpg',
});

常见错误代码

以下是 API 可能返回的常见错误代码列表：

AUTHENTICATION_ERROR: API 密钥无效或缺失。
RATE_LIMIT_EXCEEDED: 已达到 API 调用速率限制。
INVALID_IMAGE_URL: 提供的图像 URL 无效或无法访问。
UNSUPPORTED_IMAGE_FORMAT: 上传的图像格式不受支持。
PROCESSING_FAILED: 图像处理过程中发生内部错误。
INVALID_ARGUMENT: 提供的一个或多个参数无效或缺失。

未来模块

我们正在不断改进和扩展 QwenImageEdit SDK。计划中的未来模块和功能包括：

text 模块: 专门用于高级文本检测、识别和操作的操作。
object 模块: 图像中的对象检测、移除和替换。
scene 模块: 图像场景分析和操作，例如复杂的背景更改或光照调整。

API 文档

On this page