pipeline-llm/wwwroot/api/v1/docs/api_zh.md

产线平台模型 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 小时），服务端会自动落地为本地持久文件再返回。

请求示例（文本对话）

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": "你好"}]
  }'

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

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
  }'

响应示例（同步模型）

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

响应示例（异步模型）

{
  "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 错误结构，消息真实可行动（门禁不过/超时/模板配置缺失等都会给出具体原因）：

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

---

GET /v1/models

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

可选参数

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

请求示例

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

响应示例

{
  "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 字段