# パイプラインプラットフォーム モデル API ドキュメント

---

# モデルガバナンス統合推論 API

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

すべての API エンドポイントには Bearer Token 認証が必要です（短期トークン、実際のモデルキーではありません）。

テナント分離：トークンに紐づくテナントに基づきガバナンスチェーン経由で実際のモデルとキーを解決します。実際のキーはサーバープロセス外に出ません。

---

## POST /v1/chat/completions

モデル呼び出しの統一入口（OpenAI 互換形式）。同期モデルは1回の往復で結果を返します。非同期モデル（画像→動画など）はサーバーが自動的に「タスク送信 → ポーリング → 結果取得」を完了し、ローカルに永続化されたアドレスを返します。

### 必須パラメータ

| パラメータ | 型 | 説明 |
|------|------|------|
| `messages` | array | 対話メッセージ配列、`[{"role": "user", "content": "..."}]` |

### 任意パラメータ

| パラメータ | 型 | 説明 |
|------|------|------|
| `model` | string | モデル名（例：`happyhorse-1.1-i2v`）。未指定 = テナントポリシーのデフォルトモデル（プライマリ→バックアップチェーンの先頭） |
| `temperature` | float | サンプリング温度 |
| `tools` | array | ツール定義（t2t モデル、OpenAI 互換） |
| `_purpose` | string | 用途マーカー：`utility` = 補助タスク（分類/選択/要約）、補助モデルチェーンを使用 |
| `_timeout` | int | 1回の呼び出しのタイムアウト秒数（0=エンドポイントデフォルト；上限 900） |

### 非同期モデルの追加パラメータ（i2v / t2v / t2i など）

| パラメータ | 型 | 説明 |
|------|------|------|
| `image_file` | string | アップロードメディア（base64/data URL は自動的にローカル公開 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": "Alibaba Bailian"}
  ]
}
```

---

## 認証と短期トークン

- トークンはプラットフォームが発行（テナント/プロジェクト/タスクに紐づけ、有効期限と呼び出し上限あり、失効可能）
- 使用方法：`Authorization: Bearer ***
- トークンは実際のモデルキーではありません。実際のキーはサーバー側でのみ解決され、プロセス外に出ません

## 課金

- 呼び出しごとに自動的に使用量レコード（`llm_usage`）が作成され、モデルに紐づく料金プラン（ppid）に基づき非同期で請求されます
- トークン以外の課金要素（動画の長さ/解像度など）はレコードの `usages` フィールドに記録されます