创元智境 NewAPI 新手接入文档

本页介绍如何把 Claude Code、Codex CLI、OpenClaw、WorkBuddy、CC Switch、Magpie、Cherry Studio 等工具,以及你自己的项目代码接入创元智境 AI 网关,并说明对话、编程和生图模型的使用方法。你只需要完成三件事:获取 API Key(选好分组)、填对 Base URL、验证请求是否成功。

一句话说明:创元智境提供稳定的 AI API 网关服务。你可以把原本调用官方 API 的工具,改成调用创元智境地址。多数 OpenAI 兼容工具只需要修改 base_url 和 api_key。

最重要的地址

Claude Code / Anthropic 格式
Anthropic API Base URL
https://chuangyuan.org
环境变量:ANTHROPIC_BASE_URL。注意:这里不带 /v1。
Codex CLI / OpenAI 兼容工具
OpenAI API Base URL
https://chuangyuan.org/v1
填在工具或 SDK 的 Base URL 配置项中。注意:这里必须带 /v1。
新手最容易错的地方:Claude Code 地址不带 /v1;Codex、OpenClaw、OpenAI SDK 地址带 /v1。如果填反,通常会出现 404、Connection refused 或工具无法识别模型。

生图等耗时较长的请求,请改用多模态地址 https://api.chuangyuan.org,详见 选择正确地址。

新手快速开始

如果你第一次使用 API 网关,按下面 6 步做即可。不要跳过第 6 步"验证",否则后面排错会很麻烦。

1

注册账号

在控制台注册并登录。

2

获取 API Key

新建 API Key 时选择分组,并妥善保存。

3

确认分组与余额

确认 Key 的分组里有你要用的模型,并且账号有可用余额。

4

选择工具

Claude Code 用 Anthropic 地址;Codex/OpenClaw 用 OpenAI 地址。

5

复制配置命令

把 sk-your-api-key 替换成你的真实 Key。

6

验证请求

运行工具或 curl 测试,确认能正常返回结果。

API Key 是你的调用凭证。不要把 Key 发给别人,不要截图公开,不要写进前端网页代码,不要提交到 GitHub。Key 泄露后,别人可能消耗你的余额。

不知道自己该看哪一节?

你要做什么 阅读章节 Base URL
在终端里使用 Claude Code Claude Code 配置 https://chuangyuan.org
使用 OpenAI Codex CLI Codex CLI 配置 https://chuangyuan.org/v1
使用 OpenClaw 客户端 OpenClaw 配置 https://chuangyuan.org/v1
使用腾讯 WorkBuddy WorkBuddy 配置 https://chuangyuan.org/v1/chat/completions
想用图形界面一键配置 Claude Code / Codex CC Switch 或 Magpie 按工具自动区分
用桌面客户端聊天、对比模型 Cherry Studio 配置 https://chuangyuan.org
在自己的项目里写代码调用 代码接入 https://chuangyuan.org/v1

获取 API Key

API Key 是你调用接口时使用的密钥。所有工具都需要填写它。

  1. 打开控制台:https://chuangyuan.org/console。
  2. 注册或登录账号。
  3. 进入 令牌 / API Key / Token 页面。
  4. 点击 新建令牌,建议命名为具体用途,例如 claude-code-mac、codex-laptop。
  5. 选择分组。分组决定这个 Key 能用哪些模型,例如 Claude Code 选 claude,Codex 选 GPT-PRO稳定,生图选 GPT-Image。不知道选哪个,见 分组选择。
  6. 复制生成的 Key。格式通常类似 sk-xxxxxxxx。
  7. 回到本文档,把命令里的 sk-your-api-key 替换成你的真实 Key。
建议:不同工具使用不同 Key。比如 Claude Code 一个 Key、Codex 一个 Key。这样如果某个工具异常消耗,可以单独禁用对应 Key。

选择正确地址

不同工具使用的协议格式不同,因此 Base URL 不一样。你只要记住下表即可。

工具 / 场景 环境变量 正确地址 是否带 /v1
Claude Code ANTHROPIC_BASE_URL https://chuangyuan.org 不带
Codex CLI config.toml 里的 base_url https://chuangyuan.org/v1 带
OpenClaw 界面内填写 API Base URL https://chuangyuan.org/v1 带
WorkBuddy 界面内"接口地址" https://chuangyuan.org/v1/chat/completions 带,且要写完整路径
CC Switch / Magpie(Claude Code) 界面内 Base URL https://chuangyuan.org 不带
CC Switch / Magpie(Codex) 界面内 Base URL https://chuangyuan.org/v1 带
Cherry Studio 界面内"API 地址" https://chuangyuan.org 不带(客户端自动拼接)
OpenAI SDK 代码里的 baseURL / base_url https://chuangyuan.org/v1 带

长耗时请求请用多模态地址

除了主地址,我们还提供一个专门给长耗时请求用的地址。两者用法完全一样,只是域名不同:

常规请求
主地址
https://chuangyuan.org
对话、编程、Claude Code、Codex 等绝大多数场景。
多模态 / 长耗时请求
多模态地址
https://api.chuangyuan.org
生图、图像编辑、超长输出等可能超过 120 秒的请求。OpenAI 格式同样要加 /v1。
为什么要分两个地址?主地址对单个请求有约 120 秒的超时限制,超过后连接会被断开,客户端会看到 524 或超时报错。生图(尤其是 2K/4K、高质量)经常要 30–120 秒,所以生图请一律使用 https://api.chuangyuan.org/v1。

验证配置

不管用哪个工具,配置完成后都建议先做一次最小测试:确认环境变量已生效,再用 curl 直接调一次接口。curl 能通,说明 Key 和地址都没问题;如果某个工具还是不行,问题就出在工具自己的配置上。

检查环境变量是否存在

macOS / Linux

echo $ANTHROPIC_BASE_URL
echo $ANTHROPIC_API_KEY
echo $OPENAI_API_KEY

Windows PowerShell

echo $env:ANTHROPIC_BASE_URL
echo $env:ANTHROPIC_API_KEY
echo $env:OPENAI_API_KEY

OpenAI 兼容 curl 测试

curl https://chuangyuan.org/v1/chat/completions \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-6-sol",
    "messages": [
      {"role": "user", "content": "请用一句话回答:API 是否连接成功?"}
    ]
  }'

把 gpt-6-sol 换成你这个 Key 所在分组里有的模型,例如 Claude 分组用 claude-sonnet-5-5,国产模型分组用 deepseek-v4.1-flash。

成功结果应该是什么样?

如果成功,你会看到一段 JSON 返回,其中一般包含:

提示:如果 curl 能成功,但某个客户端不能成功,通常是客户端里的 Base URL、模型名或 API Key 没填对。

分组说明

创元智境把模型按来源和稳定性分成若干个分组。同一个模型名(比如 gpt-6-sol)可能同时出现在好几个分组里,区别在于背后的号池、稳定性和价格。

记住三句话就够了:

  1. 分组绑定在 API Key(令牌)上。新建令牌时选择分组,这个 Key 发出的所有请求都走这个分组。
  2. 模型名决定用哪个模型,分组决定走哪个号池、按什么价格。同一个模型,在不同分组里价格可能不同。
  3. 想同时用不同分组,就建多个 Key。比如一个 Key 选 GPT-PRO稳定 给 Codex 用,另一个 Key 选 GPT-Image 给生图用。
价格在哪看:各分组、各模型的实时价格请在 模型广场 查看,本文只介绍怎么使用。

自动分组(auto)

新建令牌时如果选择 auto,系统会在 GPT-PRO稳定、GPT-Plus、GPT-PRO企业级 这几个 GPT 分组之间自动选择和故障切换:一个分组出问题时,请求会自动转到另一个分组重试。适合"只想稳定用 GPT、不想关心号池"的用户。

注意:auto 只覆盖上面几个 GPT 编程分组,不包含 Claude、Gemini、国产模型和生图分组。要用这些模型,请单独建对应分组的 Key。

模型总览

目前提供的模型大致分为下面几类。每一类适合的工具和接口不同,下一节会细讲。

GPT / Codex 编程模型

gpt-6-sol、gpt-6.1-sol、gpt-6-astra、gpt-6-luna、gpt-5.6-sol 等。

写代码、做 Agent、Codex CLI / Codex App 首选。

OpenAI 格式Codex 推荐

Claude 模型

claude-opus-5-5、claude-sonnet-5-5、claude-opus-5、claude-sonnet-5、claude-haiku-5-5、claude-fable-5-1 等。

Claude Code 用户直接接入,长上下文、编程能力强。

Anthropic 格式Claude Code 推荐

Gemini 对话模型

gemini-3.8-flash、gemini-3.7-flash、gemini-3.6-flash、gemini-3.5-flash。

速度快、性价比高,适合批量文本处理。

OpenAI 格式

国产模型

DeepSeek、GLM、Kimi、Qwen、MiniMax、MiMo、混元等主流国产模型。

中文能力好、价格低,适合日常对话和编程辅助。

OpenAI 格式

Grok 模型

grok-4.7、grok-4.6、grok-4.5 等对话模型,以及 Grok 生图、生视频模型。

OpenAI 格式

生图模型

GPT 生图(gpt-image-2、gpt-image-2.5 系列)、Gemini 生图(Nano Banana)、Grok 生图。

见 生图分组选择。

按张计费用多模态地址

分组选择

你的情况 推荐分组 推荐模型
个人用 Codex 写代码,要稳定 GPT-PRO稳定 或 auto gpt-6-sol
预算有限,能接受偶尔不可用 GPT-Plus / GPT-特价组 gpt-6-sol
团队或生产环境,高并发 GPT-PRO企业级 按业务选
用 Claude Code claude(要 Fable / Haiku 选 claude-max) claude-sonnet-5-5 / claude-opus-5-5
中文对话、便宜好用 A01国产模型(全部主流国模) deepseek-v4.1-flash / glm-5.3 / kimi-k3
商用生图,要画质 GPT-Image,要更稳选 GPT-Image-Premium gpt-image-2
大批量生图,预算优先 GPT-Image-SR gpt-image-2
改图、换背景、保持人物一致 Gemini-Image gemini-nano-banana-2.1

接口说明

不同模型支持的接口格式不同。选错接口通常会报 404 或"模型不支持该接口"。

模型类型 推荐接口
GPT / Codex 编程模型 POST /v1/responses
Claude 模型 POST /v1/messages(Anthropic 格式)
Gemini / 国产 / Grok 对话 POST /v1/chat/completions
GPT 生图、Grok 生图 POST /v1/images/generations、POST /v1/images/edits
Gemini 生图 POST /v1beta/models/{model}:generateContent(Gemini 原生格式)
查询当前 Key 可用的模型 GET /v1/models

查看自己的 Key 能用哪些模型

模型列表跟着 Key 的分组走。用下面的命令可以直接列出来:

curl https://chuangyuan.org/v1/models \
  -H "Authorization: Bearer sk-your-api-key"

返回结果里 data[].id 就是可以填进 model 参数的完整模型名。

Claude Code 配置

Claude Code 适合在终端里做代码编辑、文件分析和项目辅助。配置时使用 ANTHROPIC_BASE_URL 和 ANTHROPIC_API_KEY。

第 1 步:确认 Node.js 已安装

Claude Code 需要 Node.js。先在终端输入:

node -v
npm -v

如果能看到版本号,例如 v18、v20、v22,说明已安装。没有版本号请先到 Node.js 官网 安装 LTS 版本。

第 2 步:安装 Claude Code

npm install -g @anthropic-ai/claude-code

第 3 步:临时配置环境变量

临时配置只在当前终端窗口有效,适合先测试。

export ANTHROPIC_BASE_URL=https://chuangyuan.org
export ANTHROPIC_API_KEY=sk-your-api-key

请把 sk-your-api-key 换成你在控制台生成的真实 Key。不要保留示例值。

第 4 步:启动 Claude Code

claude

如果正常进入 Claude Code 界面,说明配置基本成功。

第 5 步:持久化配置

如果你不想每次打开终端都重新输入环境变量,可以写入 Shell 配置文件。

macOS / Linux:先确认你使用的是 Zsh 还是 Bash

echo $SHELL

如果输出包含 zsh,使用 Zsh 命令;如果输出包含 bash,使用 Bash 命令。

Zsh 用户

echo 'export ANTHROPIC_BASE_URL=https://chuangyuan.org' >> ~/.zshrc
echo 'export ANTHROPIC_API_KEY=sk-your-api-key' >> ~/.zshrc
source ~/.zshrc

Bash 用户

echo 'export ANTHROPIC_BASE_URL=https://chuangyuan.org' >> ~/.bashrc
echo 'export ANTHROPIC_API_KEY=sk-your-api-key' >> ~/.bashrc
source ~/.bashrc

Windows PowerShell 临时配置

$env:ANTHROPIC_BASE_URL="https://chuangyuan.org"
$env:ANTHROPIC_API_KEY="sk-your-api-key"

Windows PowerShell 持久化配置

[Environment]::SetEnvironmentVariable("ANTHROPIC_BASE_URL", "https://chuangyuan.org", "User")
[Environment]::SetEnvironmentVariable("ANTHROPIC_API_KEY", "sk-your-api-key", "User")

Windows 持久化后需要关闭当前终端,重新打开 PowerShell 才能生效。

第 6 步:指定模型(可选)

Claude Code 默认会使用它自己内置的模型名。如果你想固定某个模型,可以额外设置:

export ANTHROPIC_MODEL=claude-sonnet-5-5
export ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-5-5

也可以在 Claude Code 里输入 /model 临时切换。

Key 的分组要对:Claude Code 用的 Key 必须选 claude 或 claude-max 分组。用 GPT 分组的 Key 会报"模型不存在"。另外 claude-haiku-5-5 只在 claude-max 分组里,用 claude 分组时,请把 ANTHROPIC_DEFAULT_HAIKU_MODEL 设为 claude-sonnet-5-5。

Codex CLI 配置

Codex CLI 使用 OpenAI 兼容格式,通过 config.toml 配置服务商,地址需要带 /v1。Key 请选 GPT 分组(如 GPT-PRO稳定 或 auto)。

第 1 步:确认 Node.js 已安装

node -v
npm -v

没有版本号请先到 Node.js 官网 安装 LTS 版本。

第 2 步:安装 Codex CLI

npm install -g @openai/codex

第 3 步:设置 API Key 环境变量

Zsh 用户

echo 'export OPENAI_API_KEY=sk-your-api-key' >> ~/.zshrc
source ~/.zshrc

Bash 用户

echo 'export OPENAI_API_KEY=sk-your-api-key' >> ~/.bashrc
source ~/.bashrc

Windows PowerShell

[Environment]::SetEnvironmentVariable("OPENAI_API_KEY", "sk-your-api-key", "User")

Windows 设置后需要关闭当前终端,重新打开 PowerShell 才能生效。

第 4 步:编写 config.toml

配置文件位置:

model = "gpt-6-sol"
review_model = "gpt-6-sol"
model_provider = "chuangyuan"

[model_providers.chuangyuan]
name = "创元智境"
base_url = "https://chuangyuan.org/v1"
env_key = "OPENAI_API_KEY"
wire_api = "responses"

第 5 步:启动 Codex

codex

Codex App 用户重新打开应用即可读取同一份配置。

模型怎么选:gpt-6-sol 日常编程首选;gpt-6-astra 能力最强、适合复杂任务(需要较新版本的 Codex);codex-auto-review 用于代码审查。

OpenClaw 配置

OpenClaw 是一个 AI 客户端,通常按 OpenAI 兼容格式接入。配置时只需要填 Base URL、API Key 和模型名。

第 1 步:打开设置页面

进入 OpenClaw 的 Settings / Provider / API 或类似配置页面。不同版本界面名称可能略有不同,只要找到 API 服务商配置即可。

第 2 步:填写以下信息

配置项 填写内容 说明
Provider Type OpenAI Compatible / OpenAI 兼容 不要选官方 Anthropic 格式。
API Base URL https://chuangyuan.org/v1 必须带 /v1。
API Key sk-your-api-key 替换成你的真实 Key。
Model 如 gpt-6-sol、claude-sonnet-5-5、deepseek-v4.1-flash 以控制台可用模型列表为准。

第 3 步:保存并测试

保存后发送一句简单测试,例如:

你好,请用一句话回答:当前 API 是否连接成功?

如果能正常回复,说明 OpenClaw 已接入成功。

提示:如果 OpenClaw 报模型不存在,通常是模型名填错、Key 的分组里没有这个模型,或工具没有使用 OpenAI 兼容模式。

WorkBuddy 配置

WorkBuddy 是腾讯推出的 AI 办公 / 编程助手,国内用户使用很多。它支持添加"自定义模型",可以把创元智境的模型接进去使用。

WorkBuddy 和其他工具最大的不同:它的"接口地址"要填完整路径 https://chuangyuan.org/v1/chat/completions,只填到 /v1 会请求失败。另外它只支持 OpenAI 兼容协议,不支持 Anthropic 原生协议。

第 1 步:准备 Key

按你要用的模型新建对应分组的 Key。国内用户最常见的是用国产模型(A01国产模型(全部主流国模) 分组),也可以用 GPT 或 Claude 分组。

第 2 步:添加自定义模型

打开 WorkBuddy,进入 设置 → 模型 → 添加模型,按下表填写:

字段 填写内容 说明
提供商 自定义 / Custom 不要选内置的厂商。
接口地址 https://chuangyuan.org/v1/chat/completions 必须带 /chat/completions。
API Key sk-your-api-key 换成你的真实 Key。
模型名称 如 deepseek-v4.1-flash、glm-5.3、kimi-k3、gpt-6-sol、claude-sonnet-5-5 必须是这个 Key 所在分组里有的模型。
高级配置 按模型能力勾选"工具调用""图片输入""推理模式" 自定义模型不会自动识别能力。拿不准时少勾,勾了模型不支持的能力会报错。
输入 / 输出 留空即可 留空使用默认的上下文和输出长度。
自定义协议 保持关闭 创元智境使用标准路径,不需要开启。

第 3 步:保存并选择模型

点击 保存 后,在模型选择器的"自定义"分组里选中刚加的模型,发一句话测试即可。

想换模型时,只需要编辑这个自定义模型,改"模型名称"再保存,不用重新填地址和 Key。想同时用多个模型,就多添加几个自定义模型。

费用说明:自定义模型的用量从你的创元智境余额扣除,不消耗 WorkBuddy 自带的额度。Key 只保存在你本机的 WorkBuddy 配置里。

代码接入

如果你要在自己的网站、SaaS、机器人或脚本中调用创元智境,可以使用 OpenAI 兼容方式。核心是把官方 SDK 的 baseURL 或 base_url 改为 https://chuangyuan.org/v1。

Node.js 示例

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
  baseURL: "https://chuangyuan.org/v1"
});

const res = await client.chat.completions.create({
  model: "gpt-6-sol",
  messages: [
    { role: "user", content: "Hello" }
  ]
});

console.log(res.choices[0].message.content);

Python 示例

from openai import OpenAI

client = OpenAI(
    api_key="sk-your-api-key",
    base_url="https://chuangyuan.org/v1"
)

res = client.chat.completions.create(
    model="gpt-6-sol",
    messages=[{"role": "user", "content": "Hello"}]
)

print(res.choices[0].message.content)

curl 示例

curl https://chuangyuan.org/v1/chat/completions \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-6-sol",
    "messages": [
      {"role": "user", "content": "Hello"}
    ]
  }'
注意:如果你是网页前端项目,不要把 API Key 写在浏览器端代码里。正确做法是前端请求你的后端,由后端持有 Key 并调用 API。

生图分组选择

开始写代码之前,先确定用哪个生图分组:分组决定了价格、出图方式和速度,新建 Key 时选好对应分组即可。下面先对比最常用的三个 GPT 生图分组,再介绍 Gemini 和 Grok 生图。

GPT 生图的三个分组模型名相同,区别在于出图方式、速度和价格:

GPT-Image GPT-Image-Premium GPT-Image-SR(超分)
出图方式 原生生成目标尺寸 原生生成目标尺寸 先生成较小的图,再 AI 超分到目标尺寸
画质细节 好 好 整体观感接近,近看细节(发丝、小字、纹理)稍弱
速度 / 稳定性 标准 更快、更稳 较快
适合 大多数商用场景 对成功率和时效要求高的生产业务 大批量、预算敏感、以手机屏幕浏览为主的场景
建议:拿不准就先用 GPT-Image。如果你的图主要在手机上看、对细节要求不高,可以试试 GPT-Image-SR,用同样的提示词对比一下,再决定是否切换。

其他生图分组:

GPT 生图

根据文字描述生成图片。Key 需选择 GPT-Image、GPT-Image-Premium 或 GPT-Image-SR 分组,怎么选见上一节。

生图请使用多模态地址:https://api.chuangyuan.org/v1。一张高质量大图通常要 30–120 秒,走主地址容易在 120 秒左右被断开。

可用模型

模型 说明
gpt-image-2 主力模型,画质、文字渲染和指令遵循都很好,大多数场景用它即可。
gpt-image-2.5 新一代生图模型(部分分组提供)。
gpt-image-2.5-flare gpt-image-2.5 的变体模型。
gpt-image-2.5-sunburst gpt-image-2.5 的变体模型。

不同模型的出图风格有差异,建议用同一个提示词各试一张,挑最合适的。

请求地址

POST https://api.chuangyuan.org/v1/images/generations

curl 示例

curl https://api.chuangyuan.org/v1/images/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "一只橘猫坐在窗台上看夕阳,水彩画风格",
    "n": 1,
    "size": "1024x1024",
    "quality": "high",
    "response_format": "b64_json"
  }'

Python 示例(保存为本地文件)

import base64
from openai import OpenAI

client = OpenAI(
    api_key="sk-your-api-key",
    base_url="https://api.chuangyuan.org/v1",
    timeout=300,  # 生图耗时长,超时时间要给够
)

res = client.images.generate(
    model="gpt-image-2",
    prompt="一只橘猫坐在窗台上看夕阳,水彩画风格",
    size="1536x1024",
    quality="high",
    response_format="b64_json",
)

with open("cat.png", "wb") as f:
    f.write(base64.b64decode(res.data[0].b64_json))

常用尺寸

用途 size 说明
方图 / 头像 / 商品图 1024x1024、2048x2048 最常用,速度最快。
横版海报 / 封面 1536x1024、2560x1440 16:9 用 2560x1440。
竖版海报 / 手机壁纸 1024x1536、1440x2560 9:16 用 1440x2560。
4K 大图 3840x2160、2160x3840 耗时最长,务必使用多模态地址。

自定义尺寸的一般规则:宽和高都是 16 的倍数,长边不超过 3840,宽高比不超过 3:1。尺寸越大,耗时越长。

请求参数

参数 类型 必填 说明
model string 是 填写 gpt-image-2。
prompt string 是 图片描述,建议具体说明主体、场景和风格。
n integer 否 生成数量,默认 1。
size string 否 图片尺寸,例如 1024x1024、2560x1440,见上方常用尺寸。
quality string 否 low / medium / high / auto。商用建议 high。
response_format string 否 填 b64_json,直接在响应里返回图片数据。

响应示例

{
  "created": 1767835126,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAAANSUhEUgAA..."
    }
  ],
  "usage": { ... }
}

取图方式:把 data[0].b64_json 做一次 Base64 解码,就是完整的图片文件。

GPT 改图

上传一张或多张参考图片,并根据提示词修改图片内容。

常见用途:换背景、改风格、把商品图放进场景、按参考图生成同款、多张图合成一张。

请求地址

POST https://api.chuangyuan.org/v1/images/edits
Content-Type: multipart/form-data

curl 示例:单张图改背景

curl https://api.chuangyuan.org/v1/images/edits \
  -H "Authorization: Bearer sk-your-api-key" \
  -F "model=gpt-image-2" \
  -F "image=@./source.png" \
  -F "prompt=将背景改成晴朗的海边,保持人物不变" \
  -F "size=1024x1536" \
  -F "quality=high" \
  -F "response_format=b64_json"

curl 示例:多张参考图合成

curl https://api.chuangyuan.org/v1/images/edits \
  -H "Authorization: Bearer sk-your-api-key" \
  -F "model=gpt-image-2" \
  -F "image[]=@./product.png" \
  -F "image[]=@./scene.png" \
  -F "prompt=把第一张图里的商品放到第二张图的桌面上,光影自然" \
  -F "size=1536x1024" \
  -F "response_format=b64_json"

Python 示例

import base64
from openai import OpenAI

client = OpenAI(api_key="sk-your-api-key",
                base_url="https://api.chuangyuan.org/v1",
                timeout=300)

res = client.images.edit(
    model="gpt-image-2",
    image=[open("product.png", "rb"), open("scene.png", "rb")],
    prompt="把第一张图里的商品放到第二张图的桌面上,光影自然",
    size="1536x1024",
    response_format="b64_json",
)
open("result.png", "wb").write(base64.b64decode(res.data[0].b64_json))
提示:参考图建议用 PNG / JPEG / WebP。参考图越清晰,结果越好。提示词里用"第一张图""第二张图"来指代上传顺序。

Gemini 生图

Gemini 生图推荐使用 Gemini 原生接口:你发一段内容(可以带参考图),模型在返回结果里直接给出图片数据。Key 需选择 Gemini-Image 分组。

模型 说明
gemini-3.1-flash-image-preview Nano Banana 2。
gemini-nano-banana-2.1 Nano Banana 2.1。
gemini-3-pro-image Gemini 3 Pro 生图模型。

请求地址

POST https://api.chuangyuan.org/v1beta/models/{模型名}:generateContent

用请求头 x-goog-api-key 传创元智境的 Key。生图同样耗时较长,请使用多模态地址 api.chuangyuan.org。

curl 示例:文字生图

curl "https://api.chuangyuan.org/v1beta/models/gemini-nano-banana-2.1:generateContent" \
  -H "x-goog-api-key: sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{
      "parts": [{"text": "生成一张赛博朋克风格的城市夜景"}]
    }],
    "generationConfig": {
      "responseModalities": ["TEXT", "IMAGE"],
      "imageConfig": {"aspectRatio": "16:9"}
    }
  }'

带参考图改图

把参考图以 Base64 放进 inlineData,和文字说明放在同一个 parts 里:

{
  "contents": [{
    "parts": [
      {"text": "把这张照片里的衣服换成红色,其他保持不变"},
      {"inlineData": {"mimeType": "image/png", "data": "iVBORw0KGgo..."}}
    ]
  }],
  "generationConfig": {"responseModalities": ["TEXT", "IMAGE"]}
}

取出图片

图片在 candidates[0].content.parts 里,找到带 inlineData 的那一项,把 inlineData.data 做 Base64 解码就是图片文件,格式见 inlineData.mimeType。

Python 示例(Google 官方 SDK)

安装 pip install google-genai,把 SDK 的地址改成创元智境即可:

from google import genai
from google.genai import types

client = genai.Client(
    api_key="sk-your-api-key",
    http_options=types.HttpOptions(base_url="https://api.chuangyuan.org"),
)

res = client.models.generate_content(
    model="gemini-nano-banana-2.1",
    contents="生成一张赛博朋克风格的城市夜景",
    config=types.GenerateContentConfig(
        response_modalities=["TEXT", "IMAGE"],
        image_config=types.ImageConfig(aspect_ratio="16:9"),
    ),
)

for part in res.candidates[0].content.parts:
    if part.inline_data:
        open("city.png", "wb").write(part.inline_data.data)

Grok 生图

Grok 生图走标准的 OpenAI 图像接口,用法和 GPT 生图一样。Key 需选择 grok-image2 分组。

curl https://api.chuangyuan.org/v1/images/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-image-2.0",
    "prompt": "宇航员在月球上弹吉他,电影质感",
    "n": 1
  }'

可用模型:grok-imagine-image-2.0、grok-imagine-image-quality、grok-imagine-image。

生图最佳实践

如果你要把生图接进自己的产品,下面几条能帮你少踩很多坑:

  1. 一律用多模态地址 https://api.chuangyuan.org/v1,客户端超时设到 300 秒以上。
  2. 在自己的业务里用队列控制并发。生图接口是同步的:请求会一直等到图片生成完才返回,平台不提供异步任务和回调。建议在你自己的后端用队列消费生图请求,从较低的并发开始逐步增加。并发过高会排队变慢,甚至收到 429。不要让终端用户的页面请求直接卡在生图接口上等待。
  3. 失败要重试,但要退避。遇到 429、5xx、超时,等待 2、4、8 秒后重试,最多 3 次。
  4. 检查返回内容。拿到结果后先确认 data 里确实有图片数据,再写入存储;空结果当作失败处理。
  5. 内容审核。涉及暴力、色情、真人肖像等内容可能被上游拒绝,返回 451 或安全提示,请调整提示词。

CC Switch 配置

CC Switch 是目前最常用的配置切换工具。它是一个图形界面的桌面应用,可以帮你管理 Claude Code、Codex、Gemini CLI、OpenCode、OpenClaw 等工具的多套配置,一键在官方账号和创元智境之间切换,不需要手动改环境变量和配置文件。

第 1 步:安装

系统 安装方式
Windows 从 GitHub Releases 下载 CC-Switch-v版本号-Windows.msi 安装包。
macOS 终端运行 brew install --cask cc-switch。
Linux 从 Releases 下载 .deb、.rpm 或 .AppImage。

第 2 步:添加 Claude Code 配置

  1. 打开 CC Switch,顶部选择 Claude Code。
  2. 点击 +(添加供应商),选择自定义配置。
  3. 按下表填写后保存:
字段 填写内容
供应商名称 创元智境-Claude
Base URL / 请求地址 https://chuangyuan.org(不带 /v1)
API Key claude 或 claude-max 分组的 Key
模型(Sonnet / Opus / Haiku) claude-sonnet-5-5 / claude-opus-5-5 / claude-haiku-5-5(Haiku 仅 claude-max 分组可用,claude 分组可都填 Sonnet)

第 3 步:添加 Codex 配置

  1. 顶部切换到 Codex,点击 + 添加供应商。
  2. 按下表填写后保存:
字段 填写内容
供应商名称 创元智境-Codex
Base URL / 请求地址 https://chuangyuan.org/v1(带 /v1)
API Key GPT 分组的 Key(如 GPT-PRO稳定 或 auto)
模型 gpt-6-sol

CC Switch 会自动把配置写进 Codex 的 config.toml,效果等同于:

model_provider = "chuangyuan"
model = "gpt-6-sol"

[model_providers.chuangyuan]
name = "创元智境"
base_url = "https://chuangyuan.org/v1"
wire_api = "responses"

如果自动生成的内容里 wire_api 不是 responses,在 CC Switch 的配置编辑框里手动改成上面这样。

第 4 步:启用并验证

  1. 在供应商列表里,点击创元智境那一项的 启用,当前生效的供应商会高亮。
  2. Claude Code 支持热切换,新开一个会话即可生效;Codex 需要重新打开终端或重启 Codex。
  3. 发一句测试消息,然后到控制台 使用日志 里确认有这条请求。
建议:Claude Code 和 Codex 分别用不同分组的 Key(一个 claude 分组、一个 GPT 分组),这样两边互不影响,用量也能分开统计。想切回官方账号时,在列表里启用官方配置即可。
还是走了旧配置?检查终端里是否还设置着 ANTHROPIC_BASE_URL、OPENAI_BASE_URL 等旧的环境变量,它们可能会覆盖 CC Switch 写入的配置。用 CC Switch 管理后,建议把这些环境变量删掉。

Magpie 配置

Magpie 是新出的开源模型管理工具,可以在一个界面里统一管理 Codex、Claude Code 等编程工具使用的服务商和模型。它在本机运行一个网关(默认 127.0.0.1:3425),各个编程工具通过这个网关访问创元智境。

第 1 步:安装

到 usemagpie.ai 下载对应系统(macOS / Windows / Linux)的桌面应用,安装并打开。Claude Code、Codex 本身也需要先装好,见前面的配置章节。

准备两个 Key:一个 GPT 分组的 Key 给 Codex 用,一个 claude 分组的 Key 给 Claude Code 用。在 Magpie 里两个服务商用同一个 Key 会出现重复提示。

第 2 步:添加 Claude Code 配置

  1. 进入 Providers → Add provider → Custom provider。
  2. 填写:
    • Name:chuangyuan-claude
    • Primary protocol:Anthropic compatible
    • Base URL:https://chuangyuan.org(不带 /v1,Magpie 会自动拼接 /v1/messages)
    • API key:claude 分组的 Key
    • Models:claude-sonnet-5-5、claude-opus-5-5
  3. 保存。

第 3 步:添加 Codex 配置

  1. 再次进入 Providers → Add provider → Custom provider。
  2. 填写:
    • Name:chuangyuan
    • Primary protocol:OpenAI compatible
    • Base URL:https://chuangyuan.org/v1
    • API key:GPT 分组的 Key
  3. 展开 More endpoints,把 Responses URL 也填成 https://chuangyuan.org/v1。
  4. 点击 Fetch models,勾选 gpt-6-sol 等要用的模型,保存。

注意:所有 Base URL 都只填到域名或 /v1,不要填 /chat/completions 这样的完整路径,Magpie 会自己拼接。

第 4 步:给编程工具分配模型

  1. 进入 Agents,找到 Codex 或 Claude Code。
  2. 点击当前模型,选择 chuangyuan → gpt-6-sol(Codex)或 chuangyuan-claude → claude-sonnet-5-5(Claude Code)。
  3. 关闭旧会话,重新打开工具,新开一个会话。

第 5 步:验证

在 Codex 或 Claude Code 里新开一个会话,发一句测试消息,然后到控制台 使用日志 里确认有这条请求。

常见问题

Cherry Studio 配置

Cherry Studio 是一款开源的桌面 AI 客户端,支持 Windows、macOS 和 Linux。可以在一个界面里和多个模型对话、对比回答、管理提示词,也支持 Gemini 生图。

第 1 步:安装

到 Cherry Studio 官网 下载对应系统的安装包,安装并打开。

第 2 步:选择提供商类型

Cherry Studio 里一个"提供商"对应一种接口格式和一个 Key。按你要用的模型建对应的提供商:

要用的模型 提供商类型 Key 的分组
GPT、Gemini 对话、国产模型、Grok OpenAI 对应模型的分组,如 GPT-PRO稳定、A01国产模型(全部主流国模)
Claude Anthropic claude 或 claude-max
Gemini 生图 Gemini Gemini-Image

第 3 步:添加提供商

  1. 点击左下角 设置,进入 模型服务。
  2. 点击列表底部的 添加,填写:
    • 提供商名称:创元智境(建多个时可以加后缀,如 创元智境-Claude)
    • 提供商类型:按上表选择
  3. 在右侧配置页填写:
    • API 密钥:对应分组的 Key
    • API 地址:https://chuangyuan.org(不带 /v1,Cherry Studio 会自动拼接接口路径)。Gemini 生图请填多模态地址 https://api.chuangyuan.org。
  4. 点击 API 密钥旁的 检查,提示连接成功即可。
  5. 打开右上角的开关,启用这个提供商。

第 4 步:添加模型

  1. 在提供商配置页底部点击 管理,会自动拉取这个 Key 能用的模型列表。
  2. 点击模型旁的 +,把要用的模型加进来,例如 gpt-6-sol、claude-sonnet-5-5、deepseek-v4.1-flash、gemini-nano-banana-2.1。

第 5 步:开始对话

回到对话页面,在顶部的模型选择器里选中刚添加的模型,发一句话测试。用 Gemini 生图模型时,直接用文字描述想要的图片即可。

检查失败怎么办?确认 API 地址没有多填 /v1,Key 没有多余空格,并且提供商类型和 Key 的分组对得上,例如 Claude 模型要用 Anthropic 类型配 claude 分组的 Key。

常见错误

401 Unauthorized

含义:API Key 无效、未填写、复制错误,或环境变量没有生效。

处理方法:

  1. 确认命令里的 sk-your-api-key 已替换成真实 Key。
  2. 确认 Key 没有多复制空格、换行或中文引号。
  3. 检查环境变量:
echo $ANTHROPIC_API_KEY
echo $OPENAI_API_KEY

404 Not Found

含义:Base URL 路径错误。最常见原因是 /v1 加错或漏加。

model not found / 模型不存在

最常见的原因是 Key 的分组不对。模型列表跟着 Key 的分组走,比如用 GPT-PRO稳定 分组的 Key 去调 claude-sonnet-5-5,就会报模型不存在。其他原因还有模型名拼写错误,或工具使用了不在你分组里的默认模型。

处理方法:到控制台查看这个 Key 的分组,或者用 GET /v1/models 列出它能用的模型,复制完整模型名;需要别的模型就新建一个对应分组的 Key。

insufficient_quota / balance not enough / 余额不足

含义:账号余额不足,或这个 Key 设置的额度上限已经用完。

处理方法:

rate_limit_exceeded / 429

含义:请求频率过高,超过 RPM/TPM/并发限制。

处理方法:

Connection refused / timeout

含义:网络连接失败、地址填错、代理异常或服务临时不可用。

处理方法:

  1. 确认 Base URL 正确。
  2. 浏览器打开 https://chuangyuan.org 看是否能访问。
  3. 检查本机代理、VPN、防火墙设置。
  4. 稍后重试,或查看平台公告。

524 / 请求在 2 分钟左右断开

含义:单个请求耗时超过主地址的超时限制,最常见于生图和超长输出。

处理方法:把 Base URL 换成多模态地址 https://api.chuangyuan.org/v1,并把客户端超时调到 300 秒以上。

请求成功了,但回复是空的

含义:上游号池繁忙时,偶尔会出现返回成功但没有内容的情况。

处理方法:直接重发一次即可。如果频繁出现,请记下大致时间和模型名,联系客服,我们会排查对应线路。

previous_response_id is not available

含义:使用 Responses 接口(Codex 默认)时,客户端带上了上一轮对话的 ID,但这一轮请求被分配到了另一条线路,找不到上一轮的记录。

处理方法:通常客户端会自动重试并恢复。如果一直报错,在 Codex 里开一个新会话即可。

451 / prompt or image unsafe

含义:提示词或参考图触发了上游的内容安全审核。

处理方法:修改提示词,避免暴力、色情、真人肖像等敏感内容后重试。

环境变量不生效

安全使用建议

API 网关可以方便地接入多种 AI 工具,但也需要正确管理 Key 和用量。

责任提醒:如果你把 Key 接入自己的下游产品,需要自行管理终端用户行为、隐私告知、使用限制和合规责任。

FAQ

1. sk-your-api-key 是什么?

这是示例占位符。你需要把它替换成控制台生成的真实 API Key,例如 sk-xxxxxx。

2. Claude Code 为什么不带 /v1?

Claude Code 使用 Anthropic 风格配置,工具自身会拼接接口路径。因此 Base URL 填 https://chuangyuan.org 即可。

3. OpenAI 兼容工具为什么要带 /v1?

OpenAI 兼容 SDK 和多数客户端会请求 /v1/chat/completions、/v1/models 等路径,因此 Base URL 通常需要写到 /v1。

4. 我可以同时配置 Claude Code 和 Codex 吗?

可以。它们使用不同环境变量,互不冲突:

5. 为什么工具能打开,但模型没有回复?

常见原因是余额不足、模型名错误、Key 没权限、请求超时或客户端默认模型不可用。先用 curl 验证,再排查客户端。

6. API Key 泄露怎么办?

立即进入控制台禁用或删除该 Key,然后新建一个 Key。建议每个工具单独建 Key,泄露时影响范围更小。

7. 可以把 API Key 放在前端网页里吗?

不建议,也不安全。前端代码会暴露给用户。正确做法是把 Key 放在你的后端服务器,由后端调用 API。

8. 一个 Key 能同时用 GPT、Claude 和生图吗?

不能。一个 Key 只属于一个分组,只能用这个分组里的模型。需要多种模型时,为每个分组各建一个 Key,比如 codex、claude、image。这样用量和费用也能分开统计。

9. 同一个模型在不同分组价格不一样,效果有区别吗?

编程和对话模型的能力是一样的,区别在于号池的稳定性、速度和并发能力。生图分组里,GPT-Image-SR 是超分出图,细节和另外两个分组有差异,见 生图分组选择。

10. 怎么知道有哪些新模型?

关注控制台公告和 模型广场。用 GET /v1/models 可以直接列出当前 Key 能用的最新模型。

11. 配置后还是失败,应该提供什么信息给客服?

请提供以下信息,避免只说"不能用":