PokeAPI

主题

图片生成 API 教程 ​

Poke API 使用统一的 OpenAI Images 兼容接口调用图片模型。你只需要准备 API Key、从模型列表选择可用模型，然后调用对应的公开接口。

一、准备 API Key ​

  1. 登录 Poke API 控制台。
  2. 在 API 密钥 页面创建或编辑 API Key。
  3. 绑定可以使用图片模型的分组，保存并复制密钥。
  4. 不要把完整密钥写进代码、截图、聊天记录或公开仓库。

建议将密钥读入当前终端进程的环境变量：

bash
read -rsp "Poke API Key: " POKE_API_KEY; printf '\n'
export POKE_API_KEY
powershell
$secureKey = Read-Host 'Poke API Key' -AsSecureString
$ptr = [Runtime.InteropServices.Marshal]::SecureStringToBSTR($secureKey)
try {
  $env:POKE_API_KEY = [Runtime.InteropServices.Marshal]::PtrToStringBSTR($ptr)
} finally {
  [Runtime.InteropServices.Marshal]::ZeroFreeBSTR($ptr)
}

二、模型、提供商和调用方式 ​

下表列出常见的公开模型名称。实际可用模型以当前 API Key 请求 GET /v1/models 返回的列表为准；模型上下线或权限变化时，不要继续使用列表中已不可用的名称。

提供商模型文生图图片编辑
OpenAIgpt-image-1、gpt-image-1-mini、gpt-image-2、gpt-image-2.5、gpt-image-2.5-sunburst、gpt-image-2.5-flarePOST /v1/images/generations，JSONPOST /v1/images/edits，multipart/form-data；以模型列表能力为准
OpenAIgpt-image-1.5POST /v1/images/generations，JSON当前目录未声明图片编辑能力
Googlegemini-2.5-flash-image、gemini-3.1-flash-image、gemini-3-pro-image、nano-banana、nano-banana-pro、nano-banana-2POST /v1/images/generations，JSONPOST /v1/images/edits，按模型能力使用文件或公网图片 URL
xAIgrok-imagine-image、grok-imagine-image-quality、grok-imagine-image-2.0POST /v1/images/generations，JSONPOST /v1/images/edits，按模型列表能力为准
Black Forest Labsflux-1.1-pro、flux-1.1-ultra、flux-1.1-ultra-raw、flux-kontext-pro、flux-kontext-max、flux-2-proPOST /v1/images/generations，JSONPOST /v1/images/edits，按模型列表能力为准
Runwayrunway-gen4-imagePOST /v1/images/generations，JSON以模型列表能力为准
Adobefirefly-image-3、firefly-image-4、firefly-image-4-ultra、firefly-image-5POST /v1/images/generations，JSONPOST /v1/images/edits，按模型列表能力为准
ByteDancedoubao-seedream-5-0-proPOST /v1/images/generations，JSONPOST /v1/images/edits，multipart/form-data

表中的“提供商”是模型的原厂归属。请求始终发送到 Poke API，不需要把原厂 Base URL 写进客户端，也不需要在请求中填写内部路由名称。

三、查询可用模型 ​

bash
curl --fail-with-body --silent --show-error \
  https://www.poke2api.com/v1/models \
  -H "Authorization: Bearer ${POKE_API_KEY}"

在返回的 data 数组中找到目标模型的 id。如果模型不在列表中，先检查 API Key 的分组绑定和权限，不要猜测模型名。

四、文生图 ​

公开接口：

text
POST https://www.poke2api.com/v1/images/generations

请求头：

http
Authorization: Bearer <API Key>
Content-Type: application/json

最小请求只需要 model 和 prompt：

bash
curl --fail-with-body --silent --show-error \
  https://www.poke2api.com/v1/images/generations \
  -H "Authorization: Bearer ${POKE_API_KEY}" \
  -H "Content-Type: application/json" \
  --data '{
    "model": "gpt-image-2",
    "prompt": "一只戴宇航头盔的橘猫，电影感光影，干净背景"
  }' > image-response.json

需要指定尺寸、画质或返回格式时，可以添加可选字段：

json
{
  "model": "gpt-image-2",
  "prompt": "一只戴宇航头盔的橘猫，电影感光影，干净背景",
  "size": "1024x1024",
  "quality": "high",
  "n": 1,
  "response_format": "b64_json"
}

服务默认使用 n=1、size=auto、quality=high 和 response_format=b64_json。不同模型支持的尺寸和画质值不同；遇到参数错误时，先删除可选字段，只保留 model 与 prompt。

五、图片编辑 ​

公开接口：

text
POST https://www.poke2api.com/v1/images/edits

上传本地图片 ​

使用 multipart/form-data，curl 会自动生成 boundary，不要手动设置 Content-Type：

bash
curl --fail-with-body --silent --show-error \
  https://www.poke2api.com/v1/images/edits \
  -H "Authorization: Bearer ${POKE_API_KEY}" \
  -F 'model=gpt-image-2' \
  -F 'prompt=保留主体，把背景改成夜晚城市，并增加蓝色霓虹灯' \
  -F 'image=@reference.png;type=image/png' \
  -F 'size=1024x1024' \
  -F 'quality=high' \
  -F 'response_format=b64_json'

支持的图片类型和数量取决于模型。需要多张参考图时重复 image 字段：

bash
-F 'image=@subject.png;type=image/png' \
-F 'image=@style.webp;type=image/webp'

使用公网图片 URL ​

部分模型接受 JSON 参考图。URL 必须是服务端可访问的公开 http:// 或 https:// 地址：

bash
curl --fail-with-body --silent --show-error \
  https://www.poke2api.com/v1/images/edits \
  -H "Authorization: Bearer ${POKE_API_KEY}" \
  -H "Content-Type: application/json" \
  --data '{
    "model": "gemini-3-pro-image",
    "prompt": "保留人物姿势，把背景改成海边日落",
    "images": [
      {"image_url": "https://example.com/reference.png"}
    ],
    "response_format": "b64_json"
  }'

模型不支持参考图或只支持其中一种传递方式时，接口会返回明确的参数错误。练习场显示的上传入口和模型能力是最可靠的判断依据。

六、异步任务（可选） ​

图片生成时间较长时，可以使用异步入口。提交接口返回 task_id 和 poll_url，再查询任务状态：

bash
curl --fail-with-body --silent --show-error \
  -X POST https://www.poke2api.com/v1/images/generations/async \
  -H "Authorization: Bearer ${POKE_API_KEY}" \
  -H "Content-Type: application/json" \
  --data '{
    "model": "gpt-image-2",
    "prompt": "一座漂浮在云海上的未来城市"
  }'

使用响应中的 poll_url 查询：

bash
curl --fail-with-body --silent --show-error \
  "https://www.poke2api.com/v1/images/tasks/<task_id>" \
  -H "Authorization: Bearer ${POKE_API_KEY}"

status 为 processing 时稍后重试；为 completed 时，结果位于任务响应的 result 字段；为 failed 时按 error 字段排查。不要在任务未结束时重复提交相同请求。

七、处理返回结果 ​

Base64 图片 ​

当响应包含 data[0].b64_json 时，可以保存为 PNG：

bash
python -c "import base64,json; d=json.load(open('image-response.json', encoding='utf-8')); open('generated.png','wb').write(base64.b64decode(d['data'][0]['b64_json']))"

图片 URL ​

当响应包含 data[0].url 时，请在有效期内下载：

bash
curl --fail --location "<data[0].url>" --output generated.png

n 大于 1 时遍历 data 数组保存每一张图片。不要根据示例手写响应 JSON，应以服务真实返回值为准。

八、公共参数 ​

字段必填说明
model是控制台或 /v1/models 返回的模型 ID
prompt是文生图描述，或图片编辑指令
size否模型支持的尺寸；省略时使用 auto
quality否模型支持的画质值；省略时使用默认值
n否生成数量，默认 1；建议传 JSON 数字
response_format否b64_json 或模型支持的 url
image / images编辑时按模型要求本地 multipart 文件或公网图片 URL

九、常见错误 ​

  • 401：API Key 缺失、错误、撤销或 Authorization 格式不正确。
  • 403：API Key 没有绑定可用的图片分组，或手动指定的分组无权限。
  • 400：模型名、端点、尺寸、画质或参考图格式不受支持。先用最小请求确认模型可用，再逐个增加参数。
  • 429：并发、频率或额度达到限制。等待当前任务结束后再试。
  • 超时：不要立即重复提交；先查询异步任务或检查用量记录，避免产生重复生成。

需要固定某个已绑定分组时才添加 X-Sub2API-Group-ID；不需要固定时省略该请求头，让服务按 API Key 的绑定和模型能力选择可用分组。

相关页面：API 脚本接入、本地优先 Playground、快速开始。

PokeAPI · AI API Gateway

© 2026 PokeAPI · 保留所有权利