Developer Documentation

用一个接口，
连接多种 AI 模型。

New API 提供兼容 OpenAI 格式的接口。只需修改请求地址和 API Key，即可将现有应用快速接入。

Base URL https://api.example.com/v1 格式 JSON 鉴权 Bearer Token

身份认证

所有 API 请求都需要在 HTTP 请求头中携带你的密钥。

HTTP Header

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

请妥善保管密钥。 不要把 API Key 写进浏览器端代码、公开仓库或聊天记录中，建议通过服务器环境变量读取。

快速开始

下面的请求会向指定模型发送一条消息，并返回模型生成的回答。

POST/v1/chat/completions

cURL

curl https://api.example.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [
      { "role": "user", "content": "你好，请介绍一下自己。" }
    ]
  }'

对话接口

创建一次模型对话补全。接口结构兼容常见的 OpenAI SDK。

请求参数

字段	类型	说明
`model` 必填	string	要调用的模型名称。
`messages` 必填	array	对话消息列表，包含 `role` 和 `content`。
`temperature`	number	控制回答随机性，通常为 0～2。
`max_tokens`	integer	限制本次回答最多生成的 Token 数。
`stream`	boolean	设为 `true` 时，以数据流形式逐步返回内容。

响应示例

JSON

{
  "id": "chatcmpl-123456",
  "object": "chat.completion",
  "created": 1720000000,
  "model": "gpt-4o-mini",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "你好！我是一个 AI 助手。"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 15,
    "total_tokens": 27
  }
}

文生图接口

根据文字提示词生成一张或多张图片。适合海报、插画、商品概念图和视觉素材生成。

POST/v1/images/generations

请求格式

请求体使用 application/json。鉴权方式与对话接口相同。

字段	类型	说明
`model` 必填	string	图片模型名称，例如 `gpt-image-1`。请以服务后台提供的模型列表为准。
`prompt` 必填	string	图片描述。建议写清主体、场景、构图、光线、色彩、画面风格和需要避免的内容。
`n`	integer	生成图片数量，通常默认为 `1`。不同模型可能限制最大数量。
`size`	string	输出尺寸，例如 `1024x1024`、`1536x1024` 或 `1024x1536`。可用值取决于模型。
`quality`	string	图片质量，例如 `auto`、`low`、`medium`、`high`。质量越高，通常耗时和费用越高。
`background`	string	背景模式，例如 `auto`、`opaque` 或 `transparent`。透明背景通常需要 PNG/WebP 格式和模型支持。
`output_format`	string	图片格式，例如 `png`、`jpeg` 或 `webp`。
`response_format`	string	返回方式：`url` 返回临时图片地址，`b64_json` 返回 Base64 数据。部分模型可能只支持其中一种。
`user`	string	可选的终端用户标识，用于审计、统计或风控，请勿填写敏感个人信息。

提示词建议：“主体 + 动作 + 环境 + 构图 + 光线 + 风格 + 色彩 + 细节限制”。例如：产品置于浅灰摄影棚，45° 俯拍，柔和侧光，极简商业摄影，不出现文字或水印。

JSON 请求示例

cURL · 文生图

curl https://api.example.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-1",
    "prompt": "一只橘猫坐在未来城市的屋顶，远处是霓虹灯，高角度构图，电影感光线，蓝紫色调，细节丰富，不要文字和水印",
    "n": 1,
    "size": "1024x1024",
    "quality": "high",
    "output_format": "png",
    "response_format": "b64_json"
  }'

JavaScript 示例

JavaScript · 保存 Base64 图片

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

const response = await fetch("https://api.example.com/v1/images/generations", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.NEW_API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    model: "gpt-image-1",
    prompt: "极简白色书桌上的机械键盘，柔和晨光，产品摄影",
    size: "1024x1024",
    quality: "high",
    response_format: "b64_json"
  })
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message || "图片生成失败");

const imageBase64 = result.data[0].b64_json;
await writeFile("generated.png", Buffer.from(imageBase64, "base64"));
console.log("图片已保存为 generated.png");

Python 示例

Python · 保存 Base64 图片

import os
import base64
import requests

response = requests.post(
    "https://api.example.com/v1/images/generations",
    headers={
        "Authorization": f"Bearer {os.environ['NEW_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "model": "gpt-image-1",
        "prompt": "极简白色书桌上的机械键盘，柔和晨光，产品摄影",
        "size": "1024x1024",
        "quality": "high",
        "response_format": "b64_json",
    },
    timeout=180,
)
response.raise_for_status()

image_base64 = response.json()["data"][0]["b64_json"]
with open("generated.png", "wb") as image_file:
    image_file.write(base64.b64decode(image_base64))

print("图片已保存为 generated.png")

响应示例

JSON · Base64 返回

{
  "created": 1720000000,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAAANSUhEUgAA...",
      "revised_prompt": "A detailed orange cat sitting..."
    }
  ],
  "usage": {
    "total_tokens": 1240,
    "input_tokens": 58,
    "output_tokens": 1182
  }
}

若使用 response_format: "url"，则读取 data[0].url。图片地址一般有有效期，收到后应及时下载并保存到自己的存储空间。

图生图接口

上传原图并通过文字描述进行重绘、修改或风格转换。请求需要使用表单上传，不能直接发送普通 JSON。

POST/v1/images/edits

请求格式

请求体使用 multipart/form-data。客户端会自动生成包含 boundary 的 Content-Type，手动设置可能导致服务器无法读取图片。

字段	类型	说明
`image` 必填	file / file[]	待编辑的原图。常见格式为 PNG、JPEG 或 WebP；文件大小和图片数量以服务限制为准。
`prompt` 必填	string	说明要保留和修改的内容。明确写出“保持人物姿势不变”等约束通常更稳定。
`model` 必填	string	支持图片编辑的模型名称，例如 `gpt-image-1`。
`mask`	file	可选蒙版。通常透明区域表示允许编辑的范围，具体规则以模型说明为准；尺寸应与原图一致。
`n`	integer	生成结果数量，通常默认为 `1`。
`size`	string	结果图片尺寸，例如 `1024x1024`。部分服务会保持原图比例。
`quality`	string	输出质量，例如 `auto`、`medium` 或 `high`。
`output_format`	string	结果格式，例如 `png`、`jpeg` 或 `webp`。
`response_format`	string	`url` 或 `b64_json`，是否可用取决于服务和模型。

图生图提示词建议：先写必须保留的内容，再写修改目标。例如：“保持人物面部、姿势和构图不变，把白天背景改为雨夜霓虹街道，增加地面倒影，不添加文字。”

cURL 示例

cURL · multipart/form-data

curl https://api.example.com/v1/images/edits \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "model=gpt-image-1" \
  -F "image=@./input.png" \
  -F "prompt=保持主体形状和构图不变，把背景改成日落海滩，暖色电影光线，不要文字" \
  -F "size=1024x1024" \
  -F "quality=high" \
  -F "response_format=b64_json"

JavaScript 示例

JavaScript · 上传并保存图片

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

const source = await readFile("input.png");
const form = new FormData();
form.append("model", "gpt-image-1");
form.append("image", new Blob([source], { type: "image/png" }), "input.png");
form.append("prompt", "保留主体和构图，把背景改为日落海滩，暖色电影光线");
form.append("size", "1024x1024");
form.append("quality", "high");
form.append("response_format", "b64_json");

const response = await fetch("https://api.example.com/v1/images/edits", {
  method: "POST",
  headers: { "Authorization": `Bearer ${process.env.NEW_API_KEY}` },
  body: form
});

const result = await response.json();
if (!response.ok) throw new Error(result.error?.message || "图片编辑失败");

await writeFile("edited.png", Buffer.from(result.data[0].b64_json, "base64"));
console.log("图片已保存为 edited.png");

注意：发送 FormData 时不要自行添加 Content-Type 请求头，运行环境会自动补全正确的 multipart boundary。

Python 示例

Python · 上传并保存图片

import os
import base64
import requests

with open("input.png", "rb") as source_image:
    response = requests.post(
        "https://api.example.com/v1/images/edits",
        headers={"Authorization": f"Bearer {os.environ['NEW_API_KEY']}"},
        files={"image": ("input.png", source_image, "image/png")},
        data={
            "model": "gpt-image-1",
            "prompt": "保留主体和构图，把背景改为日落海滩，暖色电影光线",
            "size": "1024x1024",
            "quality": "high",
            "response_format": "b64_json",
        },
        timeout=180,
    )

response.raise_for_status()
image_base64 = response.json()["data"][0]["b64_json"]
with open("edited.png", "wb") as output_image:
    output_image.write(base64.b64decode(image_base64))

print("图片已保存为 edited.png")

使用蒙版

如果服务支持局部编辑，可增加 mask 文件。原图和蒙版应使用相同宽高，并根据接口规定设置透明区域。

cURL · 局部重绘

curl https://api.example.com/v1/images/edits \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "model=gpt-image-1" \
  -F "image=@./input.png" \
  -F "mask=@./mask.png" \
  -F "prompt=只在蒙版区域增加一盆绿色植物，保持其他区域完全不变" \
  -F "response_format=b64_json"

常见问题

现象	原因与处理方式
返回 400	检查字段名、图片格式、文件大小、模型是否支持编辑，以及是否错误地手动设置了 multipart 请求头。
图片修改过多	提示词开头明确列出必须保留的主体、面部、姿势、构图和色彩。
蒙版没有生效	确认蒙版尺寸与原图一致，并核对服务对透明区和非透明区的定义。
请求超时	图片生成通常比文本请求慢，客户端超时建议设为 120～300 秒，并避免立即高频重试。
Base64 太大	及时解码写入图片文件，不要长期把完整 Base64 字符串保存在日志或数据库文本字段中。

代码示例

JavaScript

const response = await fetch("https://api.example.com/v1/chat/completions", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.NEW_API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    model: "gpt-4o-mini",
    messages: [{ role: "user", content: "你好！" }]
  })
});

const data = await response.json();
console.log(data.choices[0].message.content);

Python

import os
import requests

response = requests.post(
    "https://api.example.com/v1/chat/completions",
    headers={
        "Authorization": f"Bearer {os.environ['NEW_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "model": "gpt-4o-mini",
        "messages": [{"role": "user", "content": "你好！"}],
    },
)

response.raise_for_status()
print(response.json()["choices"][0]["message"]["content"])

错误码

请求失败时，服务会返回对应的 HTTP 状态码和 JSON 错误信息。

状态码	含义	处理建议
400	请求参数错误	检查 JSON 格式、模型名称和必填字段。
401	认证失败	确认 API Key 正确且未过期。
429	请求过于频繁	降低请求频率，并使用指数退避重试。
500	服务器内部错误	稍后重试；持续出现时联系服务管理员。
200	请求成功	正常读取响应中的 `choices` 数据。

错误响应

{
  "error": {
    "message": "Invalid API key",
    "type": "authentication_error",
    "code": "invalid_api_key"
  }
}

用一个接口，连接多种 AI 模型。

身份认证

快速开始

对话接口

请求参数

响应示例

文生图接口

请求格式

JSON 请求示例

JavaScript 示例

Python 示例

响应示例

图生图接口

请求格式

cURL 示例

JavaScript 示例

Python 示例

使用蒙版

常见问题

代码示例

JavaScript

Python

错误码

用一个接口，
连接多种 AI 模型。