主题
文生图(Text to Image)
根据文字描述生成图像。未指定 imageModel 时使用 妙图 1.0(miaotu_v1)。
在编辑器中试用:文生图。
基本信息
| 项目 | 值 |
|---|---|
| 接口路径 | POST /image/text2image |
| 所需 Scope | text2image 或 * |
| 任务类型 | 异步,返回 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]
}参数说明
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
requestId | string | 否 | 服务端生成 | 调用方请求 ID,用于去重和支持定位。省略时服务端生成,并在响应里返回 |
positive | string | 是 | — | 正向提示词,描述想要生成的内容。任务记录保存这段原文 |
negative | string | 否 | 空字符串 | 负向提示词。miaotu_v1、base_v2 出图不使用该字段 |
ar | string | 否 | 1:1 | 图像宽高比,如 1:1、16:9、4:3、3:2、9:16、3:4、2:3。也可传其他 宽:高 |
seed | integer | 否 | 随机 | 随机种子(≥0)。未传时服务端生成 |
count | integer | 否 | 1 | 生成图像数量(1 ~ 4)。miaotu_v1 实际固定为 1,传入 2–4 时收成 1 |
imageModel | string | 否 | miaotu_v1 | 见下方模型表。未知取值按 base_v1 出图 |
outputResolution | string | 否 | 随模型 | 1k、1.5k、2k。miaotu_v1 默认 1k,三者都可用。其他模型默认 1.5k,传入 2k 时按 1.5k 出图 |
transparent | boolean | 否 | false | 透明背景(RGBA)。仅 miaotu_v1 生效,其他模型忽略。开启后输出带 alpha 的图 |
promptEnhanced | string | 否 | — | 可选增强文案。有值时提交给出图引擎,任务仍把 positive 记为用户原文。空白且开启 transparent 时,后端可能做去背景改写。查询任务不会返回该字段 |
styleIds | integer[] | 否 | 空 | 风格 ID 列表,与 styleStrengths 对应。须为该模型支持的风格,否则返回错误。miaotu_v1、base_v2 出图不应用风格 LoRA |
styleStrengths | number[] | 否 | 按 1.0 补齐 | 各风格强度,与 styleIds 对应。短于 styleIds 时,缺的位置按 1.0 补齐 |
分辨率和张数不改变本次计费,仍为 1 个
API_CALL。查询任务不会返回promptEnhanced。
模型
imageModel | 名称 | 出图张数 | 分辨率 | 备注 |
|---|---|---|---|---|
miaotu_v1(默认) | 妙图 1.0 | 固定 1 | 1k / 1.5k / 2k,默认 1k | 支持 transparent |
base_v1 | 通用 1.0 | 1 ~ 4 | 1k / 1.5k,默认 1.5k | 未知模型回退到此 |
lancer_v1 | 蓝瑟 1.0 | 1 ~ 4 | 1k / 1.5k,默认 1.5k | |
realistic_v1 | 真实影像 1.0 | 1 ~ 4 | 1k / 1.5k,默认 1.5k | |
text_enhance_v1 | 文字增强 1.0 | 1 ~ 4 | 1k / 1.5k,默认 1.5k | |
text_enhance_v2 | 文字增强 2.0 | 1 ~ 4 | 1k / 1.5k,默认 1.5k | |
base_v2(已弃用) | 通用 2.0 | 1 ~ 4 | 1k / 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 和分辨率无关。
