图片 API 对接文档

快速开始

在控制台创建 API Key，然后把下面的 sk-your-key 替换为自己的 Key。

curl -i https://aimasker.com/v1/images/generations/async \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "一只戴宇航头盔的橘猫，电影级灯光",
    "size": "2880x2880",
    "quality": "high",
    "response_format": "b64_json",
    "output_format": "png",
    "n": 1
  }'

提交成功返回 202 Accepted、task_id 和 poll_url。使用同一 API Key 轮询：

curl https://aimasker.com/v1/images/tasks/imgtask_xxx \
  -H "Authorization: Bearer sk-your-key"

AIMasker 图片接口 Skill

适用于 Codex 及支持 SKILL.md / Agent Skills 目录规范的工具。默认使用异步 URL 并立即下载落盘；用户明确要求时可切换同步 Base64。内置 4K、high、最多 16 张参考图编辑，以及 Request ID/task_id 请求台账。

Codex 一键安装（Windows PowerShell）

$skillZip = Join-Path $env:TEMP "aimasker-image-api.zip"
Invoke-WebRequest "https://api.aimasker.com/image-api-docs/downloads/aimasker-image-api.zip" -OutFile $skillZip
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.codex\skills" | Out-Null
Expand-Archive $skillZip -DestinationPath "$env:USERPROFILE\.codex\skills" -Force
python -m pip install -r "$env:USERPROFILE\.codex\skills\aimasker-image-api\requirements.txt"

macOS / Linux

mkdir -p ~/.codex/skills
curl -L "https://api.aimasker.com/image-api-docs/downloads/aimasker-image-api.zip" -o /tmp/aimasker-image-api.zip
unzip -o /tmp/aimasker-image-api.zip -d ~/.codex/skills
python3 -m pip install -r ~/.codex/skills/aimasker-image-api/requirements.txt

配置与调用

设置环境变量 AIMASKER_API_KEY 后重新打开 Codex 或对应工具。Windows 可执行：

[System.Environment]::SetEnvironmentVariable("AIMASKER_API_KEY", "你的 API Key", "User")

macOS（默认 zsh）可持久化写入：

echo 'export AIMASKER_API_KEY="你的 API Key"' >> ~/.zshrc
source ~/.zshrc

Linux（常见 bash）可持久化写入：

echo 'export AIMASKER_API_KEY="你的 API Key"' >> ~/.bashrc
source ~/.bashrc

调用示例：

$aimasker-image-api 生成一张 16:9、4K、high 的电影感城市夜景

SHA256：C419789F02B07AC50CA5995D145FA58FB4A2983FFD8A8402A836EBBFC139166B

认证方式

所有请求都要在 HTTP Header 中携带 Bearer Token：

Authorization: Bearer sk-your-key

请勿把 API Key 写入前端网页、公开仓库、日志或截图。服务端调用时建议通过环境变量读取。

异步 URL（推荐）

异步接口不会要求客户端维持一个长时间生成连接，适合 4K 图片、自动化工具和高并发调用。提交生成 POST 只执行一次，后续只轮询任务 GET。

提交响应

{
  "id": "imgtask_xxx",
  "task_id": "imgtask_xxx",
  "status": "processing",
  "poll_url": "/v1/images/tasks/imgtask_xxx"
}

完成响应

{
  "task_id": "imgtask_xxx",
  "status": "completed",
  "image_url": "https://imgs.aimasker.com/images/xxx.png",
  "result": {
    "created": 1788172800,
    "data": [{"url": "https://imgs.aimasker.com/images/xxx.png"}]
  }
}

文生图

Python 示例

import base64
import os
import requests

response = requests.post(
    "https://aimasker.com/v1/images/generations",
    headers={"Authorization": f"Bearer {os.environ['AIMASKER_API_KEY']}"},
    json={
        "model": "gpt-image-2",
        "prompt": "中国古风山水，云海中的宫殿，横向构图",
        "size": "3840x2160",
        "quality": "high",
        "response_format": "b64_json",
        "output_format": "png",
        "n": 1,
    },
    timeout=600,
)
response.raise_for_status()
image_bytes = base64.b64decode(response.json()["data"][0]["b64_json"])
with open("generated.png", "wb") as output:
    output.write(image_bytes)

图片编辑

上传一张参考图时使用 image；上传多张参考图时重复提交 image[]，最多 16 张。可选上传透明蒙版 mask。

curl https://aimasker.com/v1/images/edits \
  -H "Authorization: Bearer sk-your-key" \
  -F "model=gpt-image-2" \
  -F "prompt=保留人物与构图，把背景改成雨夜霓虹街道" \
  -F "image=@reference.png" \
  -F "size=2160x3840" \
  -F "quality=high" \
  -F "response_format=b64_json" \
  -F "output_format=png" \
  -F "n=1"

多参考图

curl https://aimasker.com/v1/images/edits \
  -H "Authorization: Bearer sk-your-key" \
  -F "model=gpt-image-2" \
  -F "prompt=使用第一张图的人物和第二张图的服装，生成完整角色图" \
  -F "image[]=@character.png" \
  -F "image[]=@costume.png" \
  -F "size=2448x3264" \
  -F "quality=high" \
  -F "response_format=b64_json"

参数说明

图片尺寸表

size 为可选项，支持 1K、2K、4K，默认 4K。比例文字写进提示词不能代替 size 参数，且 quality=high 不能代替尺寸参数。

图片获取与保存

异步 URL 下载

task = requests.get(
    f"https://aimasker.com/v1/images/tasks/{task_id}",
    headers={"Authorization": f"Bearer {os.environ['AIMASKER_API_KEY']}"},
).json()

if task["status"] == "completed":
    image_url = task["result"]["data"][0]["url"]
    image_bytes = requests.get(image_url, timeout=120).content
    with open("generated.png", "wb") as output:
        output.write(image_bytes)

同步 Base64

在线作图和明确要求同步的客户端调用原生成/编辑接口，读取 data[].b64_json，解码为图片二进制后保存。不要为了同一张图同时调用同步和异步接口。

响应示例

{
  "created": 1788172800,
  "data": [
    {"b64_json": "iVBORw0KGgoAAAANSUhEUgAA..."}
  ]
}

Python：解码并保存全部图片

import base64

body = response.json()
for index, item in enumerate(body["data"], start=1):
    encoded = item["b64_json"]
    # 兼容可能带有 data:image/png;base64, 前缀的返回值
    if "," in encoded and encoded.startswith("data:"):
        encoded = encoded.split(",", 1)[1]
    with open(f"image_{index}.png", "wb") as output:
        output.write(base64.b64decode(encoded))

Node.js：解码并保存

import { writeFile } from "node:fs/promises";

const body = await response.json();
for (const [index, item] of body.data.entries()) {
  const encoded = item.b64_json.includes(",")
    ? item.b64_json.split(",", 2)[1]
    : item.b64_json;
  await writeFile(`image_${index + 1}.png`, Buffer.from(encoded, "base64"));
}

浏览器：直接预览 PNG

const encoded = body.data[0].b64_json;
document.querySelector("#result-image").src =
  `data:image/png;base64,${encoded}`;

错误与重试

计费说明

$0.05 / 张

按成功返回的图片数量计费。若 n=2 并成功返回两张图片，则费用为 $0.10。调用失败是否计费取决于请求是否已经进入处理流程，请保留请求 ID 便于核查。