# 파이프라인 플랫폼 모델 API 문서

---

# 모델 거버넌스 통합 추론 API

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

모든 API 엔드포인트는 Bearer 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 | 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` 필드에 저장됩니다