图片生成

这页能做什么

你可以用一段文字提示生成图片，支持一次生成多张，并按需要返回图片链接或 base64。

前置条件

已有 LokoSpace API Key，请求头使用 Authorization: Bearer <你的 LokoSpace API Key>
账号积分足够支付本次生成
模型出现在 GET /images/models 的返回里。看不到某个模型，说明它未上架、未配置按次定价，或对应渠道不可用
请求体使用 Content-Type: application/json

可用模型

curl https://sheverai.com/8811c8/api/llm/v1/images/models \
  -H "Authorization: Bearer $LOKO_KEY"

{
  "object": "list",
  "data": [
    {
      "id": "<图片模型 ID>",
      "object": "model",
      "owned_by": "lokospace",
      "display_name": "示例图片模型",
      "billing_mode": "per_unit",
      "credits_per_unit": "<最低单张积分>",
      "pricing": [
        { "resolution": "1K", "credits_per_unit": "<1K 单张积分>" },
        { "resolution": "4K", "credits_per_unit": "<4K 单张积分>" }
      ]
    }
  ]
}

字段	类型	说明
`object`	string	固定为 `list`
`data`	array	可用图片模型
`data[].id`	string	请求体里的 `model`
`data[].object`	string	固定为 `model`
`data[].owned_by`	string	固定为 `lokospace`
`data[].display_name`	string	展示名称
`data[].billing_mode`	string	图片固定为 `per_unit`
`data[].credits_per_unit`	number	该模型最低的单张积分价
`data[].pricing`	array	按分辨率拆分的价格档位
`data[].pricing[].resolution`	string \| null	档位名；`null` 表示不区分分辨率
`data[].pricing[].credits_per_unit`	number	该档位单张积分

pricing 是实际可选的档位。credits_per_unit 只用于快速比较，真正扣费按请求匹配到的档位计算。

调用示例

curl https://sheverai.com/8811c8/api/llm/v1/images/generations \
  -H "Authorization: Bearer $LOKO_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: img-20261022-001" \
  -d '{
    "model": "<图片模型 ID>",
    "prompt": "一座海边小屋，清晨薄雾，写实摄影",
    "size": "1024x1024",
    "n": 1,
    "response_format": "url"
  }'

字段	类型	必填	说明
`model`	string	是	取自 `/images/models`，最长 100 字符
`prompt`	string	是	图片描述，最长 32000 字符
`size`	string	否	`宽x高` 像素，如 `1024x1024`。服务端会近似映射到模型支持的档位
`n`	integer	否	生成张数，1 到 10，默认 1
`response_format`	string	否	`url` 或 `b64_json`，默认 `url`
`Idempotency-Key`	string	否	请求头。建议传，用于防重复扣费和结果重放

Idempotency-Key 也可以换成 X-Request-Id。两者都不传时，服务端会为这次请求生成新的 ID。

返回示例

{
  "created": 1761090000,
  "data": [
    { "url": "https://cdn.example.com/generated/image.png" }
  ],
  "lokospace_billing": {
    "requestId": "<请求 ID>",
    "creditsUsed": "<本次扣除积分>",
    "balanceAfter": "<扣除后余额>",
    "duplicate": false
  }
}

response_format 为 b64_json 时，data 里是：

{
  "created": 1761090000,
  "data": [
    { "b64_json": "<base64 图片数据>" }
  ]
}

响应同样带 lokospace_billing。

字段	类型	说明
`created`	integer	服务端生成完成时间，Unix 秒
`data`	array	生成结果，长度等于 `n`
`data[].url`	string	图片地址，通常是 http(s) 链接；也可能直接是 data URL
`data[].b64_json`	string	base64 图片数据，仅在 `response_format=b64_json` 时返回
`lokospace_billing.requestId`	string	本次请求 ID
`lokospace_billing.creditsUsed`	number	本次实际扣除积分
`lokospace_billing.balanceAfter`	number \| null	扣除后余额
`lokospace_billing.duplicate`	boolean	是否命中了相同幂等键的已有结果

成功响应还会带两个头：x-lokospace-request-id 和 x-lokospace-credits-used。

计费说明

图片按 per_unit 计费，单位是张。总价 = 单张积分 × n。n 大于 1 时按张数线性累加，没有批量折扣。

size 会匹配 model_pricing 里的分辨率档位，匹配不到时优先使用不区分分辨率的档位；没有这种档位时使用列表中的第一个档位。单价从 model_pricing 读取，文档不写死具体价格，以 GET /models 返回为准；调用前也可以用 GET /images/models 查看每个档位的单价。

1 元 = 100 积分。服务端先扣费再生成；任意一张失败都会整笔退款，不会返回部分图片。相同幂等键的并发请求只扣一次。

错误与常见问题

状态	含义	处理
400	参数不合法，如缺少 `model`、`prompt`，或 `n` 超出 1 到 10	按返回的 `message` 修正
401	密钥缺失、无效、已撤销或已过期	重新创建或更换密钥
402	积分不足	充值后重试。响应里的 `available_credits` 是可用余额
404	模型不存在或未启用	重新拉取 `/images/models`，换成列表里的 `id`
409	相同幂等键的请求正在执行，或该请求已完成但结果未缓存	正在执行时等结束后重试；结果未缓存时换一个幂等键
429	上游模型服务并发或频率受限	退避后重试。图片入口没有单独限流
502	上游模型服务生成失败、结果为空、下载失败，或模型队列排队超时	稍后重试；失败已自动退款
503	没有可用的按次定价，或渠道凭证不可用	联系管理员检查模型定价与渠道

常见问题：

size 为什么不是精确像素？服务端只做近似映射，实际输出由模型能力决定。需要固定档位时，按 pricing[].resolution 选择。
请求多久超时？图片是同步语义，默认最多等待 180 秒。超时会按失败退款；图片没有任务查询接口，超时后即使上游后来成功也拿不到结果。
用 b64_json 重试为什么返回 409？base64 结果不写入计费记录，无法重放。需要结果时换一个新的幂等键重新生成，不会重复扣费。

开发者文档