文档

通过 MCP 或 API 接入 Pixly。

开始之前

注册一个 Pixly 账户(注册即送 100 积分)。
在 API 密钥页面获取你的 API Key。

基础配置

所有接口与 OpenAI 图像 API 兼容,使用 Bearer 鉴权。

Base URL:  https://api.genframeai.com
Header:    Authorization: Bearer <YOUR_API_KEY>

可用模型

当前已启用的模型:

模型 ID	渠道	积分 / 张
gemini-2.5-flash-image	google	5

文生图

POST /v1/images/generations

参数	类型	说明
model	string	模型 ID(见上表),必填
prompt	string	提示词,必填
size	string	如 1024x1024,默认 1024x1024
n	number	生成张数,默认 1

curl https://api.genframeai.com/v1/images/generations \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-2.5-flash-image",
    "prompt": "a serene mountain lake at dawn",
    "size": "1024x1024",
    "n": 1
  }'

响应:

{
  "created": 1718352000,
  "data": [
    { "url": "https://.../image.png" }
  ]
}

图生图 / 编辑

POST /v1/images/edits (multipart/form-data,字段 image 为原图)

curl https://api.genframeai.com/v1/images/edits \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -F model="gemini-2.5-flash-image" \
  -F prompt="replace the background with snowy mountains" \
  -F size="1024x1024" \
  -F image=@./source.png

SDK 示例

因为接口与 OpenAI 图像 API 兼容,任意 OpenAI SDK 只要把 base URL 指向 Pixly 即可直接使用。

Python(openai)

from openai import OpenAI

client = OpenAI(
    api_key="<YOUR_API_KEY>",
    base_url="https://api.genframeai.com/v1",
)

# text to image
res = client.images.generate(
    model="gemini-2.5-flash-image",
    prompt="a serene mountain lake at dawn",
    size="1024x1024",
)
print(res.data[0].url)

# image to image / edit
edit = client.images.edit(
    model="gemini-2.5-flash-image",
    prompt="replace the background with snowy mountains",
    image=open("source.png", "rb"),
    size="1024x1024",
)
print(edit.data[0].url)

Node.js(openai)

import OpenAI from "openai";
import fs from "node:fs";

const client = new OpenAI({
  apiKey: "<YOUR_API_KEY>",
  baseURL: "https://api.genframeai.com/v1",
});

// text to image
const res = await client.images.generate({
  model: "gemini-2.5-flash-image",
  prompt: "a serene mountain lake at dawn",
  size: "1024x1024",
});
console.log(res.data[0].url);

// image to image / edit
const edit = await client.images.edit({
  model: "gemini-2.5-flash-image",
  prompt: "replace the background with snowy mountains",
  image: fs.createReadStream("source.png"),
  size: "1024x1024",
});
console.log(edit.data[0].url);

注意:base URL 必须包含 /v1。响应中 data[].url 为图片地址(部分模型返回 b64_json)。

计费与积分

调用按积分计费,从账户余额中扣除。
gemini-2.5-flash-image 为 5 积分/张;以账户实际扣费为准。
图片生成成功后会扣除对应积分。
余额不足时返回 402。可在价格页面充值。

限流

每个 API Key 都有速率限制。触发时返回 HTTP 429,请按指数退避重试。

错误码

状态码	含义
400	请求参数错误(缺少 model 或 prompt 等)
401	API Key 缺失或无效
402	积分不足
429	触发限流,请稍后重试
500	服务端错误

错误响应格式:

{ "error": { "message": "insufficient credits", "type": "invalid_request_error" } }

MCP 接入

Pixly 提供 Streamable HTTP MCP 服务。在 Cherry Studio / ChatWise / Claude 等客户端添加如下配置,用自然语言即可生图。

{
  "mcpServers": {
    "pixly": {
      "type": "streamableHttp",
      "url": "https://mcp.genframeai.com/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_API_KEY>"
      }
    }
  }
}

工具	说明
text_to_image	文生图,可选 style 预设(支持风格库 id)与 size
search_styles	按关键词 / 标签搜索约 1 万条风格预设,返回可用的 style id
image_to_image	按指令改写一张图(给定 URL)
upscale	放大 / 增强细节
remove_background	抠图,去除背景