CherryINCherryIN
New API 使用指南

代码调用教程

手把手教你用代码调用 CherryIN API

前言

本教程将手把手教您如何使用代码调用 CherryIN API。即使您是编程新手,也能轻松上手!

开始之前

在开始之前,请确保您已经完成了 快速上手 中的步骤,获取到了您的 API Key

安全提醒

请勿将 API Key 直接写入代码并提交到 Git 仓库! 本教程中的示例仅用于演示和本地测试。在生产环境中,请务必通过以下方式管理 API Key:

  • 环境变量:使用 os.getenv("CHERRYIN_API_KEY") 读取
  • 配置文件:使用 .env 文件配合 python-dotenv 库(记得将 .env 加入 .gitignore
  • 密钥管理服务:如 AWS Secrets Manager、HashiCorp Vault 等

泄露 API Key 可能导致您的账户被盗用,产生不必要的费用。

核心概念

在开始写代码之前,先了解几个关键概念:

概念说明示例
API Key您的身份凭证,用于验证您的请求sk-xxxxxxxx
Base URLAPI 服务的地址https://open.cherryin.net/v1
模型 (Model)您要调用的 AI 模型openai/gpt-5-chat, anthropic/claude-sonnet-4.5, google/gemini-2.5-flash
消息 (Messages)您与 AI 的对话内容[{"role": "user", "content": "你好"}]

关于模型名称

CherryIN 的模型名称格式为 厂商/模型名,例如 openai/gpt-5-chat。请在控制台的模型列表中查看可用模型。


Python 调用教程

我们推荐使用 UV 来管理 Python 环境和运行代码。UV 是一个现代化的 Python 包管理工具,安装简单、速度快,非常适合新手使用。

第一步:安装 UV

打开 PowerShell,运行以下命令:

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

安装完成后,重新打开终端,输入 uv --version 验证安装。

打开终端,运行以下命令:

curl -LsSf https://astral.sh/uv/install.sh | sh

安装完成后,重新打开终端,输入 uv --version 验证安装。

更多安装方式

如需了解更多安装选项,请参考 UV 官方文档

第二步:初始化项目并安装依赖

创建一个新文件夹作为项目目录,然后在终端中进入该目录,运行:

uv init
uv add openai

这会自动创建项目配置并安装 openai 库。

第三步:编写你的第一个程序

创建一个新文件 hello_ai.py,复制以下代码:

hello_ai.py
from openai import OpenAI

# ===== 配置区域(请修改为您自己的信息)=====
API_KEY = "sk-xxxxxxxx"  # 替换为您的 API Key
BASE_URL = "https://open.cherryin.net/v1"
MODEL = "openai/gpt-5-chat"  # 您想使用的模型
# ==========================================

# 创建客户端
client = OpenAI(
    api_key=API_KEY,
    base_url=BASE_URL
)

# 发送请求
response = client.chat.completions.create(
    model=MODEL,
    messages=[
        {"role": "user", "content": "你好,请用一句话介绍你自己"}
    ]
)

# 打印 AI 的回复
print(response.choices[0].message.content)

第四步:运行程序

在终端中运行:

uv run hello_ai.py

如果一切顺利,您将看到 AI 的回复!


进阶用法

掌握了基础用法后,来看看更多实用技巧。

多轮对话

AI 需要知道对话历史才能进行连贯的多轮对话:

multi_turn.py
from openai import OpenAI

client = OpenAI(
    api_key="sk-xxxxxxxx",  # 替换为您的 API Key
    base_url="https://open.cherryin.net/v1"
)

# 对话历史
messages = []

def chat(user_input):
    # 添加用户消息
    messages.append({"role": "user", "content": user_input})

    # 发送请求
    response = client.chat.completions.create(
        model="openai/gpt-5-chat",
        messages=messages
    )

    # 获取 AI 回复
    ai_reply = response.choices[0].message.content

    # 将 AI 回复添加到历史
    messages.append({"role": "assistant", "content": ai_reply})

    return ai_reply

# 进行多轮对话
print("AI:", chat("我叫小明"))
print("AI:", chat("我刚才说我叫什么?"))  # AI 会记住你的名字

流式输出(打字机效果)

让 AI 的回复像打字一样逐字显示:

streaming.py
from openai import OpenAI

client = OpenAI(
    api_key="sk-xxxxxxxx",  # 替换为您的 API Key
    base_url="https://open.cherryin.net/v1"
)

# 开启流式输出
stream = client.chat.completions.create(
    model="openai/gpt-5-chat",
    messages=[
        {"role": "user", "content": "讲一个100字的小故事"}
    ],
    stream=True  # 关键参数
)

# 逐块打印
for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

设置系统提示词

通过 system 角色定义 AI 的行为:

system_prompt.py
from openai import OpenAI

client = OpenAI(
    api_key="sk-xxxxxxxx",  # 替换为您的 API Key
    base_url="https://open.cherryin.net/v1"
)

response = client.chat.completions.create(
    model="openai/gpt-5-chat",
    messages=[
        {
            "role": "system",
            "content": "你是一个专业的英语老师,用简单易懂的方式解释语法问题。"
        },
        {
            "role": "user",
            "content": "什么是现在完成时?"
        }
    ]
)

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

控制输出参数

调整 AI 的创造力和输出长度:

parameters.py
from openai import OpenAI

client = OpenAI(
    api_key="sk-xxxxxxxx",  # 替换为您的 API Key
    base_url="https://open.cherryin.net/v1"
)

response = client.chat.completions.create(
    model="openai/gpt-5-chat",
    messages=[
        {"role": "user", "content": "写一首关于春天的诗"}
    ],
    temperature=0.8,  # 创造力(0-2,越高越有创意,默认 1)
    max_tokens=500,   # 最大输出字数
    top_p=0.9         # 采样范围(0-1,越低越确定)
)

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

其他语言示例

首先安装依赖:

npm install openai

然后创建 index.js

index.js
import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: 'sk-xxxxxxxx',  // 替换为您的 API Key
  baseURL: 'https://open.cherryin.net/v1'
});

async function main() {
  const response = await client.chat.completions.create({
    model: 'openai/gpt-5-chat',
    messages: [
      { role: 'user', content: '你好,请介绍一下你自己' }
    ]
  });

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

main();

在终端中直接发送请求:

curl https://open.cherryin.net/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxx" \
  -d '{
    "model": "openai/gpt-5-chat",
    "messages": [
      {"role": "user", "content": "你好"}
    ]
  }'

如果您使用其他编程语言,可以直接发送 HTTP POST 请求:

请求地址: POST https://open.cherryin.net/v1/chat/completions

请求头:

Content-Type: application/json
Authorization: Bearer sk-xxxxxxxx

请求体:

{
  "model": "openai/gpt-5-chat",
  "messages": [
    {"role": "user", "content": "你好"}
  ]
}

常见问题

报错:AuthenticationError

原因: API Key 无效或未正确设置

解决: 检查 API Key 是否正确复制,确保没有多余的空格

报错:RateLimitError

原因: 请求过于频繁

解决: 稍等片刻后重试,或在代码中添加延迟

报错:InsufficientQuotaError

原因: 账户余额不足或令牌额度用完

解决: 前往控制台充值或调整令牌额度

如何查看可用模型?

登录 CherryIN 控制台,在「模型列表」页面可以查看所有支持的模型及其名称。


完整示例:简易聊天机器人

把前面学到的知识整合起来,制作一个可以在终端运行的聊天机器人:

chatbot.py
from openai import OpenAI

# 配置
API_KEY = "sk-xxxxxxxx"  # 替换为您的 API Key
BASE_URL = "https://open.cherryin.net/v1"
MODEL = "openai/gpt-5-chat"

# 创建客户端
client = OpenAI(api_key=API_KEY, base_url=BASE_URL)

# 对话历史,包含系统提示
messages = [
    {"role": "system", "content": "你是一个友好的AI助手,用简洁的中文回答问题。"}
]

print("=" * 50)
print("欢迎使用 CherryIN 聊天机器人!")
print("输入 'quit' 或 'exit' 退出")
print("=" * 50)

while True:
    # 获取用户输入
    user_input = input("\n你: ").strip()

    # 检查退出条件
    if user_input.lower() in ['quit', 'exit', 'q']:
        print("再见!")
        break

    if not user_input:
        continue

    # 添加用户消息
    messages.append({"role": "user", "content": user_input})

    try:
        # 流式输出
        print("\nAI: ", end="", flush=True)

        stream = client.chat.completions.create(
            model=MODEL,
            messages=messages,
            stream=True
        )

        # 收集完整回复
        full_reply = ""
        for chunk in stream:
            if chunk.choices and chunk.choices[0].delta.content:
                content = chunk.choices[0].delta.content
                print(content, end="", flush=True)
                full_reply += content

        print()  # 换行

        # 保存 AI 回复到历史
        messages.append({"role": "assistant", "content": full_reply})

    except Exception as e:
        print(f"\n发生错误: {e}")

运行后,您就拥有了一个可以连续对话的 AI 聊天机器人!


下一步

  • 查看 常见问题 解决使用中的疑惑
  • 探索更多模型,尝试不同的 AI 能力
  • 将 API 集成到您自己的项目中