Skip to content

MOSS 图像生成 API 文档 ​

文生图接口。支持直接生图,或在同一次请求内先增强提示词再生图。一次生成一张 PNG,返回图片 URL,不支持流式输出。

请求经过平台图像接口。调用方使用平台 API Key 和标准模型名;平台再转发到模型服务。成功响应是平台标准生图格式,失败响应是平台统一错误体。

接口信息 ​

项目说明
分类图像生成 / 文生图
请求方法POST
请求地址https://aiping.cn/api/v1/images/generations
鉴权Authorization: Bearer <API_KEY>,<API_KEY> 为平台 API Key
Content-Typeapplication/json
建议超时900 秒

推荐使用 OpenAI 标准格式:prompt 与生成参数放在请求体顶层。也支持嵌套格式,见文末。

计费说明 ​

能力计费方式人民币价格
生图低:约 100 万像素
总像素数 ≤ 1,048,576
¥0.20 / 张
生图高:约 200 万像素
总像素数大于 1,048,576,且不超过 2,097,152
¥0.30 / 张
智能改写按改写次数
开启时额外计费
¥0.05 / 次

生图按张计费,每张图片按总像素数(宽 × 高)分档。相同总像素数的图片适用同一档位。设置 prompt_enhance: true 开启智能改写后,按改写次数另计。

单次调用按实际用量计算。

请求参数 ​

参数名类型必填说明默认值取值范围/格式
modelstring是平台标准模型名-当前为 Moss-Image-SFT
promptstring是待生成图像的文本描述-非空字符串,最多 4000 字符
prompt_enhanceboolean否是否在同一个任务内先增强提示词再生图falsefalse:直接使用原始 prompt 生图。
true:先增强提示词,再将完整增强文本用于生图
negative_promptstring否不希望出现在图片中的内容-最多 4000 字符
sizestring否图片尺寸,格式为宽x高1024x1024每边 256–2048,且为 16 的倍数;总像素不超过 2097152
ninteger否生成图片数量。省略时不传给模型,模型生成 1 张-传入时仅支持整数 1
seedinteger否随机种子。未提供时由模型随机生成系统随机0–2^53−1
num_inference_stepsinteger否推理步数-1–100
guidance_scalenumber否引导系数。显式传入 0 有效-0–10
response_formatstring否图片结果的返回方式url仅支持 url
output_watermarkobject否输出水印设置。enabled 为布尔值开启可见水印省略时默认开启可见水印;传 {"enabled": false} 关闭可见水印
extra_body.providerobject否平台调度与响应控制-见 服务商调度参数说明

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())

成功响应 ​

参数名类型必返说明
createdinteger是Unix 时间戳(秒)
dataarray是生成图片列表,当前长度为 1
data[].urlstring是图片 URL
usageobject是用量。同时包含平台计费字段和模型用量字段
usage.image_countinteger是实际生成图片数,平台按此计费
usage.total_tokensinteger是总 token 数,图像生成场景为 0
usage.input_tokensinteger是输入 token 数,图像生成场景为 0
usage.output_tokensinteger是输出 token 数,图像生成场景为 0
usage.input_tokens_details.text_tokensinteger是文本 token 数,图像生成场景为 0
usage.input_tokens_details.image_tokensinteger是图像 token 数,图像生成场景为 0
usage.generated_imagesinteger是模型报告的生成图片数
usage.output_widthinteger是实际图片宽度,单位像素
usage.output_heightinteger是实际图片高度,单位像素
providerstring是服务商名称。服务商未对外展示时为 "-"
modelstring是标准模型名,当前为 Moss-Image-SFT
aiping_idstring是本次请求 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。

HTTPerror_type触发条件
400validation_error平台拒绝的请求:带参考图、stream: true、n 不是整数 1、response_format 不是 url。message 形如 All providers failed. Last error: Provider returned status 400: ...
400validation_error模型以 HTTP 400 拒绝参数,例如字段类型、取值范围不合法。message 中包含模型原始内容
401-平台 API Key 缺失或无效。见 错误处理
422validation_error请求体不是合法 JSON、prompt 为空,或 model 不在标准目录
503provider_error模型返回 403、404、429、502,或成功体结构、用量不合法。message 为「暂无可用服务商,请稍后重试」。这些情况对外状态码和文案相同,无法用 error.code 区分鉴权、安全拦截、资源不存在、并发或频率超限、增强失败
503provider_error生成超时。message 为「请求超时,请稍后重试」
503pricing_unavailable该模型在当前服务商下没有价格配置
503provider_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
    }
  }
}

相关文档 ​