主题模式
MOSS 图像生成 API 文档
文生图接口。支持直接生图,或在同一次请求内先增强提示词再生图。一次生成一张 PNG,返回图片 URL,不支持流式输出。
请求经过平台图像接口。调用方使用平台 API Key 和标准模型名;平台再转发到模型服务。成功响应是平台标准生图格式,失败响应是平台统一错误体。
接口信息
| 项目 | 说明 |
|---|---|
| 分类 | 图像生成 / 文生图 |
| 请求方法 | POST |
| 请求地址 | https://aiping.cn/api/v1/images/generations |
| 鉴权 | Authorization: Bearer <API_KEY>,<API_KEY> 为平台 API Key |
| Content-Type | application/json |
| 建议超时 | 900 秒 |
推荐使用 OpenAI 标准格式:prompt 与生成参数放在请求体顶层。也支持嵌套格式,见文末。
计费说明
| 能力 | 计费方式 | 人民币价格 |
|---|---|---|
| 生图 | 低:约 100 万像素 总像素数 ≤ 1,048,576 | ¥0.20 / 张 |
| 生图 | 高:约 200 万像素 总像素数大于 1,048,576,且不超过 2,097,152 | ¥0.30 / 张 |
| 智能改写 | 按改写次数 开启时额外计费 | ¥0.05 / 次 |
生图按张计费,每张图片按总像素数(宽 × 高)分档。相同总像素数的图片适用同一档位。设置 prompt_enhance: true 开启智能改写后,按改写次数另计。
单次调用按实际用量计算。
请求参数
| 参数名 | 类型 | 必填 | 说明 | 默认值 | 取值范围/格式 |
|---|---|---|---|---|---|
model | string | 是 | 平台标准模型名 | - | 当前为 Moss-Image-SFT |
prompt | string | 是 | 待生成图像的文本描述 | - | 非空字符串,最多 4000 字符 |
prompt_enhance | boolean | 否 | 是否在同一个任务内先增强提示词再生图 | false | false:直接使用原始 prompt 生图。true:先增强提示词,再将完整增强文本用于生图 |
negative_prompt | string | 否 | 不希望出现在图片中的内容 | - | 最多 4000 字符 |
size | string | 否 | 图片尺寸,格式为宽x高 | 1024x1024 | 每边 256–2048,且为 16 的倍数;总像素不超过 2097152 |
n | integer | 否 | 生成图片数量。省略时不传给模型,模型生成 1 张 | - | 传入时仅支持整数 1 |
seed | integer | 否 | 随机种子。未提供时由模型随机生成 | 系统随机 | 0–2^53−1 |
num_inference_steps | integer | 否 | 推理步数 | - | 1–100 |
guidance_scale | number | 否 | 引导系数。显式传入 0 有效 | - | 0–10 |
response_format | string | 否 | 图片结果的返回方式 | url | 仅支持 url |
output_watermark | object | 否 | 输出水印设置。enabled 为布尔值 | 开启可见水印 | 省略时默认开启可见水印;传 {"enabled": false} 关闭可见水印 |
extra_body.provider | object | 否 | 平台调度与响应控制 | - | 见 服务商调度参数说明 |
model 填写 Moss-Image-SFT。上游 model ID(如 moss-image-sft-1.0、moss-image-base-1.0 及 snapshot ID)不在平台标准目录中,传入后返回 HTTP 422。
上表中的取值范围由模型校验。超出范围时,调用方收到的是下方「错误响应」里的 HTTP 400,消息中包含模型返回的原始内容。
请求示例
cURL
bash
curl --max-time 900 -X POST "https://aiping.cn/api/v1/images/generations" \
-H "Authorization: Bearer <API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"model": "Moss-Image-SFT",
"prompt": "一只橘猫坐在窗边,窗外是雨后的花园,柔和的自然光,温暖细腻的摄影风格。",
"negative_prompt": "nsfw, worst quality, bad anatomy, watermark, jpeg artifact",
"prompt_enhance": false,
"size": "1024x1024",
"n": 1,
"response_format": "url",
"output_watermark": {"enabled": true},
"extra_body": {
"provider": {
"only": ["MOSS"],
"allow_fallbacks": false
}
}
}'Python
python
import os
import requests
response = requests.post(
"https://aiping.cn/api/v1/images/generations",
headers={
"Authorization": f"Bearer {os.environ['API_KEY']}",
"Content-Type": "application/json",
},
timeout=900,
json={
"model": "Moss-Image-SFT",
"prompt": "一只橘猫坐在窗边,窗外是雨后的花园,柔和的自然光,温暖细腻的摄影风格。",
"negative_prompt": "nsfw, worst quality, bad anatomy, watermark, jpeg artifact",
"prompt_enhance": False,
"size": "1024x1024",
"n": 1,
"response_format": "url",
"output_watermark": {"enabled": True},
"extra_body": {
"provider": {
"only": ["MOSS"],
"allow_fallbacks": False,
}
},
},
)
response.raise_for_status()
print(response.json())TypeScript
ts
const response = await fetch("https://aiping.cn/api/v1/images/generations", {
method: "POST",
signal: AbortSignal.timeout(900_000),
headers: {
"Authorization": "Bearer " + process.env.API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({
model: "Moss-Image-SFT",
prompt: "一只橘猫坐在窗边,窗外是雨后的花园,柔和的自然光,温暖细腻的摄影风格。",
negative_prompt: "nsfw, worst quality, bad anatomy, watermark, jpeg artifact",
prompt_enhance: false,
size: "1024x1024",
n: 1,
response_format: "url",
output_watermark: { enabled: true },
extra_body: {
provider: {
only: ["MOSS"],
allow_fallbacks: false,
},
},
}),
})
if (!response.ok) throw new Error(`HTTP ${response.status}`)
console.log(await response.json())成功响应
| 参数名 | 类型 | 必返 | 说明 |
|---|---|---|---|
created | integer | 是 | Unix 时间戳(秒) |
data | array | 是 | 生成图片列表,当前长度为 1 |
data[].url | string | 是 | 图片 URL |
usage | object | 是 | 用量。同时包含平台计费字段和模型用量字段 |
usage.image_count | integer | 是 | 实际生成图片数,平台按此计费 |
usage.total_tokens | integer | 是 | 总 token 数,图像生成场景为 0 |
usage.input_tokens | integer | 是 | 输入 token 数,图像生成场景为 0 |
usage.output_tokens | integer | 是 | 输出 token 数,图像生成场景为 0 |
usage.input_tokens_details.text_tokens | integer | 是 | 文本 token 数,图像生成场景为 0 |
usage.input_tokens_details.image_tokens | integer | 是 | 图像 token 数,图像生成场景为 0 |
usage.generated_images | integer | 是 | 模型报告的生成图片数 |
usage.output_width | integer | 是 | 实际图片宽度,单位像素 |
usage.output_height | integer | 是 | 实际图片高度,单位像素 |
provider | string | 是 | 服务商名称。服务商未对外展示时为 "-" |
model | string | 是 | 标准模型名,当前为 Moss-Image-SFT |
aiping_id | string | 是 | 本次请求 ID。响应头 AIPing-Id 为同一值 |
模型返回的成功体必须恰好包含一张非空图片 URL,且 generated_images、output_width、output_height 为正整数。否则平台视为失败,调用方收到 HTTP 503。
响应示例
json
{
"created": 1794277457,
"data": [
{
"url": "https://example.com/generated-image.png"
}
],
"usage": {
"total_tokens": 0,
"input_tokens": 0,
"output_tokens": 0,
"input_tokens_details": {
"text_tokens": 0,
"image_tokens": 0
},
"image_count": 1,
"generated_images": 1,
"output_width": 1024,
"output_height": 1024
},
"provider": "-",
"model": "Moss-Image-SFT",
"aiping_id": "01a1c345-383a-7674-860c-4194866c73b5"
}错误响应
失败时返回平台统一错误体。响应没有独立的 error.code 字段。模型原始错误码若出现,只嵌在 detail.message 的文本中。
json
{
"detail": {
"message": "All providers failed. Last error: Provider returned status 400: {'error': {'code': 'invalid_field_value', 'message': '...'}}",
"error_type": "validation_error"
},
"aiping_id": "01a1c345-383a-7674-860c-4194866c73b5"
}请求体无法解析为 JSON 时没有 aiping_id。其余失败在能识别请求后都会带上 aiping_id。
| HTTP | error_type | 触发条件 |
|---|---|---|
400 | validation_error | 平台拒绝的请求:带参考图、stream: true、n 不是整数 1、response_format 不是 url。message 形如 All providers failed. Last error: Provider returned status 400: ... |
400 | validation_error | 模型以 HTTP 400 拒绝参数,例如字段类型、取值范围不合法。message 中包含模型原始内容 |
401 | - | 平台 API Key 缺失或无效。见 错误处理 |
422 | validation_error | 请求体不是合法 JSON、prompt 为空,或 model 不在标准目录 |
503 | provider_error | 模型返回 403、404、429、502,或成功体结构、用量不合法。message 为「暂无可用服务商,请稍后重试」。这些情况对外状态码和文案相同,无法用 error.code 区分鉴权、安全拦截、资源不存在、并发或频率超限、增强失败 |
503 | provider_error | 生成超时。message 为「请求超时,请稍后重试」 |
503 | pricing_unavailable | 该模型在当前服务商下没有价格配置 |
503 | provider_error | 没有可用服务商 |
嵌套格式
参数也可以按内部格式提交,效果与顶层格式相同。prompt、negative_prompt 放在 input 中,其余生成参数放在 extra_body 中。
json
{
"model": "Moss-Image-SFT",
"input": {
"prompt": "一只橘猫坐在窗边,窗外是雨后的花园,柔和的自然光,温暖细腻的摄影风格。",
"negative_prompt": "nsfw, worst quality, bad anatomy, watermark, jpeg artifact"
},
"extra_body": {
"prompt_enhance": false,
"size": "1024x1024",
"n": 1,
"response_format": "url",
"output_watermark": {"enabled": true},
"provider": {
"only": ["MOSS"],
"allow_fallbacks": false
}
}
}