跳到主要内容

Universe 接口文档

本文档提供 Universe 的完整接口参考，包括端点地址、请求参数、响应格式、错误码等详细信息。

1. 概述​

Universe 为标准化 RESTful API 接口服务，通过统一协议连接大语言模型能力与开发者应用。支持 HTTP 请求和官方 SDK 调用，兼容 OpenAI 接口协议，实现对话补全、内容生成等功能。

2. API 端点​

类型端点地址说明
通用服务https://open.universeapi.com/api/paas/v4适用于所有通用场景（对话、生成、分析等）
专用服务（编码）https://open.universeapi.com/api/coding/paas/v4专为代码生成和编程辅助场景优化

如何选择：大部分场景使用通用服务端点即可。如果您开发的是代码助手、IDE 插件等编程相关产品，建议使用专用编码端点以获得更好的代码生成效果。

3. 身份验证​

所有 API 请求使用 HTTP Bearer 令牌 进行身份验证。请求头必须包含：

Authorization: Bearer YOUR_API_KEY
参数位置必填说明
AuthorizationRequest Header是格式为 Bearer {api_key}，Bearer 后有一个空格

安全规范：

  • 禁止将 API Key 硬编码在代码中
  • 建议通过环境变量或密钥管理服务配置
  • 为不同项目使用独立的 Key，设置权限和额度上限
# 推荐：通过环境变量配置
export UNIVERSE_API_KEY="sk-xxxxxxxxxxxxxxxxxxxxxxxx"

4. 可用模型​

模型名称API 调用参数定位
Universe 3.0universe-3.0轻量高效型，适合日常通用任务
Universe 3.0 Prouniverse-3.0-pro专业增强型，推理能力强，性价比高
Universe 4.5universe-4.5旗舰全能型，能力天花板最高

详细的模型能力对比请参考 模型产品介绍。

5. 对话补全（Chat Completions）​

这是 Universe 最核心的接口，用于向模型发送消息列表并获取回复。

5.1 请求​

POST /chat/completions

完整请求 URL 示例：

https://open.universeapi.com/api/paas/v4/chat/completions

请求参数​

参数类型必填默认值说明
modelstring是-模型名称，如 universe-3.0-pro。可用值见上方模型列表。
messagesarray是-对话消息列表，包含角色和内容。详见下方消息格式说明。
temperaturenumber否1.0控制输出随机性。范围 0-2，值越高输出越多样，值越低输出越确定。
top_pnumber否1.0核采样参数。仅从概率最高的 token 中采样。与 temperature 二选一调整。
max_tokensinteger否模型默认值限制模型输出的最大 token 数。
streamboolean否false是否启用流式输出。启用后逐 token 实时推送结果。
stopstring/array否null停止序列。当模型生成指定字符串时停止输出，最多设置 4 个。
frequency_penaltynumber否0范围 -2.0 到 2.0。正值降低已出现 token 的重复概率。
presence_penaltynumber否0范围 -2.0 到 2.0。正值鼓励模型引入新话题。
response_formatobject否-指定输出格式，如 {"type": "json_object"} 强制输出合法 JSON。
toolsarray否-工具/函数定义列表，用于 Function Calling。详见 5.4 节。
tool_choicestring/object否auto控制模型是否以及如何调用工具。可选值：auto、none、required。

消息格式（messages）​

消息列表中的每条消息包含以下字段：

字段类型必填说明
rolestring是消息角色：system、user、assistant、tool
contentstring是消息内容
namestring否消息发送者名称（用于多用户场景）

角色说明：

角色用途使用建议
system设定模型的角色、行为和约束放在消息列表最前面，通常只设一条
user用户发送的消息每轮对话中用户输入的内容
assistant模型之前的回复多轮对话时传入历史对话记录
tool工具/函数调用的返回结果配合 Function Calling 使用

5.2 非流式响应​

当 stream=false（默认）时，服务端返回完整的 JSON 响应：

{
  "id": "chatcmpl-xxxxxxxx",
  "object": "chat.completion",
  "created": 1700000000,
  "model": "universe-3.0-pro",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "你好！我是 Universe AI 助手，很高兴为你服务。"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 25,
    "completion_tokens": 18,
    "total_tokens": 43
  }
}

响应字段说明​

字段类型说明
idstring请求唯一标识
objectstring对象类型，固定为 chat.completion
createdinteger响应创建时间（Unix 时间戳）
modelstring实际使用的模型名称
choicesarray生成结果列表（通常为 1 个）
choices[].indexinteger结果索引
choices[].messageobject模型回复的消息内容
choices[].message.rolestring固定为 assistant
choices[].message.contentstring模型生成的文本内容
choices[].finish_reasonstring停止原因：stop（正常结束）、length（达到 max_tokens）、tool_calls（触发工具调用）
usageobjecttoken 消耗统计
usage.prompt_tokensinteger输入消耗的 token 数
usage.completion_tokensinteger输出消耗的 token 数
usage.total_tokensinteger总消耗 token 数

5.3 流式响应​

当 stream=true 时，服务端通过 SSE（Server-Sent Events） 协议逐块推送结果。每个数据块格式如下：

{
  "id": "chatcmpl-xxxxxxxx",
  "object": "chat.completion.chunk",
  "created": 1700000000,
  "model": "universe-3.0-pro",
  "choices": [
    {
      "index": 0,
      "delta": {
        "content": "你好"
      },
      "finish_reason": null
    }
  ]
}

流式结束时会发送一个 finish_reason 为 stop 的最终块，随后发送 [DONE] 标记：

data: [DONE]

流式响应解析（Python）​

response = client.chat.completions.create(
    model="universe-3.0-pro",
    messages=[
        {"role": "system", "content": "你是一个友好的 AI 助手。"},
        {"role": "user", "content": "讲一个简短的故事"}
    ],
    stream=True
)

for chunk in response:
    delta = chunk.choices[0].delta
    if delta.content:
        print(delta.content, end="", flush=True)

流式响应解析（cURL）​

curl -X POST "https://open.universeapi.com/api/paas/v4/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -N \
  -d '{
    "model": "universe-3.0-pro",
    "messages": [{"role": "user", "content": "你好"}],
    "stream": true
  }'

提示：cURL 中使用 -N 参数禁用输出缓冲，确保实时接收流式数据。

5.4 Function Calling（工具调用）​

Function Calling 允许模型在对话中调用外部函数或工具，实现与外部系统的交互。

定义工具​

在请求的 tools 参数中定义可用工具：

{
  "model": "universe-3.0-pro",
  "messages": [
    {"role": "user", "content": "北京今天天气怎么样？"}
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "获取指定城市的天气信息",
        "parameters": {
          "type": "object",
          "properties": {
            "city": {
              "type": "string",
              "description": "城市名称，如北京"
            }
          },
          "required": ["city"]
        }
      }
    }
  ],
  "tool_choice": "auto"
}

处理工具调用响应​

当模型决定调用工具时，响应的 finish_reason 为 tool_calls，message 中包含调用信息：

{
  "choices": [{
    "message": {
      "role": "assistant",
      "content": null,
      "tool_calls": [{
        "id": "call_xxxxxxxx",
        "type": "function",
        "function": {
          "name": "get_weather",
          "arguments": "{\"city\": \"北京\"}"
        }
      }]
    },
    "finish_reason": "tool_calls"
  }]
}

返回工具结果​

调用外部函数后，将结果以 tool 角色消息返回给模型：

{
  "model": "universe-3.0-pro",
  "messages": [
    {"role": "user", "content": "北京今天天气怎么样？"},
    {"role": "assistant", "content": null, "tool_calls": [{"id": "call_xxxxxxxx", "type": "function", "function": {"name": "get_weather", "arguments": "{\"city\": \"北京\"}"}}]},
    {"role": "tool", "content": "{\"temperature\": 28, \"condition\": \"晴\"}", "tool_call_id": "call_xxxxxxxx"}
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "获取指定城市的天气信息",
        "parameters": {
          "type": "object",
          "properties": {
            "city": {
              "type": "string",
              "description": "城市名称，如北京"
            }
          },
          "required": ["city"]
        }
      }
    }
  ]
}

模型将基于工具返回的结果生成最终回复。

6. 调用示例​

6.1 Python SDK 示例​

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": "你是一个专业的翻译助手，将用户输入翻译为英文。"},
        {"role": "user", "content": "今天天气真不错，适合出去走走。"}
    ],
    temperature=0.3
)

print(response.choices[0].message.content)
print(f"Token 消耗: {response.usage.total_tokens}")

6.2 Java SDK 示例​

import universeai.UniverseClient;
import universeai.service.model.*;

public class ChatExample {
    public static void main(String[] args) {
        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("你是一个专业的翻译助手，将用户输入翻译为英文。")
                    .build(),
                ChatMessage.builder()
                    .role("user")
                    .content("今天天气真不错，适合出去走走。")
                    .build()
            ))
            .temperature(0.3f)
            .build();

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

6.3 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": "你是一个专业的翻译助手，将用户输入翻译为英文。"},
      {"role": "user", "content": "今天天气真不错，适合出去走走。"}
    ],
    "temperature": 0.3
  }'

6.4 OpenAI SDK 兼容调用​

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": "system", "content": "你是一个专业的翻译助手，将用户输入翻译为英文。"},
        {"role": "user", "content": "今天天气真不错，适合出去走走。"}
    ],
    temperature=0.3
)

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

7. 多轮对话​

实现多轮对话需要将历史消息一并传入 messages 列表：

messages = [
    {"role": "system", "content": "你是一个友好的 AI 助手。"},
    {"role": "user", "content": "什么是大语言模型？"},
    {"role": "assistant", "content": "大语言模型（LLM）是一种基于深度学习的自然语言处理模型..."},
    {"role": "user", "content": "它和传统 NLP 模型有什么区别？"},
]

response = client.chat.completions.create(
    model="universe-3.0-pro",
    messages=messages
)

注意：每次请求都需要传入完整的消息历史，模型不会自动保存对话状态。建议对过长的历史对话进行摘要压缩，避免超出上下文窗口限制。

8. 错误码​

HTTP 状态码​

状态码含义常见原因解决方案
400Bad Request请求体格式错误、必填参数缺失、参数值超出范围检查 JSON 格式和必填参数
401UnauthorizedAPI Key 无效、缺失或未正确传入确认 Key 正确，检查请求头格式
403ForbiddenKey 无权限访问该模型，或请求内容违反使用规范检查 Key 权限配置和使用规范
404Not Found模型名称拼写错误或端点地址不正确核对模型名称和端点
429Too Many Requests请求频率超出配额限制降低频率或申请提升配额
500Internal Server Error服务端内部故障稍后重试，持续问题请联系支持
502Bad Gateway上游服务暂不可用稍后重试
503Service Unavailable系统维护或过载等待几分钟后重试

错误响应格式​

所有错误响应遵循统一格式：

{
  "error": {
    "message": "Invalid API key provided.",
    "type": "authentication_error",
    "code": "invalid_api_key"
  }
}
字段说明
error.message人类可读的错误描述
error.type错误类型标识
error.code错误代码，便于程序化处理

9. 速率限制​

限制项说明
RPM（每分钟请求数）每分钟允许发起的最大请求次数
RPH（每小时请求数）每小时允许发起的最大请求次数
TPM（每分钟 token 数）每分钟允许消耗的最大 token 数量

触发速率限制时返回 HTTP 429 错误。推荐的处理方式：

import time

def call_with_retry(client, messages, max_retries=3):
    for attempt in range(max_retries):
        try:
            return client.chat.completions.create(
                model="universe-3.0-pro",
                messages=messages
            )
        except Exception as e:
            if "429" in str(e) and attempt < max_retries - 1:
                wait_time = 2 ** attempt  # 指数退避：1s, 2s, 4s
                time.sleep(wait_time)
            else:
                raise

如需提升配额，请联系技术支持团队。

10. 调试建议​

方法说明
检查请求和响应打印完整的请求参数和响应内容，排查格式问题
使用最小化示例先用最简单的 Prompt 测试接口连通性，再逐步增加复杂度
查看 usage 字段确认 token 消耗是否符合预期
对比 curl 和 SDK如果 SDK 调用失败，先用 curl 测试排除网络问题
在线调试工具使用控制台提供的在线调试工具快速验证接口

更多资源​

文档内容
开发者指南快速入门、平台介绍、核心概念
模型产品介绍各模型能力对比、选型指南
产品定价计费规则、模型价格、成本优化
Prompt 工程指南Prompt 编写技巧、参数调优、模板速查
常见问题FAQ、故障排查、SDK 安装、性能优化