POSThttps://api.wylon.cn/v1/contents/generations/tasks

GEThttps://api.wylon.cn/v1/contents/generations/tasks/{task_id}

异步生成

创建后台图片生成任务，保存任务 ID，并通过查询接口获取状态和最终图片。

鉴权与请求格式

Authorizationstring · header必填

Bearer 令牌。可前往控制台创建 API 密钥，并将其保存为环境变量 $WYLON_API_KEY。

Content-Typestring · header必填

创建任务时固定为 application/json。

创建任务

curl -sS --max-time 60 \
  -X POST "https://api.wylon.cn/v1/contents/generations/tasks" \
  -H "Authorization: Bearer ${WYLON_API_KEY}" \
  -H "Content-Type: application/json" \
  --data-binary '{
    "type": "image",
    "model": "Qwen/Qwen-Image-2512",
    "prompt": "一张未来城市夜景海报，电影感构图",
    "size": "1664x928",
    "n": 1
  }' -o async-create-response.json

import os
import requests

response = requests.post(
    "https://api.wylon.cn/v1/contents/generations/tasks",
    headers={"Authorization": f"Bearer {os.environ['WYLON_API_KEY']}"},
    json={
        "type": "image",
        "model": "Qwen/Qwen-Image-2512",
        "prompt": "一张未来城市夜景海报，电影感构图",
        "size": "1664x928",
        "n": 1,
    },
    timeout=60,
)
response.raise_for_status()
task = response.json()
print(task["id"])

const response = await fetch(
  "https://api.wylon.cn/v1/contents/generations/tasks",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.WYLON_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      type: "image",
      model: "Qwen/Qwen-Image-2512",
      prompt: "一张未来城市夜景海报，电影感构图",
      size: "1664x928",
      n: 1,
    }),
  },
);

if (!response.ok) throw new Error(`HTTP ${response.status}`);
const task = await response.json();
console.log(task.id);

创建参数

typestring必填

指定任务生成的内容类型。创建图片任务时必须传入 image；省略该字段时，接口默认按视频任务处理。

modelstring必填

wylon 提供的模型 ID，例如 Qwen/Qwen-Image-2512。可前往模型广场或通过列出模型确认可访问的模型。

promptstring必填

描述希望生成的主体、场景、构图、光线、风格和文字内容。

negative_promptstring可选

描述不希望出现在生成结果中的内容。是否支持、长度限制及实际效果由所选模型决定。

seedinteger可选

用于控制生成随机性的种子。是否支持、合法取值范围及结果可复现程度由所选模型决定。

sizestring可选

期望输出的图片尺寸，格式为 宽x高。省略时使用所选模型的默认值；支持的取值由模型决定。

ninteger1

请求生成的图片数量。支持范围由接口版本和模型能力共同决定。

output_formatstringpng

期望生成的图片文件格式。

output_compressioninteger可选

期望使用的输出压缩等级，对 png 图片默认不生效。

backgroundstring可选

期望使用的图片背景模式。Openai兼容字段，V1 默认不生效。

qualitystring可选

期望使用的图片质量档位。是Openai兼容字段，V1 默认不生效。

stylestring可选

期望使用的图片风格预设。是否支持及合法取值由所选模型决定。

userstring可选

调用方提供的终端用户关联标识。该字段不参与 API 鉴权。

user_idstring可选

兼容性用户标识。接口接受该字段，但当前不持久化或使用。

moderationstring可选

请求使用的内容审核模式。该字段不能关闭或绕过平台安全策略。

streambooleanfalse

是否流式返回生成过程中的部分图片。V1 不支持该能力，请省略或传入 false。

partial_imagesinteger0

指定流式生成时返回的部分图片数量。V1 不支持该能力，请省略或传入 0。

当前模型限制

以下取值仅适用于 Qwen/Qwen-Image-2512。

参数	支持值	默认值	说明
`size`	`1328x1328`、`1664x928`、`928x1664`、`1104x1472`、`1584x1056`	`1664x928`	支持方形、横向和纵向画幅
`n`	`1`	`1`	每个任务仅生成一张图片

V1 默认添加“AI 生成”水印，且不支持流式中间图。以上属于接口版本行为，不属于单个模型的能力参数。

查询任务

使用创建响应中的 id 查询任务。设置 detail=true 时，成功响应包含实际生效的 image_parameters。

查询任务

TASK_ID=$(jq -r '.id' async-create-response.json)

curl -sS --get \
  "https://api.wylon.cn/v1/contents/generations/tasks/${TASK_ID}" \
  -H "Authorization: Bearer ${WYLON_API_KEY}" \
  --data-urlencode "detail=true" \
  -o async-task-response.json

import os
import requests

task_id = os.environ["TASK_ID"]
response = requests.get(
    f"https://api.wylon.cn/v1/contents/generations/tasks/{task_id}",
    headers={"Authorization": f"Bearer {os.environ['WYLON_API_KEY']}"},
    params={"detail": "true"},
    timeout=30,
)
response.raise_for_status()
task = response.json()
print(task["status"])

const taskId = process.env.TASK_ID;
const url = new URL(
  `https://api.wylon.cn/v1/contents/generations/tasks/${taskId}`,
);
url.searchParams.set("detail", "true");

const response = await fetch(url, {
  headers: { Authorization: `Bearer ${process.env.WYLON_API_KEY}` },
});
if (!response.ok) throw new Error(`HTTP ${response.status}`);
const task = await response.json();
console.log(task.status);

状态	含义	建议操作
`queued`	任务已受理，等待执行	稍后继续查询
`running`	图片正在生成	稍后继续查询
`succeeded`	任务成功	读取并下载图片
`failed`	任务执行失败	读取 `error`
`cancelled`	排队任务已取消	停止轮询
`expired`	任务或结果已过期	需要时重新创建任务

读取并下载结果

status=succeeded 时，图片地址位于 data[0].url，过期时间位于 data[0].url_expires_at。

成功结果

{
  "id": "8a7f2c10-5d4e-4b31-9a76-c2e8f1430d65",
  "status": "succeeded",
  "type": "image",
  "file_status": "available",
  "data": [{
    "url": "https://example.com/generated/image.png?signature=REDACTED",
    "url_expires_at": 1788842262
  }],
  "model": "Qwen/Qwen-Image-2512",
  "output_format": "png",
  "watermark": true
}

下载结果

IMAGE_URL=$(jq -r '.data[0].url' async-task-response.json)
curl -L --fail --show-error "${IMAGE_URL}" -o generated-image.png

import json
import requests

with open("async-task-response.json", encoding="utf-8") as file:
    image_url = json.load(file)["data"][0]["url"]

response = requests.get(image_url, timeout=120)
response.raise_for_status()
with open("generated-image.png", "wb") as file:
    file.write(response.content)

import { readFile, writeFile } from "node:fs/promises";

const task = JSON.parse(
  await readFile("async-task-response.json", "utf8"),
);
const response = await fetch(task.data[0].url);
if (!response.ok) throw new Error(`HTTP ${response.status}`);
await writeFile(
  "generated-image.png",
  Buffer.from(await response.arrayBuffer()),
);

结果 URL 不是永久存储地址。结果过期后任务记录可能继续保留，但 file_status 会变为 expired，并且不会重新签发 URL。

错误处理与生产建议

使用逐步增加的轮询间隔，避免固定高频查询。
创建响应已经返回 id 时，只重试查询，不要重复创建任务。
失败任务从 error 读取错误信息，具体错误码以实际响应为准。
记录 HTTP 状态码、任务 ID 和状态，不记录 API 密钥或完整签名 URL。