登录控制台
打开 www.unikeyx.com，进入控制台。
Quick start
三步完成接入
创建 API Key
在令牌页面创建一个新的 Key。妥善保存，后续示例都使用它作为 Bearer Token。
替换 Base URL
把 OpenAI SDK 或兼容客户端的 base_url 改成 https://www.unikeyx.com/v1。
模型名提示
示例使用常用模型名。若控制台模型列表显示了不同别名，请以控制台可见模型名为准。
Copy-ready samples
通用 SDK 初始化
Python
from openai import OpenAI
client = OpenAI(
api_key="YOUR_UNIKEYX_API_KEY",
base_url="https://www.unikeyx.com/v1",
)
JavaScript
import OpenAI from "openai";
const client = new OpenAI({
apiKey: process.env.UNIKEYX_API_KEY,
baseURL: "https://www.unikeyx.com/v1",
});Image generation and editing
MAI 生图/改图与 GPT 生图/改图
MAI 生图：生成商品海报
适合中文提示词、运营物料、商品图和海报草图。MAI 官方接口使用 width 和 height 指定尺寸，输出图片通常在 b64_json 中返回。
curl
curl https://www.unikeyx.com/v1/images/generations \
-H "Authorization: Bearer YOUR_UNIKEYX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "MAI-Image-2",
"prompt": "一张高端咖啡豆礼盒的中文电商主图，白色背景，柔和棚拍光，真实产品摄影风格",
"width": 1024,
"height": 1024
}'GPT 生图：生成插画视觉
适合需要严格遵循英文或中英文混合提示词的场景。Azure/OpenAI 图片接口常见返回字段是 b64_json，客户端应解码后保存为图片文件。
Python
import base64
from openai import OpenAI
client = OpenAI(
api_key="YOUR_UNIKEYX_API_KEY",
base_url="https://www.unikeyx.com/v1",
)
result = client.images.generate(
model="gpt-image-2",
prompt="A clean editorial illustration of a small AI API gateway, with clear labels and modern product UI details.",
size="1024x1024",
quality="high",
n=1,
)
image_base64 = result.data[0].b64_json
with open("gpt-image-2-output.png", "wb") as file:
file.write(base64.b64decode(image_base64))MAI 改图：参考图生成运营海报
适合上传商品图、人物图或风格参考图后做二次创作。MAI-Image-2.5 官方改图接口使用 multipart form data，参考图必须是 PNG 或 JPEG。
curl
curl -sS https://www.unikeyx.com/v1/images/edits \
-H "Authorization: Bearer YOUR_UNIKEYX_API_KEY" \
-F "model=MAI-Image-2.5" \
-F "prompt=保留商品主体，替换为夏季户外露营场景，加入中文标题：清爽上新，真实商业摄影风格" \
-F "image=@./product-reference.png" \
| jq -r '.data[0].b64_json' \
| base64 --decode > mai-image-2-5-edit.pngGPT 改图：单图编辑
适合用一张主图做局部重绘、风格调整和商品图优化。示例不传 response_format，直接解码 b64_json 保存结果。
Python
import base64
from openai import OpenAI
client = OpenAI(
api_key="YOUR_UNIKEYX_API_KEY",
base_url="https://www.unikeyx.com/v1",
)
with open("product-reference.png", "rb") as image_file:
result = client.images.edit(
model="gpt-image-2",
image=image_file,
prompt="Keep the product shape and logo readable. Rebuild the scene as a premium e-commerce hero image with soft studio lighting and a clean background.",
size="1024x1024",
quality="high",
)
image_base64 = result.data[0].b64_json
with open("gpt-image-2-edit.png", "wb") as file:
file.write(base64.b64decode(image_base64))Chat completion
GPT-5.6 与 Claude Sonnet 5 调用
GPT-5.6：结构化摘要
用于复杂推理、长文本整理和高质量中文输出。示例使用 Chat Completions 兼容格式。
JavaScript
import OpenAI from "openai";
const client = new OpenAI({
apiKey: process.env.UNIKEYX_API_KEY,
baseURL: "https://www.unikeyx.com/v1",
});
const completion = await client.chat.completions.create({
model: "gpt-5.6",
messages: [
{ role: "system", content: "你是一个严谨的中文技术文档助手。" },
{
role: "user",
content: "把 UniKeyX 的 API 接入流程总结成 3 个步骤，并给出注意事项。",
},
],
temperature: 0.3,
});
console.log(completion.choices[0].message.content);Claude Sonnet 5：审阅与改写
用于文档审阅、代码解释、客服回复和风格化改写。通过 UniKeyX 仍使用同一个 OpenAI-compatible 入口。
curl
curl https://www.unikeyx.com/v1/chat/completions \
-H "Authorization: Bearer YOUR_UNIKEYX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "claude-sonnet-5",
"messages": [
{
"role": "system",
"content": "你是一个负责审阅 API 文档的资深工程师。"
},
{
"role": "user",
"content": "请把这段说明改写得更清晰：先创建令牌，然后把 base_url 改为 UniKeyX。"
}
],
"temperature": 0.2
}'Troubleshooting
常见问题
401 unauthorized
检查 API Key 是否复制完整，Header 是否为 Authorization: Bearer YOUR_UNIKEYX_API_KEY。
模型不存在或无权限
打开控制台确认当前令牌所属分组是否允许使用该模型。必要时把示例模型名替换为控制台显示的模型名。
gpt-image-2 的 size 应该怎么填？
gpt-image-2 使用 OpenAI 兼容的 size 字符串，格式为
宽x高，例如 1024x1024。推荐优先使用这些稳定预设：
1024x1024、1024x1536、1536x1024、
2048x2048、3840x2160、2160x3840。
- 方图：
1024x1024，适合商品主图、头像、通用插画。 - 竖图：
1024x1536或2160x3840，适合海报、封面、人像。 - 横图：
1536x1024或3840x2160，适合 banner、封面、场景图。 - 自定义尺寸时，宽高都必须能被 16 整除，宽高比例建议保持在
1:3到3:1之间。 - 超大尺寸更慢，也更容易因为上游限制失败；不确定时先用
1024x1024验证提示词。
gpt-image-2 的 quality 应该怎么填？
gpt-image-2 支持 quality，常用值为
auto、low、medium、high。
不传时可按 auto 理解。
auto：默认选择，适合大多数业务接入。low：速度优先、成本优先，适合草图、预览、批量试 prompt。medium：质量和速度折中，适合常规运营图。high：质量优先，适合最终出图、商品图、品牌海报，但耗时和成本通常更高。
MAI-Image-2 的尺寸应该怎么填？
MAI-Image-2 官方生图参数是 width 和 height，
不是 size: "1024x1024"。在 UniKeyX 文档示例里，推荐直接传
"width": 1024、"height": 1024 这样的整数。
- 方图：
"width": 1024、"height": 1024。 - 横图：
"width": 1024、"height": 768。 - 竖图：
"width": 768、"height": 1024。 - 宽屏横图：
"width": 1365、"height": 768。 - 竖屏海报：
"width": 768、"height": 1365。
MAI-Image-2 的 quality 应该怎么填？
MAI-Image-2 当前不建议传 quality 参数。
如果从 gpt-image-2 示例复制代码，请删除
quality: "high"、quality: "medium" 等字段。
想提升 MAI 出图效果，优先优化提示词：明确主体、画面风格、构图、光线、背景、文字内容和用途，而不是依赖 quality。
MAI-Image-2.5 的尺寸应该怎么填？
MAI-Image-2.5 可用于参考图改图。纯生图时同样使用
width 和 height；参考图改图时，优先只传
model、prompt、image。
- 生图方图：
"width": 1024、"height": 1024。 - 生图横图：
"width": 1024、"height": 768或"width": 1365、"height": 768。 - 生图竖图：
"width": 768、"height": 1024或"width": 768、"height": 1365。 - 改图请求不要传
size、quality、n，先按官方 multipart 写法只传必要字段。 - MAI-Image-2.5 编辑参考图必须使用 PNG 或 JPEG；目前按一张参考图排查最稳定。
MAI-Image-2.5 的 quality 应该怎么填？
MAI-Image-2.5 当前不建议传 quality 参数，尤其是图片编辑请求。
从 GPT 图片示例迁移时，请删除 quality 字段，只保留
model、prompt 和 image 等必要字段。
改图质量主要受参考图清晰度和提示词影响。建议上传清晰、未损坏、非压缩过度的 PNG/JPEG，并在提示词里说明保留什么、替换什么、最终用途是什么。
400: Invalid size，宽高必须都能被 16 整除
例如报错 status_code=400, Invalid size '568x1024'. Width and height must both be divisible by 16.
表示图片尺寸不合法。这里 1024 可以被 16 整除，但 568 不能。
使用 gpt-image-2 或兼容图片模型时，建议遵守这些规则：
- 宽度和高度都使用 16 的倍数，例如
576、768、1024、1536。 - 方图建议用
1024x1024，适合头像、商品主图、通用插画。 - 竖图建议用
768x1024或1024x1536，适合海报、小红书封面、人物图。 - 横图建议用
1024x768或1536x1024，适合 banner、封面图、场景图。 - 接近 9:16 的竖版可以用
576x1024，不要用568x1024。 - 接近 16:9 的横版可以用
1024x576。
常见修正方式：568x1024 改为 576x1024；
1024x568 改为 1024x576。
如果不确定尺寸，优先使用 1024x1024。
400: gpt-image-2 图片编辑报 Unknown parameter: 'response_format'
例如调用 /v1/images/edits 时返回
status_code=400, Unknown parameter: 'response_format'.
表示请求体里带了上游不支持的参数。这个错误通常不是额度或鉴权问题，而是参数校验失败。
- 使用
gpt-image-2做图片编辑时，不要传response_format。 - 如果代码从旧的 DALL-E 或图片接口示例迁移而来，检查 SDK、封装层或中间件是否自动补了
response_format: "url"或response_format: "b64_json"。 - 保留必要参数：
model、prompt、image；需要局部编辑时再传mask；尺寸使用上一条 FAQ 里符合规则的size。 - 客户端不要强依赖某一种返回格式，按实际响应兼容
url、b64_json或平台返回的图片字段。
推荐处理方式：删除 response_format 后重试。如果仍然返回 400，再检查是否还有其它旧版参数、拼写错误或不被当前模型支持的字段。
400: 图片编辑报 Invalid image file or mode for image 2
例如调用 /v1/images/edits 时返回
status_code=400, Invalid image file or mode for image 2, please check your image file.
表示第 2 张输入图无法被上游识别或图片模式不被支持。这里的 image 2
通常指请求里第二个 image 文件，而不是生成结果的第 2 张图。
- 先只保留一张图调用；如果单图成功，再逐张加入参考图，定位是哪一张文件触发错误。
gpt-image-2编辑输入建议使用png、jpg/jpeg或webp。MAI-Image-2.5编辑输入按官方文档使用 PNG 或 JPEG，不要传 WebP、HEIC、AVIF、GIF、PDF、PSD 或损坏文件。- 大文件、相机原图、超大 PNG、带异常元数据的图片建议重新导出后再传。
- 如果图片是 CMYK、16-bit、索引色、带特殊色彩配置或动画图，建议先转成普通
RGB或RGBA的 PNG/JPEG/WebP。 - 使用标准
multipart/form-data上传真实文件内容，不要把本地路径、过期 URL 或未按接口约定处理的 base64 字符串当作image传入。 - 如果同时传
mask，mask应是有效 PNG，尺寸与第一张输入图一致，并通过透明区域表示需要编辑的位置。
推荐处理方式：把报错里的第 2 张图重新导出为普通 RGB PNG 或 RGB JPEG，
确认文件能正常打开、大小合规，再重新请求。若仍失败，把多图请求拆成单图请求逐个排查。
400: gpt-image-2 生图被 safety system 拒绝，safety_violations=[sexual]
例如报错 status_code=400, Your request was rejected by the safety system... safety_violations=[sexual].
表示上游安全系统判断这次生图请求可能涉及性相关内容，因此拒绝生成。错误里的 request ID
只用于排查这一次请求，不代表可以绕过安全策略。
- 检查提示词中是否包含露骨身体描述、性暗示、成人内容、挑逗姿势、透明/暴露服装等词。
- 如果是人物图，尽量写成普通肖像、时装摄影、职业形象、生活方式照片，避免强调身体部位或性感表达。
- 如果上传了参考图，参考图本身也可能触发安全拒绝；请更换为合规、非暴露、非性暗示的参考图。
- 不要使用“未成年”“校园”“少女”等容易和敏感场景组合的描述来生成暧昧或性感图片。
- 把需求改写成明确的非性化表达，例如“优雅的品牌大片”“自然站姿”“日常穿搭”“商业人像”。
推荐处理方式：先删除可能触发的词，再用中性、商业、摄影风格的描述重试。若你确认内容完全合规，可以保留错误里的 request ID，联系平台支持排查，但最终是否放行取决于上游安全系统。
图片返回 base64 而不是 URL
不同上游和通道配置可能返回不同图片字段。客户端建议同时兼容 url 和 b64_json。
OpenAI SDK 报 baseURL 或 base_url 错误
Python SDK 使用 base_url，JavaScript SDK 使用 baseURL。
References