Skip to content

文生图(Text to Image) ​

根据文字描述生成图像。未指定 imageModel 时使用 妙图 1.0(miaotu_v1)。

在编辑器中试用:文生图。

基本信息 ​

项目值
接口路径POST /image/text2image
所需 Scopetext2image 或 *
任务类型异步,返回 taskId

请求参数 ​

json
{
  "requestId": "可选,调用方自定义唯一 ID",
  "positive": "正向提示词(必填)",
  "negative": "负向提示词(可选,部分模型使用)",
  "ar": "宽高比,默认 1:1",
  "seed": 42,
  "count": 1,
  "imageModel": "miaotu_v1",
  "outputResolution": "1k",
  "transparent": false,
  "promptEnhanced": "可选。传入时出图使用这段文案",
  "styleIds": [101, 202],
  "styleStrengths": [0.8, 0.6]
}

参数说明 ​

参数类型必填默认值说明
requestIdstring否服务端生成调用方请求 ID,用于去重和支持定位。省略时服务端生成,并在响应里返回
positivestring是—正向提示词,描述想要生成的内容。任务记录保存这段原文
negativestring否空字符串负向提示词。miaotu_v1、base_v2 出图不使用该字段
arstring否1:1图像宽高比,如 1:1、16:9、4:3、3:2、9:16、3:4、2:3。也可传其他 宽:高
seedinteger否随机随机种子(≥0)。未传时服务端生成
countinteger否1生成图像数量(1 ~ 4)。miaotu_v1 实际固定为 1,传入 2–4 时收成 1
imageModelstring否miaotu_v1见下方模型表。未知取值按 base_v1 出图
outputResolutionstring否随模型1k、1.5k、2k。miaotu_v1 默认 1k,三者都可用。其他模型默认 1.5k,传入 2k 时按 1.5k 出图
transparentboolean否false透明背景(RGBA)。仅 miaotu_v1 生效,其他模型忽略。开启后输出带 alpha 的图
promptEnhancedstring否—可选增强文案。有值时提交给出图引擎,任务仍把 positive 记为用户原文。空白且开启 transparent 时,后端可能做去背景改写。查询任务不会返回该字段
styleIdsinteger[]否空风格 ID 列表,与 styleStrengths 对应。须为该模型支持的风格,否则返回错误。miaotu_v1、base_v2 出图不应用风格 LoRA
styleStrengthsnumber[]否按 1.0 补齐各风格强度,与 styleIds 对应。短于 styleIds 时,缺的位置按 1.0 补齐

分辨率和张数不改变本次计费,仍为 1 个 API_CALL。查询任务不会返回 promptEnhanced。

模型 ​

imageModel名称出图张数分辨率备注
miaotu_v1(默认)妙图 1.0固定 11k / 1.5k / 2k,默认 1k支持 transparent
base_v1通用 1.01 ~ 41k / 1.5k,默认 1.5k未知模型回退到此
lancer_v1蓝瑟 1.01 ~ 41k / 1.5k,默认 1.5k
realistic_v1真实影像 1.01 ~ 41k / 1.5k,默认 1.5k
text_enhance_v1文字增强 1.01 ~ 41k / 1.5k,默认 1.5k
text_enhance_v2文字增强 2.01 ~ 41k / 1.5k,默认 1.5k
base_v2(已弃用)通用 2.01 ~ 41k / 1.5k,默认 1.5k仍可调用

旧模型传入 2k 时请求仍然成功,出图按 1.5k。


请求示例 ​

最简请求(默认妙图 1.0):

bash
curl -s -X POST \
  -H "Authorization: Bearer $TUSEN_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "positive": "a serene mountain lake at sunrise, photorealistic"
  }' \
  "https://magiqsight.com/openapi/v1/image/text2image"

妙图 1.0,2k,透明背景:

bash
curl -s -X POST \
  -H "Authorization: Bearer $TUSEN_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "positive": "a product sticker of a fluffy cat, isolated",
    "imageModel": "miaotu_v1",
    "outputResolution": "2k",
    "transparent": true
  }' \
  "https://magiqsight.com/openapi/v1/image/text2image"

指定通用模型与负向提示词:

bash
curl -s -X POST \
  -H "Authorization: Bearer $TUSEN_API_TOKEN" \
  -H "X-Request-Id: req-$(date +%s)" \
  -H "Content-Type: application/json" \
  -d '{
    "positive": "a serene mountain lake at sunrise, photorealistic, high detail",
    "negative": "blurry, low quality, overexposed",
    "ar": "16:9",
    "seed": 12345,
    "count": 2,
    "imageModel": "base_v1",
    "outputResolution": "1.5k"
  }' \
  "https://magiqsight.com/openapi/v1/image/text2image"

响应示例 ​

提交成功:

json
{
  "code": 0,
  "msg": "",
  "data": {
    "requestId": "req-1717200000",
    "taskId": "img-abc123def456"
  }
}

错误 — 积分不足:

json
{
  "code": 1004008000,
  "msg": "用户积分余额不足",
  "data": null
}

获取结果 ​

提交后使用 taskId 轮询 GET /tasks/{taskId}。

任务成功(status: 1)后,imageUrls 字段包含生成图像的完整分辨率 URL。
imagePreviewUrls 包含压缩预览图,通常先于完整图就绪。

若 count > 1,多张图像按顺序排列在 imageUrls 数组中。miaotu_v1 始终只有 1 张。

任务失败(status: 2)时,原因在 resultMetadata。


常见问题 ​

Q:提示词用中文还是英文?
A:均支持。英文提示词通常效果更稳定,建议优先尝试英文。

Q:如何让同样的提示词每次出相同结果?
A:设置固定 seed 值,并保持其他参数不变。

Q:不传 imageModel 用的是哪个模型?
A:miaotu_v1(妙图 1.0)。

Q:transparent 对通用模型有效吗?
A:无效,会被忽略。需要透明底时把 imageModel 设为 miaotu_v1。

Q:count=2 或 outputResolution=1k 消耗几个积分?
A:每次请求消耗 1 个 API_CALL 积分,与 count 和分辨率无关。

妙图设计 API Beta