155 lines
5.5 KiB
Markdown
155 lines
5.5 KiB
Markdown
# 파이프라인 플랫폼 모델 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` 필드에 저장됩니다
|