yumoqing/pipeline-llm
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
pipeline-llm/wwwroot/api/v1/docs/api_ko.md

5.5 KiB
Raw Blame History

파이프라인 플랫폼 모델 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시간뿐). 서버가 로컬에 영속화한 후 반환합니다.

요청 예시 (텍스트 대화)

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": "Alibaba Bailian"}
  ]
}

인증과 단기 토큰

  • 토큰은 플랫폼이 발급 (테넌트/프로젝트/작업에 연결, 만료 시간과 호출 상한 있음, 폐기 가능)
  • 사용 방법: `Authorization: Bearer ***
  • 토큰은 실제 모델 키가 아닙니다. 실제 키는 서버 측에서만 해결되며 프로세스 외부로 나가지 않습니다

과금

  • 호출마다 자동으로 사용량 기록 (llm_usage)이 생성되며, 모델에 연결된 요금제 (ppid) 기준으로 비동기 정산됩니다
  • 토큰 외 과금 요소 (비디오 길이/해상도 등)는 기록의 usages 필드에 저장됩니다