Genesis API 快速开始

本页使用 Genesis 的 OpenAI 兼容接口完成一次非流式对话请求。整个过程需要三个值：Base URL、Genesis API Key 和模型 ID。

准备接入信息

  1. 在 Genesis 模型页选择支持对话的模型，复制详情页显示的模型 ID。

  2. 在凭据管理中为服务账号签发 Genesis API Key。若当前部署的 Genesis 密钥页提供本地密钥创建入口，也可以按页面配置模型范围、额度、速率和有效期后创建。

  3. 打开 Genesis 使用页，复制 Base URL。Base URL 通常已经包含 /v1，调用时不要再次添加版本段。

  4. 确认 Key 允许访问所选模型，并将完整 Key 保存到密钥服务或环境变量中。完整值可能只在创建或更新时显示一次。

以下命令使用占位值，必须替换为控制台中的实际内容：

export GENESIS_BASE_URL='https://<genesis-host>/<path>/v1'
export GENESIS_API_KEY='<your-genesis-api-key>'
export GENESIS_MODEL='<model-id>'

不要把真实 Key 写入脚本、终端历史共享文件或 Git 仓库。

先确认模型是否可用

使用当前 Key 查询可用模型，可以同时验证 Base URL、认证和模型授权：

curl --fail-with-body --silent --show-error \
  "$GENESIS_BASE_URL/models" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

成功响应的 data 数组中应包含可用模型。找到准备调用的 id，并确认它与 GENESIS_MODEL 完全一致。模型目录和 Key 的授权范围会变化，不要在应用中长期维护未经校验的固定列表。

发送第一个对话请求

curl --fail-with-body --silent --show-error \
  "$GENESIS_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $GENESIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"model\": \"$GENESIS_MODEL\",
    \"messages\": [
      {
        \"role\": \"user\",
        \"content\": \"用一句话解释数据血缘。\"
      }
    ],
    \"stream\": false
  }"

对话文本通常位于 choices[0].message.content，本次调用的 Token 用量位于 usage。应用接入监控时，建议同时记录 HTTP 状态、响应中的请求标识（若有）、模型 ID、延迟和 usage，但不要记录 Key。

使用 Python SDK

Genesis 兼容 OpenAI SDK 的常用调用方式。安装 SDK：

python -m pip install openai

创建 quickstart.py：

import os

from openai import OpenAI

client = OpenAI(
    api_key=os.environ["GENESIS_API_KEY"],
    base_url=os.environ["GENESIS_BASE_URL"],
)

response = client.chat.completions.create(
    model=os.environ["GENESIS_MODEL"],
    messages=[
        {"role": "user", "content": "用一句话解释数据血缘。"},
    ],
)

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

运行：

python quickstart.py

如果你已有使用 OpenAI SDK 的项目，通常只需把 base_url 指向 Genesis，并换用 Genesis API Key；具体接口仍须由所选模型支持。

常见失败

现象

检查项

401 或认证失败

是否使用 Authorization: Bearer；Key 是否完整、有效；是否误用了其他产品的令牌

404 或路径错误

Base URL 是否来自「使用」页；是否重复拼接了 /v1

模型不可用或无权限

GET /models 是否返回该模型；Key 的允许模型范围是否包含该 ID

429

Key 的并发、RPM、TPM 或额度是否已达到；重试时使用指数退避，不要立即密集重放

参数不支持

在模型详情页确认能力，并先在 Genesis 调试页用同一模型验证

生产环境应为网络超时和可重试错误设置有上限的指数退避；不要自动重试确定性的认证错误和参数错误。需要定位具体调用时，可在 Genesis 日志页按时间、Key、模型或状态筛选。

下一步