# AI-HIVE API 接入说明

> 一份给 AI Agent 和开发者读的接入说明。按你要生成的内容选接入方式：文本、图片或视频；兼容协议用于现有文字客户端；模型、参数和价格以接口返回为准。

把本说明交给 WorkBuddy、豆包工作、千问办公等智能体，或直接按下面的命令执行。

## 获取 API 密钥

1. 登录控制台，打开 https://0.0.0.0:3000/platform/keys（需要登录）。
2. 创建 API 密钥。
3. 在运行智能体或代码的环境里设置环境变量：

```bash
# macOS / Linux
export AI_HIVE_API_KEY="<API_KEY>"

# Windows PowerShell
$env:AI_HIVE_API_KEY="<API_KEY>"
```

不要把密钥写进代码、日志或对话；本说明和链接都不包含密钥。

## 选择内容类型

### 文本

- Hive Chat API：Base URL https://0.0.0.0:3000/api/openapi/v1；先 `GET /models?modelType=TEXT` 取 `publicModelId`、`routingMode`、`pricingSnapshot`，再 `POST /chat/text`。
- 兼容协议：Base URL https://0.0.0.0:3000/api/openapi/native/v1；Chat Completions、Responses、Anthropic Messages。
- 兼容协议只支持文字模型；`GET /models` 为空时，改用 Hive Chat API。

### 图片

- Hive Media API：Base URL https://0.0.0.0:3000/api/openapi/v1；`POST /generation/image`、`GET /generation/tasks/{taskId}`。
- 正式提交前先 `dryRun: true` 预检；参考图先上传素材。

### 视频

- Hive Media API：Base URL https://0.0.0.0:3000/api/openapi/v1；`POST /generation/video`、`GET /generation/tasks/{taskId}`。
- 正式提交前先 `dryRun: true` 预检；支持首尾帧和参考素材。

- 素材上传：`POST /media/upload-token` → 按返回的 URL 和 headers 上传 → `POST /media/{mediaId}/complete`。

## 认证

所有请求都使用同一个 API 密钥：

```
Authorization: Bearer $AI_HIVE_API_KEY
Content-Type: application/json
```

密钥只从本机环境变量 `AI_HIVE_API_KEY` 读取；不要索取、回显或写入代码、日志和对话。

## Hive Chat API

### 1. 列出文字模型

```bash
curl "https://0.0.0.0:3000/api/openapi/v1/models?modelType=TEXT" \
  -H "Authorization: Bearer $AI_HIVE_API_KEY"
```

从返回里选一个模型，记下 `publicModelId`、`routingModes` 和对应模式的 `pricingSnapshot`。这个请求只读，不产生费用。

### 2. 发起文字请求

```bash
curl "https://0.0.0.0:3000/api/openapi/v1/chat/text" \
  -H "Authorization: Bearer $AI_HIVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "publicModelId": "<MODEL_ID>",
    "routingMode": "<ROUTING_MODE>",
    "clientRequestId": "<UUID>",
    "messages": [{"role": "user", "content": "你好"}]
  }'
```

默认按当前价格计费；网络重试时复用同一个 `clientRequestId` 和原请求。如果接口要求携带价格快照，把模型列表里对应模式的 `pricingSnapshot` 原样带上，不要自己拼价格结构。

需要流式输出时加 `"stream": true`，响应是 SSE；非流式请求返回普通 JSON。

## Hive Media API

图片和视频都先发送 `dryRun: true` 预检参数与费用，确认后再正式提交。预检不进行内容审核，也不保证生成成功。

### 图片预检

```bash
curl "https://0.0.0.0:3000/api/openapi/v1/generation/image" \
  -H "Authorization: Bearer $AI_HIVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "publicModelId": "<MODEL_ID>",
    "routingMode": "<ROUTING_MODE>",
    "prompt": "一只在窗边看雨的猫",
    "batchSize": 1,
    "params": {},
    "dryRun": true,
    "clientRequestId": "<UUID>"
  }'
```

### 视频预检

```bash
curl "https://0.0.0.0:3000/api/openapi/v1/generation/video" \
  -H "Authorization: Bearer $AI_HIVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "publicModelId": "<MODEL_ID>",
    "routingMode": "<ROUTING_MODE>",
    "prompt": "镜头缓慢推进，雨滴落在窗台",
    "params": {},
    "dryRun": true,
    "clientRequestId": "<UUID>"
  }'
```

正式提交时复用同一个请求体：把 `dryRun` 改为 `false`，加入预检返回的 `pricingSnapshot`，并保持 `clientRequestId` 不变。需要参考图或首尾帧时，先完成素材上传，再把 `mediaId` 放进 `imageMediaIds`、`videoMediaIds`、`audioMediaIds`、`firstFrameMediaId` 或 `lastFrameMediaId`。

### 查询任务

```bash
curl "https://0.0.0.0:3000/api/openapi/v1/generation/tasks/<TASK_ID>" \
  -H "Authorization: Bearer $AI_HIVE_API_KEY"
```

任务列表：`GET https://0.0.0.0:3000/api/openapi/v1/generation/tasks?page=1&pageSize=20`。任务状态和结果以查询接口返回为准。

### 上传素材

```bash
# 1. 申请上传地址
curl "https://0.0.0.0:3000/api/openapi/v1/media/upload-token" \
  -H "Authorization: Bearer $AI_HIVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "input.png",
    "contentType": "image/png",
    "sizeBytes": 12345
  }'
```

返回里有 `mediaId`、`upload.url`、`upload.method` 和 `upload.headers`。按返回的地址上传文件，`upload.headers` 里的每一个头都要带上：

```bash
# 2. 上传文件
curl -X PUT "<UPLOAD_URL>" \
  -H "<HEADER_NAME>: <HEADER_VALUE>" \
  --data-binary "@input.png"

# 3. 确认上传
curl -X POST "https://0.0.0.0:3000/api/openapi/v1/media/<MEDIA_ID>/complete" \
  -H "Authorization: Bearer $AI_HIVE_API_KEY"
```

上传完成后，素材可以在 Hive Chat 的用户消息里通过 `mediaIds` 引用，也可以在图片或视频请求里通过 `imageMediaIds` 等字段引用。

## 兼容协议

兼容协议只支持文字。先验证密钥：

```bash
curl "https://0.0.0.0:3000/api/openapi/native/v1/models" \
  -H "Authorization: Bearer $AI_HIVE_API_KEY"
```

### Chat Completions

```bash
curl "https://0.0.0.0:3000/api/openapi/native/v1/chat/completions" \
  -H "Authorization: Bearer $AI_HIVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<MODEL_ID>",
    "messages": [{"role": "user", "content": "你好"}]
  }'
```

### Responses

```bash
curl "https://0.0.0.0:3000/api/openapi/native/v1/responses" \
  -H "Authorization: Bearer $AI_HIVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<MODEL_ID>",
    "input": "你好"
  }'
```

### Anthropic Messages

```bash
curl "https://0.0.0.0:3000/api/openapi/native/v1/messages" \
  -H "Authorization: Bearer $AI_HIVE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "<MODEL_ID>",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "你好"}]
  }'
```

## 规则

- 先读模型列表和模型文档，不要猜字段；模型、参数和价格以接口返回为准。
- 图片和视频先发送 `dryRun: true` 预检；确认费用后再去掉 `dryRun` 正式生成。
- 正式提交前创建并保存 `clientRequestId`；网络重试复用原 ID 和原请求，不要重复创建付费任务。
- 失败先查任务和账单，不要未经确认就重建付费任务。

## 模型文档

按模型查看参数、请求示例和计费方式：https://0.0.0.0:3000/platform/docs

控制台页面需要登录；本接入说明是公开的。