# 产线平台模型 API 文档

---

# 模型治理统一推理 API

Base url: `https://pipeline.opencomputing.cn/pipeline-llm/api/v1`

所有 API 端点需要 Bearer Token 认证（短期 token，非真实模型 key）。

机构隔离：按 token 绑定的机构走治理链解析真实模型与密钥，真实密钥永不出服务进程。

---

## POST /v1/chat/completions

模型调用统一入口（OpenAI 兼容格式）。同步模型一次往返返回结果；异步模型（图生视频等）由服务端自动完成「提交任务 → 轮询 → 取结果」，返回落地后的本地持久地址。

### 必填参数

| 参数 | 类型 | 说明 |
|------|------|------|
| `messages` | array | 对话消息数组，`[{"role": "user", "content": "..."}]` |

### 可选参数

| 参数 | 类型 | 说明 |
|------|------|------|
| `model` | string | 模型名称（如 `happyhorse-1.1-i2v`）。不传 = 机构策略缺省模型（主→备链第一个） |
| `temperature` | float | 采样温度 |
| `tools` | array | 工具定义（t2t 模型，OpenAI 兼容） |
| `_purpose` | string | 用途标记：`utility` = 辅助任务（分类/选择/摘要），走辅助模型链 |
| `_timeout` | int | 单次调用超时秒数（0=端点默认；上限 900） |

### 异步模型额外参数（图生视频/文生视频/文生图等）

| 参数 | 类型 | 说明 |
|------|------|------|
| `image_file` | string | 上传媒体（base64/data URL 自动转本地公网地址；http(s) URL 原样使用）。**同类能力参数统一 `xxx_file` 命名** |
| `resolution` | string | 分辨率，如 `480P` / `720P` / `1080P` |
| `duration` | int | 视频时长（秒） |

> 生成物说明：上游返回的图片/视频等产物 URL 有效期极短（视频仅 24 小时），服务端会自动落地为本地持久文件再返回。

### 请求示例（文本对话）

```bash
curl -X POST 'https://pipeline.opencomputing.cn/pipeline-llm/api/v1/chat/completions' \
  -H 'Authorization: Bearer ***' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "qwen3.8-max",
    "messages": [{"role": "user", "content": "你好"}]
  }'
```

### 请求示例（图生视频，异步模型）

```bash
curl -X POST 'https://pipeline.opencomputing.cn/pipeline-llm/api/v1/chat/completions' \
  -H 'Authorization: Bearer ***' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "happyhorse-1.1-i2v",
    "messages": [{"role": "user", "content": "画面中的角色开始动感说唱"}],
    "image_file": "https://example.com/first-frame.png",
    "resolution": "720P",
    "duration": 5,
    "_timeout": 600
  }'
```

### 响应示例（同步模型）

```json
{
  "choices": [
    {"message": {"content": "你好！", "role": "assistant"}, "finish_reason": "stop"}
  ],
  "usage": {"prompt_tokens": 10, "completion_tokens": 5}
}
```

### 响应示例（异步模型）

```json
{
  "choices": [
    {"message": {"content": "https://pipeline.opencomputing.cn/idfile/tmp/.../xxx.mp4", "role": "assistant"},
     "finish_reason": "stop"}
  ],
  "usage": {"duration": 5, "SR": 720, "video_count": 1},
  "task_id": "e53dee87-...",
  "media": {
    "status": "SUCCEEDED",
    "video": "https://pipeline.opencomputing.cn/idfile/tmp/.../xxx.mp4",
    "usage": {"duration": 5, "SR": 720}
  }
}
```

`media` 字段是统一出参（同类能力字段一致）：视频 `video`、图片 `image`、3D 模型 `glb`。

### 错误响应

失败返回 OpenAI 错误结构，消息真实可行动（门禁不过/超时/模板配置缺失等都会给出具体原因）：

```json
{"error": {"message": "模型链全部不可用。最后原因：…", "type": "invalid_request_error", "code": "govern_error"}}
```

---

## GET /v1/models

按能力分类列出当前机构可用的模型（机构未配治理策略返回空列表）。

### 可选参数

| 参数 | 类型 | 说明 |
|------|------|------|
| `catelogid` | string | 能力分类：`t2t` / `t2i` / `i2v` / `t2v` / `embedding` / `rerank` / `tts` / `asr` / `i2t`。不传 = 全部 |

### 请求示例

```bash
curl 'https://pipeline.opencomputing.cn/pipeline-llm/api/v1/models?catelogid=i2v' \
  -H 'Authorization: Bearer ***'
```

### 响应示例

```json
{
  "object": "list",
  "data": [
    {"id": "happyhorse-1.1-i2v", "object": "model", "name": "happyhorse-1.1-i2v",
     "catelogid": "i2v", "vendor": "阿里云百炼"}
  ]
}
```

---

## 认证与短期 token

- token 由平台签发（绑定机构/项目/任务，含过期时间与调用上限，可吊销）
- 使用方式：`Authorization: Bearer ***
- token 不是真实模型密钥；真实密钥只在服务端解析，永不出进程

## 计费

- 调用自动产生用量流水（`llm_usage`），按模型挂的定价方案（ppid）异步出账
- 非 token 计价因子（视频时长/分辨率等）记录在流水的 `usages` 字段