海外客 · 生图使用教程

从两把 Key
到第一张图

按步骤完成接口配置、文字生图和参考图编辑。教程内的调用会使用套餐额度,没有额外免费试用额度。

1. 领取两把 Key,确认工具兼容

付款后通过海外客客服提供订单号。人工开通后,你会收到一把 GPT Key 和一把 Nano Key,以及套餐到期信息。

Key 相当于套餐使用凭证。只保存在自己的设备或受信任的服务端;不要贴到公开网页、群聊、截图或代码仓库中。
API Basehttps://miaoma.ai/v1
鉴权Authorization: Bearer 你的Key
文字生图POST /images/generations
参考图编辑POST /images/edits(multipart/form-data)

第三方工具需要支持自定义 Base URL、自定义模型和 Images API。仅支持聊天接口的工具不能直接出图。Base URL 填到 /v1 即可,避免重复拼接 /v1。

没有合适工具时,可以运行下面的 Python 示例。需先安装 Python 3;示例只使用标准库,不需要安装额外依赖。

2. 先生成一张 GPT 图片

把下面代码保存为 first_image.py,在文件所在目录运行。输入 GPT Key,等待完成后,图片会保存在同一目录。

# 保存为 first_image.py,然后运行 python3 first_image.py
# 仅在自己的电脑运行;不要把 Key 放进公开网页、截图或代码仓库。
import base64, getpass, json, urllib.request, urllib.error

key = getpass.getpass("粘贴 GPT Key(输入不显示):").strip()
payload = {
    "model": "gpt-image-2-standard",
    "prompt": "一只蓝色陶瓷咖啡杯,白色桌面,柔和自然光,干净的产品摄影",
    "n": 1
}
request = urllib.request.Request(
    "https://miaoma.ai/v1/images/generations",
    data=json.dumps(payload).encode("utf-8"),
    headers={"Authorization": "Bearer " + key,
             "Content-Type": "application/json"}
)
try:
    with urllib.request.urlopen(request, timeout=300) as response:
        result = json.load(response)
    encoded = result["data"][0].get("b64_json")
    if not encoded:
        raise ValueError("没有收到图片;先查询额度,再联系客服。")
    image = base64.b64decode(encoded)
    suffix = ".png" if image.startswith(b"\x89PNG") else (
        ".jpg" if image.startswith(b"\xff\xd8") else ".webp")
    filename = "first-image" + suffix
    with open(filename, "wb") as output:
        output.write(image)
    print("图片已保存:", filename)
except urllib.error.HTTPError as error:
    print("请求失败:", error.code, error.read().decode("utf-8", "replace"))
except Exception as error:
    print("请求未完成:", error)
    print("请先查询额度,确认结果后再重试。")

GPT 模型:gpt-image-2-standard。当前为标准账号通道,实测约 1254 × 1254、low 质量;不承诺自定义尺寸或高质量档。示例不传 size / quality,避免把参数误认为输出保证。

3. 用 Nano 选择分辨率和画幅

重新运行示例时输入 Nano Key,将提示文字中的 GPT 改为 Nano,并替换 payload。两把 Key 不能混用。

模型名规格每张扣费
nano-banana-2-1k1K1 额度
nano-banana-2-2k2K1 额度
nano-banana-2-4k4K2 额度
# 使用 Nano Key,并将上面的 payload 替换为:
payload = {
    "model": "nano-banana-2-2k",
    "prompt": "一座海边白色建筑,建筑摄影,清晨自然光",
    "n": 1,
    "extra_fields": {"aspect_ratio": "16:9"}
}
# 1K: nano-banana-2-1k,每张 1 额度
# 2K: nano-banana-2-2k,每张 1 额度
# 4K: nano-banana-2-4k,每张 2 额度
画幅放在 extra_fields.aspect_ratio 内,例如 1:1 或 16:9,不要写成顶层 aspect_ratio。方图实测 1K / 2K / 4K 的边长分别为 1024 / 2048 / 4096;其他画幅的实际像素随模型输出变化。

4. 上传参考图进行编辑

下面以 Nano 2K 为例。准备一张 reference.png,与终端当前目录保持一致,或改成图片的完整路径。Windows 用户可在支持 curl 的兼容终端运行,或使用支持图像编辑接口的客户端。

# macOS / Linux 终端;读取 Key 时不回显
printf '粘贴 Nano Key: '
read -r -s IMAGE_KEY
printf '\n'
# reference.png 替换为你电脑上的图片路径
curl --max-time 300 https://miaoma.ai/v1/images/edits \
  -H "Authorization: Bearer $IMAGE_KEY" \
  -F 'model=nano-banana-2-2k' \
  -F 'prompt=保留主体,将背景改为浅蓝色摄影棚' \
  -F 'n=1' \
  -F 'extra_fields={"aspect_ratio":"1:1"}' \
  -F 'image=@reference.png' \
  -o edit-result.json
unset IMAGE_KEY
# 解码返回的图片(在同一个目录执行)
python3 - <<'PYIMAGE'
import json, base64
from pathlib import Path
result = json.loads(Path("edit-result.json").read_text())
if not result.get("data") or not result["data"][0].get("b64_json"):
    raise SystemExit("未收到图片,请查看 edit-result.json 并先查询额度。")
image = base64.b64decode(result["data"][0]["b64_json"])
suffix = ".png" if image.startswith(b"\x89PNG") else (
    ".jpg" if image.startswith(b"\xff\xd8") else ".webp")
Path("edited-image" + suffix).write_bytes(image)
print("已保存 edited-image" + suffix)
PYIMAGE
  • 参考图支持 PNG、JPEG、WebP;每张最多 10MB,最多 4 张。
  • 每次只请求一张结果:n=1,不要开启流式输出。
  • 每把 Key 同时只发一个请求,收到结果后再提交下一张。
  • GPT 编辑使用 GPT Key 和 gpt-image-2-standard,省略 Nano 的画幅参数。

5. 查看额度与有效期

打开生图额度页,分别查询 GPT 和 Nano Key。两者各自计量,不互相借用;提交 Key 前确认域名为 sub.miaoma.ai。

  • 北京时间每天 00:00 刷新,未用额度不累计。
  • 套餐从开通起有效 30 天,同时受每日上限和周期总量限制。
  • Nano 1K / 2K 每张 1 额度;4K 每张 2 额度。
  • 额度耗尽后不会自动使用钱包余额计费。

6. 遇到问题,先看这几项

显示鉴权失败 / 401

检查 Key 是否完整、有无前后空格,Authorization 是否为 Bearer 加一个空格再加 Key;确认套餐已开通且未到期。

找不到模型或没有权限

逐字核对模型名,确认 GPT 模型配 GPT Key、Nano 模型配 Nano Key。不要填写模型的中文展示名称。

额度不足或请求过于频繁

先查询对应 Key 额度。4K 需要至少 2 个 Nano 额度;有额度时再检查是否同时发起了多个请求,每把 Key 只允许 1 个并发。

超时、断网、图片没有显示

图片生成可能需要较长时间,请保留等待窗口。明确上游失败或空图片不计额度;网络异常不能直接判断是否已生成,先查额度,再决定重试。接口返回的是 data[0].b64_json,需解码保存,不能直接当作图片网址。

生成尺寸和预期不一致

GPT 为标准通道,不保证指定 size / quality 生效。Nano 请核对模型的 1k / 2k / 4k 后缀,以及 extra_fields 中的 aspect_ratio;不是所有比例都对应固定边长。

仍未解决?联系客服时提供订单号、模型名、请求时间、错误信息及请求 ID(如有)。遮盖 API Key,不发送完整鉴权头。