OspreyAI API 使用指南

本文档介绍如何使用 OspreyAI API，该服务通过 new API 转发提供 GLM-4.6-FP8 模型访问。

重要发现

OspreyAI 同时支持两种 API 格式：

1. OpenAI 兼容格式 - /v1/chat/completions 端点

2. Anthropic 兼容格式 - /v1/messages 端点

根据测试结果，OpenAI 格式返回更完整的内容，而 Anthropic 格式在某些情况下返回空内容。

配置

环境变量设置

在项目根目录的 .env 文件中配置以下环境变量：

# OspreyAI API配置
OSPREYAI_API_KEY=your-api-key-here
OSPREYAI_OPENAI_BASE_URL=https://open.ospreyai.cn/v1/chat/completions
OSPREYAI_ANTHROPIC_BASE_URL=https://open.ospreyai.cn/v1/messages

API 端点

OpenAI 兼容格式（推荐）

• 端点: https://open.ospreyai.cn/v1/chat/completions

• 模型名称: glm-4.6-fp8

• 认证方式: Authorization: Bearer {api_key}

Anthropic 兼容格式

• 端点: https://open.ospreyai.cn/v1/messages

• 模型名称: glm-4.6-fp8

• 认证方式: x-api-key: {api_key}

• API版本: 2023-06-01

可用模型

通过 /v1/models 端点可以获取可用模型列表：

{
  "data": [
    {
      "id": "deepseek-r1-0528",
      "object": "model",
      "supported_endpoint_types": ["openai"]
    },
    {
      "id": "glm-4.6-fp8",
      "object": "model",
      "supported_endpoint_types": ["openai"]
    }
  ]
}

使用方法

1. Python 脚本测试

项目提供了三个测试脚本：

基础测试脚本（Anthropic 格式）

uv run python scripts/test_ospreyai_api.py

综合测试脚本（Anthropic 格式）

uv run python scripts/test_ospreyai_comprehensive.py

格式对比测试脚本

uv run python scripts/test_ospreyai_formats.py

1. curl 命令

OpenAI 兼容格式（推荐）

设置环境变量
export OSPREYAI_API_KEY="your-api-key"

发送请求
curl -X POST "https://open.ospreyai.cn/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${OSPREYAI_API_KEY}" \
  -d '{
    "model": "glm-4.6-fp8",
    "max_tokens": 1000,
    "messages": [
      {
        "role": "user",
        "content": "Hello! Please respond with a simple test message."
      }
    ]
  }'

Anthropic 兼容格式

设置环境变量
export OSPREYAI_API_KEY="your-api-key"

发送请求
curl -X POST "https://open.ospreyai.cn/v1/messages" \
  -H "Content-Type: application/json" \
  -H "x-api-key: ${OSPREYAI_API_KEY}" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "glm-4.6-fp8",
    "max_tokens": 1000,
    "messages": [
      {
        "role": "user",
        "content": "Hello! Please respond with a simple test message."
      }
    ]
  }'

API 格式详解

OpenAI 兼容格式（推荐）

请求头

{
  "Content-Type": "application/json",
  "Authorization": "Bearer your-api-key"
}

请求体

{
  "model": "glm-4.6-fp8",
  "max_tokens": 1000,
  "messages": [
    {
      "role": "user",
      "content": "你的消息内容"
    }
  ]
}

响应格式

{
  "id": "chat-completion-id",
  "object": "chat.completion",
  "created": 1760161674,
  "model": "glm-4.6-fp8",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "模型回复内容",
        "reasoning_content": "推理内容（如果有）"
      },
      "finish_reason": "length"
    }
  ],
  "usage": {
    "prompt_tokens": 15,
    "completion_tokens": 100,
    "total_tokens": 115
  }
}

Anthropic 兼容格式

请求头

{
  "Content-Type": "application/json",
  "x-api-key": "your-api-key",
  "anthropic-version": "2023-06-01"
}

请求体

{
  "model": "glm-4.6-fp8",
  "max_tokens": 1000,
  "messages": [
    {
      "role": "user",
      "content": "你的消息内容"
    }
  ]
}

响应格式

{
  "id": "message-id",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "模型回复内容"
    }
  ],
  "stop_reason": "max_tokens",
  "model": "glm-4.6-fp8",
  "usage": {
    "input_tokens": 15,
    "output_tokens": 1000
  }
}

测试结果

格式对比测试结果

根据格式对比测试，发现以下重要信息：

OpenAI 兼容格式（/v1/chat/completions）

✅ 响应完整 - 返回完整的模型回复内容 ✅ 标准格式 - 完全兼容 OpenAI API 格式 ✅ 推理内容 - 包含 reasoning_content 字段 ✅ 使用统计 - 详细的 token 使用信息

Anthropic 兼容格式（/v1/messages）

✅ 连接成功 - API 连接正常 ❌ 内容缺失 - 在某些情况下返回空内容 ✅ 格式正确 - 符合 Anthropic API 格式

功能测试结果

✅ 基础对话 - 支持单轮对话 ✅ 多轮对话 - 支持上下文相关的多轮对话 ✅ 代码生成 - 能够生成代码片段 ✅ 错误处理 - 正确返回错误信息 ❌ 流式响应 - 当前配置下流式响应返回空内容

推荐使用方案

强烈建议使用 OpenAI 兼容格式，原因：

1. 内容完整: OpenAI 格式返回完整的回复内容

2. 标准兼容: 与现有 OpenAI 生态系统完全兼容

3. 信息丰富: 包含推理内容和详细的使用统计

4. 稳定可靠: 测试中表现更稳定

注意事项

1. 格式选择: 推荐使用 OpenAI 兼容格式 /v1/chat/completions

2. 模型限制: 使用 glm-4.6-fp8 模型，不是 Claude 模型

3. Token 限制: 建议设置合理的 max_tokens 值

4. API 密钥: 确保使用有效的 API 密钥

5. 错误处理: 妥善处理 503 等错误状态码

集成到项目

要在项目中使用 OspreyAI API，推荐使用 OpenAI 兼容格式：

• src/ai/llm_adapter.py - LLM 适配器基类

• src/ai/qwen_code_adapter.py - Qwen 模型适配器示例

可以创建一个新的 ospreyai_adapter.py 文件，使用 OpenAI 客户端库连接到 OspreyAI 端点。

集成示例

from openai import OpenAI

client = OpenAI(
    api_key="your-ospreyai-api-key",
    base_url="https://open.ospreyai.cn/v1"
)

response = client.chat.completions.create(
    model="glm-4.6-fp8",
    messages=[
        {"role": "user", "content": "Hello!"}
    ],
    max_tokens=1000
)

故障排除

常见错误

1. 503 错误: 模型不可用或名称错误

   1. 确保使用正确的模型名称 glm-4.6-fp8

2. 认证失败: API 密钥无效

   1. 检查环境变量 OSPREYAI_API_KEY 是否正确设置

   2. OpenAI 格式使用 Authorization: Bearer 头

   3. Anthropic 格式使用 x-api-key 头

3. 空响应: 可能是格式或 token 限制问题

   1. 推荐使用 OpenAI 格式

   2. 调整 max_tokens 参数

4. 端点错误: 确保使用正确的端点

   1. OpenAI 格式: /v1/chat/completions

   2. Anthropic 格式: /v1/messages

调试建议

1. 使用 scripts/test_ospreyai_formats.py 验证两种格式

2. 检查网络连接和防火墙设置

3. 查看 API 使用情况和配额限制

4. 优先使用 OpenAI 兼容格式进行开发