Realm API 文档

Appearance

编辑图片 (Edit Image) ​

使用通义千问模型编辑图片，支持单图编辑和多图融合。

计费说明 ​

按成功生成的图像张数计费（单次请求如果返回n张图片，则当次费用为 n×单价）

请求 ​

POST https://www.realmrouter.cn/v1/images/edits

请求头 ​

参数类型必填说明
Authorizationstring是Bearer Token 认证。格式: Authorization: Bearer sk-xxxxxx
Content-Typestring是请求内容类型，固定为 application/json

请求体 (application/json) ​

参数类型必填说明
modelstring是模型名称，可选值: qwen-image-edit-plus | qwen-image-edit-plus-2025-12-15 | qwen-image-edit-plus-2025-10-30 | qwen-image-edit
inputobject是输入参数对象
input.messagesarray是消息数组
input.messages[].rolestring是消息角色，固定为 "user"
input.messages[].contentarray是内容数组
input.messages[].content[].imagestring否图片URL地址或Base64编码数据，支持传入1-3张图像
input.messages[].content[].textstring否图像编辑指令，即正向提示词，长度上限800个字符
parametersobject否生成参数对象
parameters.ninteger否输出图像数量，默认值: 1。qwen-image-edit-plus系列支持1-6张，qwen-image-edit仅支持1张
parameters.negative_promptstring否反向提示词，长度上限500个字符
parameters.sizestring否输出图像分辨率，格式为宽*高，例如 "1024*2048"，取值范围[512, 2048]
parameters.prompt_extendboolean否是否开启prompt智能改写，默认值: true
parameters.seedinteger否随机数种子，取值范围[0, 2147483647]

参数说明 ​

model ​

模型名称，可选以下模型：

  • qwen-image-edit-plus系列模型：包括 qwen-image-edit-plus、qwen-image-edit-plus-2025-12-15、qwen-image-edit-plus-2025-10-30，支持输出1-6张图片
  • qwen-image-edit：仅支持输出1张图片

image ​

输入图像的 URL 或 Base64 编码数据。支持传入1-3张图像。

多图输入时，按照数组顺序定义图像顺序，输出图像的比例以最后一张为准。

图像要求：

  • 图像格式：JPG、JPEG、PNG、BMP、TIFF、WEBP和GIF
  • 输出图像为PNG格式，对于GIF动图，仅处理其第一帧
  • 图像分辨率：为获得最佳效果，建议图像的宽和高均在384像素至3072像素之间。分辨率过低可能导致生成效果模糊，过高则会增加处理时长
  • 图像大小：不超过10MB

text ​

图像编辑指令，即正向提示词，用来描述生成图像中期望包含的元素和视觉特点。

进行多图像编辑时，编辑指令中需要使用"图1"、"图2"、"图3"等描述来指代相应的图片，否则会出现不符合预期的编辑结果。

支持中英文，长度上限800个字符，每个汉字/字母占一个字符，超过部分会自动截断。

示例值： 图1中的女生穿着图2中的黑色裙子按图3的姿势坐下，保持其服装、发型和表情不变，动作自然流畅。

n ​

输出图像的数量，默认值为1。

  • 对于qwen-image-edit-plus系列模型，可选择输出1-6张图片
  • 对于qwen-image-edit，仅支持输出1张图片

negative_prompt ​

反向提示词，用来描述不希望在画面中看到的内容，可以对画面进行限制。

支持中英文，长度上限500个字符，每个汉字/字母占一个字符，超过部分会自动截断。

示例值： 低分辨率、错误、最差质量、低质量、残缺、多余的手指、比例不良等。

size ​

设置输出图像的分辨率，格式为宽*高，例如 "1024*2048"。宽和高的取值范围均为[512, 2048]像素。

默认行为： 若不设置，输出图像将保持与输入图像（多图输入时为最后一张）相似的长宽比，接近1024*1024分辨率。

支持模型： 仅qwen-image-edit-plus系列模型支持。

prompt_extend ​

是否开启prompt智能改写。开启后，将使用大模型优化正向提示词，对描述性不足、较为简单的prompt提升效果较明显。

  • true：默认值，开启智能改写
  • false：不开启智能改写

支持模型： 仅qwen-image-edit-plus系列模型支持。

seed ​

随机数种子，取值范围[0, 2147483647]。

使用相同的seed参数值可使生成内容保持相对稳定。若不提供，算法将自动使用随机数种子。

注意： 模型生成过程具有概率性，即使使用相同的seed，也不能保证每次生成结果完全一致。

请求示例 ​

cURL - 单图编辑 ​

bash
curl -X POST "https://www.realmrouter.cn/v1/images/edits" \
  -H "Authorization: Bearer " \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-image-edit-plus",
    "input": {
      "messages": [
        {
          "role": "user",
          "content": [
            {
              "image": "http://example.com/image.jpg"
            },
            {
              "text": "保持小猫咪姿势不动，给她的背景换成圣诞节的背景，希望在户外且下雪的场景"
            }
          ]
        }
      ]
    },
    "parameters": {
      "n": 2,
      "negative_prompt": "",
      "prompt_extend": true,
      "watermark": false
    }
  }'

cURL - 多图融合 ​

bash
curl -X POST "https://www.realmrouter.cn/v1/images/edits" \
  -H "Authorization: Bearer " \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-image-edit-plus",
    "input": {
      "messages": [
        {
          "role": "user",
          "content": [
            {
              "image": "http://example.com/image1.jpg"
            },
            {
              "image": "http://example.com/image2.jpg"
            },
            {
              "text": "将两张图的小猫融合到一张图里一起在户外过圣诞节谢谢，原图的猫咪别做任何改动这非常重要不需要对原图的猫咪做任何改动"
            }
          ]
        }
      ]
    },
    "parameters": {
      "n": 6,
      "negative_prompt": "blurry, bad quality, text",
      "prompt_extend": true,
      "watermark": false
    }
  }'

JavaScript ​

javascript
const body = JSON.stringify({
  "model": "qwen-image-edit-plus",
  "input": {
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "image": "http://example.com/image.jpg"
          },
          {
            "text": "保持小猫咪姿势不动，给她的背景换成圣诞节的背景，希望在户外且下雪的场景"
          }
        ]
      }
    ]
  },
  "parameters": {
    "n": 2,
    "negative_prompt": "",
    "prompt_extend": true,
    "watermark": false
  }
})

fetch("https://www.realmrouter.cn/v1/images/edits", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer "
  },
  body
})

Go ​

go
package main

import (
  "fmt"
  "net/http"
  "io/ioutil"
  "strings"
)

func main() {
  url := "https://www.realmrouter.cn/v1/images/edits"
  body := strings.NewReader(`{
    "model": "qwen-image-edit-plus",
    "input": {
      "messages": [
        {
          "role": "user",
          "content": [
            {
              "image": "http://example.com/image.jpg"
            },
            {
              "text": "保持小猫咪姿势不动，给她的背景换成圣诞节的背景，希望在户外且下雪的场景"
            }
          ]
        }
      ]
    },
    "parameters": {
      "n": 2,
      "negative_prompt": "",
      "prompt_extend": true,
      "watermark": false
    }
  }`)
  req, _ := http.NewRequest("POST", url, body)
  req.Header.Add("Authorization", "Bearer ")
  req.Header.Add("Content-Type", "application/json")
  res, _ := http.DefaultClient.Do(req)
  defer res.Body.Close()
  body, _ := ioutil.ReadAll(res.Body)

  fmt.Println(res)
  fmt.Println(string(body))
}

Python ​

python
import requests

url = "https://www.realmrouter.cn/v1/images/edits"
body = """{
  "model": "qwen-image-edit-plus",
  "input": {
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "image": "http://example.com/image.jpg"
          },
          {
            "text": "保持小猫咪姿势不动，给她的背景换成圣诞节的背景，希望在户外且下雪的场景"
          }
        ]
      }
    ]
  },
  "parameters": {
    "n": 2,
    "negative_prompt": "",
    "prompt_extend": true,
    "watermark": false
  }
}"""
response = requests.request("POST", url, data = body, headers = {
  "Content-Type": "application/json",
  "Authorization": "Bearer "
})

print(response.text)

Java ​

java
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.http.HttpResponse.BodyHandlers;
import java.time.Duration;
import java.net.http.HttpRequest.BodyPublishers;

var body = BodyPublishers.ofString("""{
  "model": "qwen-image-edit-plus",
  "input": {
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "image": "http://example.com/image.jpg"
          },
          {
            "text": "保持小猫咪姿势不动，给她的背景换成圣诞节的背景，希望在户外且下雪的场景"
          }
        ]
      }
    ]
  },
  "parameters": {
    "n": 2,
    "negative_prompt": "",
    "prompt_extend": true,
    "watermark": false
  }
}""");
HttpClient client = HttpClient.newBuilder()
  .connectTimeout(Duration.ofSeconds(10))
  .build();

HttpRequest.Builder requestBuilder = HttpRequest.newBuilder()
  .uri(URI.create("https://www.realmrouter.cn/v1/images/edits"))
  .header("Authorization", "Bearer ")
  .header("Content-Type", "application/json")
  .POST(body)
  .build();

try {
  HttpResponse<String> response = client.send(requestBuilder.build(), BodyHandlers.ofString());
  System.out.println("Status code: " + response.statusCode());
  System.out.println("Response body: " + response.body());
} catch (Exception e) {
  e.printStackTrace();
}

C# ​

csharp
using System;
using System.Net.Http;
using System.Text;

var body = new StringContent("""
{
  "model": "qwen-image-edit-plus",
  "input": {
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "image": "http://example.com/image.jpg"
          },
          {
            "text": "保持小猫咪姿势不动，给她的背景换成圣诞节的背景，希望在户外且下雪的场景"
          }
        ]
      }
    ]
  },
  "parameters": {
    "n": 2,
    "negative_prompt": "",
    "prompt_extend": true,
    "watermark": false
  }
}
""", Encoding.UTF8, "application/json");

var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "Bearer ");
var response = await client.PostAsync("https://www.realmrouter.cn/v1/images/edits", body);
var responseBody = await response.Content.ReadAsStringAsync();

响应 ​

响应体 (application/json) ​

参数类型说明
createdinteger创建时间戳
dataarray编辑后的图片数据数组
data[].urlstring图片URL
data[].revised_promptstring修订后的提示词

响应示例 ​

json
{
  "created": 1234567890,
  "data": [
    {
      "url": "https://example.com/edited-image.png",
      "revised_prompt": "保持小猫咪姿势不动，给她的背景换成圣诞节的背景，希望在户外且下雪的场景"
    }
  ]
}

状态码 ​

状态码说明
200成功
400请求参数错误
401认证失败
429请求过于频繁
500服务器错误

常见问题 ​

Q：qwen-image-edit 支持多轮对话式编辑吗？

A：不支持。模型仅支持单轮执行。每次调用均为独立、无状态的任务。如需连续编辑，须将生成的图片作为新输入再次调用。

Q：qwen-image-edit 和 qwen-image-edit-plus 系列模型支持哪些语言？

A：目前正式支持简体中文和英文；其他语言可自行尝试，但效果未经充分验证，可能存在不确定性。

Q：上传多张不同比例的参考图时，输出图像的比例以哪张为准？

A：输出图像会以最后一张上传的参考图的比例为准。

注意事项 ​

  1. model 参数支持多个模型：
    • qwen-image-edit-plus、qwen-image-edit-plus-2025-12-15、qwen-image-edit-plus-2025-10-30：支持输出1-6张图片
    • qwen-image-edit：仅支持输出1张图片
  2. input.messages[].content 数组支持两种格式：
    • 单图编辑: 包含一个 image 字段和一个 text 字段
    • 多图融合: 包含多个 image 字段和一个 text 字段
  3. image 字段支持图片URL或Base64编码数据，支持传入1-3张图像
  4. 多图输入时，按照数组顺序定义图像顺序，输出图像的比例以最后一张为准
  5. text 字段用于指定编辑指令或融合要求，长度上限800个字符
  6. 进行多图像编辑时，编辑指令中需要使用"图1"、"图2"、"图3"等描述来指代相应的图片
  7. parameters.n 参数控制生成图片的数量：
    • qwen-image-edit-plus系列支持1-6张
    • qwen-image-edit仅支持1张
  8. parameters.negative_prompt 参数用于指定不希望出现的内容，长度上限500个字符
  9. parameters.size 参数控制输出图像分辨率，格式为宽*高，取值范围[512, 2048]
  10. parameters.prompt_extend 参数控制是否自动扩展提示词：
    • true: 自动扩展提示词以获得更好的效果
    • false: 使用原始提示词
  11. parameters.seed 参数用于控制生成结果的稳定性，取值范围[0, 2147483647]
  12. 每次请求的token消耗会计入您的配额
  13. 生成的图片URL有时效性，请及时保存
  14. 图片编辑可能需要较长时间，请耐心等待响应
  15. 支持的图片格式包括 JPG、JPEG、PNG、BMP、TIFF、WEBP和GIF
  16. 输出图像为PNG格式，对于GIF动图，仅处理其第一帧
  17. 原始图片大小建议不超过10MB
  18. 建议图像的宽和高均在384像素至3072像素之间
  19. 多图融合时，建议图片主题相关，融合效果会更好
  20. 在提示词中明确说明需要保留或修改的内容，可以获得更精确的编辑效果

基于 MIT 许可发布 厦门界云聚算网络科技有限公司

Copyright © 2025 Realm API