Universe 开发者指南

欢迎使用 Universe！本指南将帮助您在 5 分钟内完成第一个 API 调用，并全面了解平台的核心能力和开发方式。

平台简介

Universe 是一个一站式 AI 大模型 API 服务平台，为开发者提供功能丰富、灵活易用的大语言模型调用能力。平台覆盖从轻量高效到旗舰全能的多款模型，支持文本生成、对话交互、代码辅助、内容创作等多种应用场景。

核心优势

优势	说明
丰富的模型矩阵	提供 Universe 3.0 / 3.0 Pro / 4.5 三款不同定位的模型，覆盖各类场景需求。
完善的开发套件	官方 Python SDK、Java SDK、OpenAI 兼容接口、LangChain 集成，开箱即用。
极致性价比	按 token 计费，支持 Prompt Cache 缓存机制，缓存命中可节省约 97%-99% 的输入费用。
稳定的服务保障	高并发资源、多层次安全防护、99.9% 服务可用性保障。

快速开始

跟随以下四个步骤，分钟级完成 API 集成。

第一步：获取 API Key

API Key 是调用 Universe API 的身份凭证。请按以下步骤获取：

访问 Universe 控制台，注册并登录账号。
进入 API Keys 管理页面。
点击"创建新密钥"，复制并妥善保管生成的 Key。

安全提醒：请勿将 API Key 硬编码在代码中或提交到公开仓库。推荐通过环境变量管理：
export UNIVERSE_API_KEY="sk-xxxxxxxxxxxxxxxxxxxxxxxx"

第二步：安装 SDK

根据您的技术栈选择安装方式：

Python SDK（推荐 Python 3.8+）：

pip install universeai

Java SDK（Maven）：

<dependency>
    <groupId>com.universeai</groupId>
    <artifactId>universeai-java-sdk</artifactId>
    <version>1.0.0</version>
</dependency>

OpenAI SDK 兼容模式（从 OpenAI 迁移时使用）：

pip install openai

第三步：发送第一个请求

以下是最简单的调用示例，向模型发送一条消息并获取回复：

Python：

from universeai import UniverseClient

client = UniverseClient(api_key="YOUR_API_KEY")

response = client.chat.completions.create(
    model="universe-3.0-pro",
    messages=[
        {"role": "system", "content": "你是一个友好的 AI 助手。"},
        {"role": "user", "content": "你好，请用一句话介绍一下自己。"}
    ]
)

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

cURL：

curl -X POST "https://open.universeapi.com/api/paas/v4/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "universe-3.0-pro",
    "messages": [
      {"role": "system", "content": "你是一个友好的 AI 助手。"},
      {"role": "user", "content": "你好，请用一句话介绍一下自己。"}
    ]
  }'

Java：

UniverseClient client = UniverseClient.builder().apiKey("YOUR_API_KEY").build();

ChatCompletionCreateParams request = ChatCompletionCreateParams.builder()
    .model("universe-3.0-pro")
    .messages(Arrays.asList(
        ChatMessage.builder().role("system").content("你是一个友好的 AI 助手。").build(),
        ChatMessage.builder().role("user").content("你好，请用一句话介绍一下自己。").build()
    ))
    .build();

ChatCompletionResponse response = client.chat().createChatCompletion(request);
System.out.println(response.getData().getChoices().get(0).getMessage());

第四步：集成到业务中

成功收到第一个响应后，您可以：

将 API 调用封装为后端服务，对接前端应用
使用流式输出（stream=true）实现实时打字机效果
结合 System Prompt 定制模型的角色和行为
参考 Prompt 工程指南优化输出质量

提示：如果您开发的是代码助手或 IDE 插件等编程产品，请使用专用编码端点 https://open.universeapi.com/api/coding/paas/v4 以获得更好的代码生成效果。详见接口文档。

开发方式

Universe API 提供多种接入方式，满足不同技术栈和场景的需求。

接入方式	说明	适用场景	入门难度
HTTP RESTful API	标准 HTTP 请求，语言无关	任意技术栈	低
Python SDK	官方工具包，支持同步/异步	Python 项目	低
Java SDK	企业级工具包，支持高并发	Java/Spring 项目	低
OpenAI 兼容接口	兼容 OpenAI SDK 协议	从 OpenAI 迁移	极低
LangChain 集成	原生支持 LangChain 框架	AI Agent / RAG 应用	中

从 OpenAI 迁移

只需修改两个参数即可无缝迁移：

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_UNIVERSE_API_KEY",
    base_url="https://open.universeapi.com/api/paas/v4"
)

# 其余代码保持不变
response = client.chat.completions.create(
    model="universe-3.0-pro",
    messages=[{"role": "user", "content": "你好"}]
)

LangChain 集成

from langchain_openai import ChatOpenAI

llm = ChatOpenAI(
    model="universe-3.0-pro",
    api_key="YOUR_UNIVERSE_API_KEY",
    base_url="https://open.universeapi.com/api/paas/v4"
)

response = llm.invoke("介绍一下 Universe API 的核心优势")

核心概念

API Key

API Key 是您的身份凭证，每个请求必须携带有效的 Key。建议在控制台为不同项目创建独立的 Key，并设置调用频率和消费额度上限。详见常见问题中的权限控制说明。

Token

Token 是模型处理文本的最小单位，也是计费的基本单位。

语言	大致换算
中文	1 个汉字 ≈ 1-2 个 token
英文	1 个单词 ≈ 1-1.5 个 token

每次 API 调用的响应中包含 usage 字段，记录本次消耗的具体 token 数量。详细的计费说明请参考产品定价。

上下文窗口（Context Window）

上下文窗口是模型在一次对话中能处理的最大文本长度，包含用户输入、模型回复和中间推理内容。超出限制的部分将被自动截断。

应对策略：

精简输入，去除不必要的上下文
定期总结长对话，压缩历史信息
选择上下文窗口更大的模型（如 Universe 4.5）

System Prompt

System Prompt 是每次对话中优先级最高的指令，用于定义模型的角色、行为模式和输出规范。一个设计良好的 System Prompt 能显著提升输出的一致性和可控性。详细的编写技巧请参考 Prompt 工程指南。

流式与非流式输出

模式	参数	特点	适用场景
非流式	`stream=false`（默认）	等待生成完毕后一次性返回	后端批处理、数据提取
流式	`stream=true`	逐 token 实时推送	聊天对话、实时交互

可用模型

模型	定位	特点	适用场景
Universe 3.0	轻量高效型	响应快、成本低	日常问答、文本分类、批量生成
Universe 3.0 Pro	专业增强型	推理强、性价比高	内容创作、代码生成、数据分析
Universe 4.5	旗舰全能型	能力天花板最高	复杂推理、企业 Agent、专业咨询

不知道选哪个？推荐从 Universe 3.0 Pro 开始，它是能力与成本的最佳平衡点。详细的模型对比请参考模型产品介绍。

最佳实践概览

实践	建议
Prompt 设计	提供清晰、具体的指令，包含背景信息和输出格式要求。详见 Prompt 工程指南。
模型选型	简单任务用轻量模型（3.0），复杂任务才用旗舰模型（4.5），降低成本的同时保证质量。
成本控制	利用 Prompt Cache 缓存机制、精简输入内容、合理设置 `max_tokens` 参数。详见产品定价。
错误处理	实现指数退避重试机制，妥善处理 429 限流和 5xx 服务端错误。详见常见问题。
密钥安全	使用环境变量管理 API Key，为不同项目使用独立的 Key，定期轮换。
生产部署	使用流式输出优化用户体验，通过异步调用处理高并发，设置消费额度上限防止意外超支。

文档导航

文档	内容
接口文档	完整的 API 参考：端点、参数、响应格式、错误码
模型产品介绍	各模型的能力定位、核心特性、选型指南
产品定价	计费规则、模型价格、Prompt Cache 说明、成本优化
Prompt 工程指南	Prompt 编写技巧、System Prompt 设计、参数调优
常见问题	FAQ、故障排查、错误码详解、SDK 安装问题

遇到问题？请访问帮助中心或通过页面右上角的反馈按钮联系技术支持团队。

平台简介​

核心优势​

快速开始​

第一步：获取 API Key​

第二步：安装 SDK​

第三步：发送第一个请求​

第四步：集成到业务中​

开发方式​

从 OpenAI 迁移​

LangChain 集成​

核心概念​

API Key​

Token​

上下文窗口（Context Window）​

System Prompt​

流式与非流式输出​

可用模型​

最佳实践概览​

文档导航​