OpenClaw 企业定制 私人订制工作流 优化运维 openclaw记忆优化 问题咨询解决 请加微信交流
除了通过消息平台和WebSocket，Hermes还提供完整的REST API，让你可以用API方式集成AI能力到任何系统。API适合需要程序化调用AI的场景。这篇讲清楚Hermes API的结构、使用方法、认证方式、以及实际调用示例。
API概览
Hermes REST API提供以下端点：
POST /v1/chat/completions # 对话 POST /v1/completions # 补全 GET /v1/models # 列出可用模型 POST /v1/embeddings # 向量嵌入 GET /v1/usage # 使用量统计 GET /health # 健康检查启动API服务
# 启动API服务 hermes api --port 8080 # 或通过Gateway hermes gateway --api认证方式
API Key认证
# 生成API Key hermes api-key create --name "my-app" # 使用API Key curl https://your-domain.com/v1/chat/completions -H "Authorization: Bearer sk-hermes-xxx" -H "Content-Type: application/json" -d '{"model": "claude-3-sonnet", "messages": [{"role": "user", "content": "Hello"}]}'环境变量配置
hermes: api: enabled: true port: 8080 api_keys: - name: "my-app" key: "sk-hermes-xxx" expires: "2025-12-31"Chat Completions API
核心对话接口，兼容OpenAI格式：
POST /v1/chat/completions请求格式
{
"model": "claude-3-sonnet",
"messages": [
{"role": "system", "content": "你是一个助手"},
{"role": "user", "content": "你好"}
],
"temperature": 0.7,
"max_tokens": 1000,
"stream": false
}响应格式
{
"id": "chatcmpl-xxx",
"object": "chat.completion",
"created": 1234567890,
"model": "claude-3-sonnet",
"choices": [{
"index": 0,
"message": {
"role": "assistant",
"content": "你好！有什么可以帮你的？"
},
"finish_reason": "stop"
}],
"usage": {
"prompt_tokens": 10,
"completion_tokens": 20,
"total_tokens": 30
}
}curl调用示例
curl -X POST https://your-domain.com/v1/chat/completions -H "Authorization: Bearer sk-hermes-xxx" -H "Content-Type: application/json" -d '{
"model": "claude-3-sonnet",
"messages": [{"role": "user", "content": "用Python写一个快速排序"}]
}'Python调用示例
import openaiclient = openai.OpenAI(
api_key="sk-hermes-xxx",
base_url="https://your-domain.com/v1"
)response = client.chat.completions.create(
model="claude-3-sonnet",
messages=[{"role": "user", "content": "你好"}]
)
print(response.choices[0].message.content)流式响应
{
"stream": true
}import openaiclient = openai.OpenAI(
api_key="sk-hermes-xxx",
base_url="https://your-domain.com/v1"
)stream = client.chat.completions.create(
model="claude-3-sonnet",
messages=[{"role": "user", "content": "讲个故事"}],
stream=True
)for chunk in stream:
if chunk.choices[0].delta.content:
print(chunk.choices[0].delta.content, end="")模型列表
GET /v1/models{
"data": [
{"id": "claude-3-sonnet", "object": "model", "owned_by": "anthropic"},
{"id": "claude-3-opus", "object": "model", "owned_by": "anthropic"},
{"id": "gpt-4", "object": "model", "owned_by": "openai"},
{"id": "gemini-pro", "object": "model", "owned_by": "google"}
]
}使用量统计
GET /v1/usage{
"total_tokens": 1000000,
"total_cost": 5.50,
"period": "30d"
}Middleware配置
hermes:
api:
enabled: true
port: 8080
rate_limit:
enabled: true
requests_per_minute: 60
requests_per_hour: 1000
cors:
enabled: true
allowed_origins:
- "https://your-app.com"
logging:
enabled: true
log_requests: true
log_responses: falseNginx反代配置
server {
listen 443 ssl;
server_name your-domain.com;ssl_certificate /path/to/cert.pem;
ssl_certificate_key /path/to/key.pem;location / {
proxy_pass http://localhost:8080;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;# 流式响应需要这些
proxy_buffering off;
proxy_cache off;
proxy_read_timeout 86400;
}
}常见问题
401 Unauthorized？
检查API Key是否正确，是否带有Bearer前缀。
429 Rate Limited？
触发限流，降低请求频率。
连接超时？
检查服务器是否启动，防火墙是否开放端口。
模型不支持？
检查config.yaml中的模型配置是否正确。
总结
REST API让Hermes集成到任何系统：
- OpenAI兼容格式
- 支持流式响应
- API Key认证
- 速率限制保护
适合需要程序化调用AI的场景。
暂无评论内容