QP企鹅派 QIEPAI
开始创作

DEVELOPER DOCS / 开发者文档

5 分钟，接入第一张图

企鹅派开放 API 与站内工作台共用同一生成管线与积分账本。统一鉴权、异步任务、失败不计费。

QUICKSTART

快速开始

  1. 01

    注册并领取体验积分

    手机号验证码登录（首次登录自动注册），即赠 100 积分，约可生成 10 张标准图。

  2. 02

    创建 API Key

    进入「个人中心 → API KEYS」创建密钥。明文 qp_live_ 开头，仅创建时展示一次，请妥善保存。

  3. 03

    发起第一次生成

    调用 POST /api/v1/images/generations，202 立即返回任务 ID，异步出图后轮询取结果。

cURL · 第一张图
curl -X POST https://image.qiepai.ai/api/v1/images/generations \
  -H "Authorization: Bearer qp_live_你的密钥" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "一只立于涟漪之上的青鹭，水墨渐变，东方意境",
    "model": "seedream-lite",
    "size": "1024x1024",
    "n": 1
  }'
RESPONSE · 202 Accepted
{
  "ok": true,
  "data": {
    "generationId": "cmu7a81o70000itobr2z4qsnp",
    "status": "processing",
    "creditsFrozen": 10,
    "demo": false
  }
}

AUTHENTICATION

鉴权

开放 API 使用 Bearer Token 鉴权。密钥以 qp_live_ 开头，服务端只存 SHA-256 哈希，明文仅创建时返回一次。密钥与账号共享积分账本，默认权限域 images:generate。

REQUEST HEADER
Authorization: Bearer qp_live_a1b2c3d4e5f6…
ITEM说明
密钥前缀qp_live_ + 48 位随机 hex，展示用前缀为前 16 字符
存储方式SHA-256 哈希落库，服务端不留存明文
权限域scopes 逗号分隔，当前开放 images:generate
吊销个人中心 → API KEYS 可随时吊销，立即生效

请勿把密钥提交进代码仓库或前端 bundle。泄露后请立即吊销并新建。

IMAGES / GENERATIONS

文生图接口

POST/api/v1/images/generations

提交即落库并冻结积分，202 立即返回任务 ID，出图在后台异步执行。生成不成功，冻结积分自动解冻退回。

PARAM类型必填说明
promptstring是画面描述，上限 1000 字符
modelstring否seedream-lite（默认）/ seedream-pro / gpt-image-2.5
sizestring否1024x1024（默认）/ 1152x1536 / 1536x1152 / 1920x1080 / 1080x1920
nnumber否生成张数 1–4，默认 1，按张数冻结积分
negativePromptstring否负向提示词：不希望出现的元素
RESPONSE · 202 Accepted
{
  "ok": true,
  "data": {
    "generationId": "cmu7a…",   // 任务 ID，轮询用
    "status": "processing",     // 已受理，后台渲染中
    "creditsFrozen": 10,        // 本次冻结积分（成功后实扣）
    "demo": false               // true = 演示模式（未配置引擎 key）
  }
}

演示模式：未配置引擎密钥时全链路走 picsum 占位图，计费流程真实走通，便于联调。

TASK POLLING

任务查询

GET/api/v1/images/generations/{generationId}

ApiKey 独立轮询端点：与提交任务使用同一把 Bearer key鉴权，仅返回由该 key 创建的任务（他人任务与站内会话任务一律 404，不暴露存在性）。 返回形状与站内轮询完全一致。

任务状态机：queued ───→ rendering ───→ succeeded / failed。建议以 2 秒间隔轮询，直到 succeeded（取 images）或 failed（积分已自动退回）。

cURL · 轮询任务
curl https://image.qiepai.ai/api/v1/images/generations/cmu7a81o70000itobr2z4qsnp \
  -H "Authorization: Bearer qp_live_你的密钥"
RESPONSE · succeeded
{
  "ok": true,
  "data": {
    "id": "cmu7a…",
    "status": "succeeded",
    "model": "seedream-lite",
    "prompt": "一只立于涟漪之上的青鹭……",
    "images": ["/uploads/cmu7a…-f82fbbad8417.png"],
    "creditsCost": 10,
    "createdAt": "2026-09-18T09:30:00.000Z"
  }
}
ENDPOINT鉴权方式可见范围
GET /api/v1/images/generations/{id}Bearer ApiKey仅该 key 创建的任务
GET /api/generate/{id}站内登录会话仅当前账号的任务

出图统一落盘并叠加「AI生成」显式标识。两个端点共享同一任务状态机与返回形状，按集成方式二选一即可。

MCP SERVER

MCP 接入（Agent 直调）

POST/api/mcp

平台内置 MCP（Model Context Protocol）服务端：Kimi、Claude 等支持 MCP 的 Agent 配置后即可直接调用平台出图，无需手写 HTTP 集成。协议为最小 JSON-RPC 2.0 实现，支持 initialize / ping / tools/list / tools/call。鉴权复用 Bearer ApiKey（与账号共享积分账本）；未带密钥时 tools/list 仍可见，方便配置阶段调试签名，tools/call 返回 401。

TOOL参数返回
generate_imageprompt（必）/ model / size / ngenerationId + 轮询说明（异步，202 语义）
get_generationgenerationId（必）status；succeeded 时给绝对图片 URL（…/uploads/…）
JSON-RPC · initialize
curl -X POST https://image.qiepai.ai/api/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize"}'

# → {"jsonrpc":"2.0","id":1,"result":{
#     "protocolVersion":"2025-03-26",
#     "capabilities":{"tools":{"listChanged":false}},
#     "serverInfo":{"name":"qiepai-image","version":"1.0.0"} }}
JSON-RPC · tools/call（generate_image）
curl -X POST https://image.qiepai.ai/api/mcp \
  -H "Authorization: Bearer qp_live_你的密钥" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "generate_image",
      "arguments": { "prompt": "一只立于涟漪之上的青鹭，水墨渐变", "size": "1024x1024" }
    }
  }'
Agent 客户端配置示例（mcpServers）
{
  "mcpServers": {
    "qiepai-image": {
      "url": "https://image.qiepai.ai/api/mcp",
      "headers": { "Authorization": "Bearer qp_live_你的密钥" }
    }
  }
}

get_generation 仅返回由同一把 ApiKey 创建的任务（他人与站内会话任务按不存在处理）。 生成的图片带「AI生成」显式标识，可在 Agent 对话中直接引用展示。

ERROR CODES

错误码

所有接口统一返回形状：成功 { ok: true, data }，失败 { ok: false, error }。

HTTP场景处理建议
400prompt 为空 / 超长（>1000）/ model 不支持 / 请求体非 JSON检查请求参数
401ApiKey 无效、已吊销或权限域不足重新创建密钥
402积分余额不足充值后重试，冻结不会发生
422提示词或生成图未通过内容审核调整描述后重试
500内部错误稍后重试；冻结积分会自动解冻
ERROR SHAPE
{
  "ok": false,
  "error": "prompt 超长（上限 1000 字符）"
}

CREDIT BILLING

积分计费

1 积分 ≈ 0.1 元。计费机制：提交冻结 → 成功实扣 → 失败自动解冻退回，以任务 ID 为幂等键，重复回调不会重复扣费。

ENGINE / 引擎SCENE / 场景CREDITS / 积分
Seedream 5.0 lite标准 1K 文生图10 积分 / 张
Seedream 5.0 lite2K 高分辨率15 积分 / 张
Seedream 5.0 pro精绘 / 海报级质感15–30 积分 / 张
GPT Image 2.5高端精编辑 / 复杂指令80–150 积分 / 张
任意引擎图生图（附加费）+10 积分 / 张
任意引擎高清放大至 4K+5 积分 / 张

多张开图按张数乘算。完整套餐与换算见 定价页。

COMPLIANCE

合规说明

企鹅派依据《人工智能生成合成内容标识办法》及配套国家标准 GB 45438-2025《人工智能生成合成内容标识方法》，对全部出图叠加「AI生成」显式标识，并在文件元数据中写入隐式标识，请勿去除。

  • ▸提示词与生成图均经过内容审核，违规内容将被拒绝且不计费
  • ▸禁止生成侵犯他人著作权、肖像权的内容，禁止违法违规用途
  • ▸生成内容的商用授权范围以《用户协议》为准
  • ▸通过 API 生成的内容同样计入账号审核记录，请妥善保管密钥

详见 《用户协议》 与 《隐私政策》。