# 원경(Yuanjing) 플랫폼 API

원경 플랫폼은 하위 시스템을 위해 OpenAI 인터페이스 프로토콜과 호환되는 API를 제공합니다. API를 활성화하려면 하위 시스템에서 다음 단계를 수행해야 합니다:
* 계정 등록
* 로그인
* APIKEY 신청
* 충전

위 단계를 완료하면 다음 예시에 따라 텍스트 생성, 텍스트 기반 비디오(T2V), 이미지 기반 비디오(I2V), 참조 기반 비디오(R2V) 추론 서비스를 구현할 수 있습니다.

원경 플랫폼에서 지원하는 모델은 '모델 광장(Model Square)'을 참조하십시오.

## APIKEY 신청

사용자는 원경 플랫폼(https://ai.opencomputing.cn)에 모바일로 로그인한 후 "APIKEY 생성(创建APIKEY)"을 클릭해야 합니다.

정보를 입력하고 제출하면 APIKEY 생성이 완료됩니다.

"apikey 복사(复制apikey)"를 클릭하여 팝업 창에 표시된 apikey를 복사하십시오.

## 충전
사용자는 원경 플랫폼에서 충전을 진행해야 합니다. 현재 Alipay(알리페이)를 지원합니다.

## 현재 잔액 확인

* 사용자 로그인
* 사용자 메뉴 호출
* '재무(财务)' 클릭

## API 기본 URL
https://opencomputing.ai

## OpenAI 호환 인터페이스
OpenAI와 호환되는 일련의 API를 제공합니다.

### 텍스트 생성
* 경로: /llmage/v1/chat/completions
* 메서드: 'POST'
* 헤더
```
{
    "Content-Type": "application/json",
    "Authorization": "Bearer <your-apikey>"                # 원경 플랫폼에서 신청한 APIKEY
}
```
* 데이터
{
    "model":                # 모델 식별 코드 (공급업체가 제공한 모델 이름)
    "prompt":               # 프롬프트 (필수 입력)
    "sys_prompt"            # 시스템 프롬프트 (선택 사항)
    "stream"                # 스트림 출력 스위치
    "..."                   # 기타 매개변수
}

* 반환값
OpenAI 프로토콜을 준수하는 스트리밍 또는 비스트리밍 결과를 반환합니다.

* 스트리밍:
```
./oc.curl 你是谁
data: {"id": "chatcmpl-2665dfd8-e05f-9d7f-adff-3c53c174a454", "object": "chat.completion.chunk", "created": 1775019761, "choices": [{"logprobs": null, "index": 0, "delta": {"content": "", "role": "assistant"}}], "model": "qwen3-max", "reasoning_content": null, "content": "", "finish": "0", "llmusageid": "K9_veNBxeqvrFfbGWXs0R"}
...
data: [DONE]
```

* 비스트리밍
```
./oc.curl 你是谁
{"id": "chatcmpl-eea7abb9-24d5-9f70-b6f6-d7da4f22a8b8", "object": "chat.completion", "created": 1775011902, "choices": [{"finish_reason": "stop", "index": 0, "message": {"content": "我是通义千问...", "role": "assistant"}}], "model": "qwen3-max", "usage": {"total_tokens": 70}}
```

## 텍스트 기반 비디오 (Text-to-Video)
현재 지원되는 모델:
| 모델 ID | 제공사 | 모델 이름 |
|--------|--------|--------|
| o5vfXYD5BURJWRTWpopE5 | Alibaba Cloud | happyhorse-1.0-t2v |
| YjjGgxO_Xma8PWsMjJvps | Doubao | doubao-seedance-2-0-260128 |
| TWay-xd0p0pkEX-_Kuhto | We Token AI | dreamina-seedance-2-0-260128(*), dreamina-seedance-2-0-fast-260128 |
| CrEMkFQfRCmbmopZsCqLj | Doubao | doubao-seedance-1-5-pro-251215 |
| u9HZyfDoqU6uKI6M1BTks | Tongyi Wanxiang | wan2.6-t2v |
| r0ill7L0s6PtBS8mkmg-7 | vidu | viduq3-pro |

### happyhorse-1.0-t2v 업로드 요구 사항
| 필드명 (Name) | 유형 | 필수 여부 | 기본값 | 설명 |
| :--- | :--- | :--- | :--- | :--- |
| llmid | 모델 번호 | 예 | - | - |
| model | 모델 이름 | 아니요 | happyhorse-1.0-t2v | - |
| prompt | string | 예 | - | 프롬프트. 생성하려는 비디오 내용을 설명합니다. |
| resolution | string | 아니요 | `720p` | 비디오 해상도.<br>선택 가능 값:<br>`480p`, `720p`, `1080p` |
| ratio | string | 아니요 | adaptive | 화면 비율. 선택 가능 값: adaptive, 16:9, 4:3, 1:1, 3:4, 9:16, 21:9 |
| duration | integer | 아니요 | `5` | 비디오 길이(초).<br>선택 가능 값: 정수 |

### seedance 2.0 업로드 요구 사항
| 필드명 (Name) | 유형 | 필수 여부 | 기본값 | 설명 |
| :--- | :--- | :--- | :--- | :--- |
| llmid | 모델 번호 | 예 | - | - |
| model | 모델 이름 | 아니요 | doubao-seedance-2-0-260128 | doubao-seedance-2-0-260128 또는 doubao-seedance-2-0-fast-260128 |
| prompt | string | 예 | - | 프롬프트. 생성하려는 비디오 내용을 설명합니다. |
| resolution | string | 아니요 | `720p` | 비디오 해상도. |
| ratio | string | 아니요 | adaptive | 화면 비율. |
| duration | integer | 아니요 | `5` | 비디오 길이(초). |

### 완샹(Wanxiang) 업로드 요구 사항
| 필드명 (Name) | 유형 | 필수 여부 | 기본값 | 설명 |
| :--- | :--- | :--- | :--- | :--- |
| llmid | 모델 번호 | 예 | - | - |
| prompt | string | 예 | - | 프롬프트. 생성하려는 비디오 내용을 설명합니다. |
| negative_prompt | string | 아니요 | (비어 있음) | 부정 프롬프트. 비디오에 포함되지 않기를 바라는 내용을 설명합니다. |
| size | string | 아니요 | `1920*1080` | 비디오 크기.<br>선택 가능 값:<br>`1280*720`, `1920*1080` 등 |
| duration | integer | 아니요 | `15` | 비디오 길이(초).<br>선택 가능 값: `5`, `10`, `15` |

### 예시 (Example)
seedance를 사용한 예:
```
#!/usr/bin/env bash
curl -X POST https://opencomputing.ai/llmage/video \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-apikey-from-opencomputing.ai" \
  -d '{
        "llmid": "CrEMkFQfRCmbmopZsCqLj",
        "prompt": "小猫在抓老鼠",
        "duration": 5,
        "ratio": "16:9",
        "resolution": "480p"
    }'
```

## 이미지 기반 비디오 (Image-to-Video)
### 해피호스(Happy Horse) 업로드 요구 사항
첫 번째 프레임 기반 비디오 생성만 지원합니다.
| 필드명 (Name) | 유형 | 필수 여부 | 기본값 | 설명 |
| :--- | :--- | :--- | :--- | :--- |
| image1_file | 이미지 파일 | 예 | - | 첫 번째 프레임 이미지. |
| resolution | string | 아니요 | `720p` | 해상도. `720P`, `1080P` |

예시:
```
#!/usr/bin/env bash
curl -X POST https://opencomputing.ai/llmage/video \
  -H "Authorization: Bearer <your-apikey>" \
  -F "llmid=o5vfXYD5BURJWRTWpopE5" \
  -F "prompt=一起来调科目三" \
  -F "duration=15" \
  -F "resolution=720P" \
  -F "image1_file=@./02.jpg"
```

## 참조 기반 비디오 (Reference-to-Video)
### seedance 2.0 업로드 요구 사항
| 필드명 | 유형 | 필수 여부 | 기본값 | 설명 |
| :--- | :--- | :--- | :--- | :--- |
| image_files | 배열 | 예 | [] | 참조 이미지 배열. |
| video_files | 배열 | 아니요 | [] | 참조 비디오 배열. |

## 작업 제출
* 경로: /llmage/video
* 메서드: POST
* 헤더
```
{
    "Content-Type": "application/json",
    "Authorization": "Bearer <your-apikey>"             # 원경 플랫폼에서 신청한 APIKEY
}
```

* 반환값
```
{
    "taskid":                               # 작업 ID. 나중에 실행 결과 조회에 사용됩니다.
    "status":                               # 상태: SUCCEEDED, FAILED, CREATED, PENDING, RUNNING
}
```

## 작업 상태 조회
* 경로: /llmage/tasks
* 메서드: GET
* 헤더
```
{
    "Content-Type": "application/json",
    "Authorization": "Bearer <your-apikey>"
}
```
* 매개변수
```
{
    "taskid": "936759404378734592"
}
```
* 반환값
```
{
    "status":                           # 상태
    "usage":                            # status==SUCCEEDED일 때 유효. 과금 정보.
    "image":                            # 비디오 커버 URL
    "video":                            # 비디오 URL
}
```

## 오류 메시지

* 401: {"error": "Invalid API Key"} (유효하지 않은 API 키)
* 400: {"error": "Missing required parameter: prompt"} (필수 매개변수 누락)
* 429: {"error": "Insufficient balance"} (잔액 부족)