API 문서

오픈 플랫폼 API 문서 (v1)

이 문서는 YinziAI 오픈 플랫폼 API 사용 방법을 설명합니다. 개발자는 API를 통해 주문 생성, 조회 등의 작업을 수행할 수 있습니다.

인증 (Authentication)

모든 인터페이스는 apiKey를 통한 인증이 필요합니다. 시스템은 세션이나 토큰에 의존하지 않고 apiKey를 기반으로 사용자를 식별합니다. "개인 센터" -> "API Key"에서 키를 얻을 수 있습니다.

인증 방식은 다음 두 가지를 지원합니다:

1. 헤더 인증 (권장)

   Authorization: Bearer <your_api_key>
   

2. 쿼리 파라미터 인증

   ?apiKey=<your_api_key>
   

기본 URL

https://api.yinziai.com

---

인터페이스 목록

1. 주문 생성 (Create Order)

비동기 처리 주문을 생성합니다. 시스템은 자동으로 주문 번호를 생성하여 반환합니다.

• URL: /api/open/v1/order/create
• Method: POST
• Content-Type: application/json

요청 파라미터

파라미터명	타입	필수	설명
orderType	string	예	주문 유형, 아래 열거 참조
stuff	object	예	소스 정보
stuff.pathKey	string	예	리소스 주소 (HTTP 링크 지원)

요청 예시

트랙 분리 (track-separation)

오디오를 보컬과 반주 두 개의 트랙으로 분리합니다.

{
  "orderType": "track-separation",
  "stuff": {
    "pathKey": "https://example.com/audio.mp3"
  }
}

보컬 추출 (extract-voice)

오디오에서 보컬 부분을 추출합니다.

{
  "orderType": "extract-voice",
  "stuff": {
    "pathKey": "https://example.com/audio.mp3"
  }
}

반주 추출 (extract-music)

오디오에서 반주/배경 음악 부분을 추출합니다.

{
  "orderType": "extract-music",
  "stuff": {
    "pathKey": "https://example.com/audio.mp3"
  }
}

텍스트 추출 (extract-text)

동영상이나 오디오에서 텍스트 내용을 추출합니다.

{
  "orderType": "extract-text",
  "stuff": {
    "pathKey": "https://example.com/video.mp4"
  }
}

응답 예시

{
  "code": 0,
  "data": {
    "orderNo": "abc123XYZ789defGHI",
    "orderType": "track-separation",
    "orderStatus": "processing",
    "payStatus": "waiting",
    "messageId": "task-id-123"
  },
  "msg": "success"
}

응답 필드 설명

필드	타입	설명
orderNo	string	주문 번호, 추후 조회에 사용
orderType	string	주문 유형
orderStatus	string	주문 상태
payStatus	string	결제 상태
messageId	string	작업 메시지 ID

---

2. 주문 조회 (Query Order)

주문의 처리 상태와 결과를 조회합니다. 주문 처리가 완료되면 처리 결과 다운로드 링크가 반환됩니다.

주의: 주문 완료 후 첫 조회 시 자동으로 크레딧이 차감됩니다.

• URL: /api/open/v1/order/query
• Method: GET

요청 파라미터

파라미터명	타입	필수	설명
orderNo	string	예	주문 번호

요청 예시

GET /api/open/v1/order/query?orderNo=abc123XYZ789defGHI
Authorization: Bearer <your_api_key>

응답 예시 (처리 중)

{
  "code": 0,
  "data": {
    "orderNo": "abc123XYZ789defGHI",
    "orderType": "track-separation",
    "status": "processing",
    "cost": 0,
    "reason": null,
    "stuffs": [],
    "balance": 1000
  },
  "msg": "success"
}

응답 예시 (처리 완료)

{
  "code": 0,
  "data": {
    "orderNo": "abc123XYZ789defGHI",
    "orderType": "track-separation",
    "status": "finish",
    "cost": 10,
    "reason": null,
    "stuffs": [
      {
        "name": "vocals.mp3",
        "business": "vocals",
        "url": "https://cdn.example.com/result/vocals.mp3"
      },
      {
        "name": "accompaniment.mp3",
        "business": "accompaniment",
        "url": "https://cdn.example.com/result/accompaniment.mp3"
      }
    ],
    "balance": 990
  },
  "msg": "success"
}

응답 필드 설명

필드	타입	설명
orderNo	string	주문 번호
orderType	string	주문 유형
status	string	주문 상태
cost	number	소모 크레딧
reason	string	실패 원인 (실패 시에만 값 있음)
stuffs	array	처리 결과 목록
stuffs[].name	string	파일명
stuffs[].business	string	업무 유형 (vocals/accompaniment/caption 등)
stuffs[].url	string	다운로드 링크 (유효기간 1시간)
balance	number	현재 사용자의 사용 가능한 크레딧 잔액

---

3. 쇼트 비디오 분석 (Short Video Analyze)

쇼트 비디오 공유 링크를 실시간으로 분석하여 동영상 정보와 워터마크 없는 다운로드 주소를 획득합니다.

주의: 이 인터페이스는 실시간 인터페이스이며, 즉시 크레딧이 차감되고 결과가 반환됩니다.

• URL: /api/open/v1/short-video/analyze
• Method: POST
• Content-Type: application/json

요청 파라미터

파라미터명	타입	필수	설명
link	string	예	쇼트 비디오 공유 링크

요청 예시

{
  "link": "https://v.douyin.com/ixxxxxx/"
}

응답 예시

{
  "code": 0,
  "data": {
    "title": "동영상 제목",
    "author": "작성자 닉네임",
    "cover": "https://cdn.example.com/cover.jpg",
    "videoUrl": "https://cdn.example.com/video.mp4",
    "musicUrl": "https://cdn.example.com/music.mp3",
    "balance": 990
  },
  "msg": "success"
}

응답 필드 설명

필드	타입	설명
title	string	동영상 제목
author	string	작성자 닉네임
cover	string	커버 이미지 주소
videoUrl	string	워터마크 없는 동영상 다운로드 주소
musicUrl	string	배경 음악 다운로드 주소 (있는 경우)
balance	number	현재 사용자의 사용 가능한 크레딧 잔액

---

에러 코드 설명

에러 코드	설명
0	성공
400	요청 파라미터 오류
401	인증 실패 (API Key 무효 또는 누락)
500	서버 내부 오류

일반적인 에러 메시지

에러 메시지	설명
API Key is required	API Key가 필요합니다
Invalid API Key	API Key가 유효하지 않습니다
pathKey is required	리소스 주소가 필요합니다
Order not found	주문이 존재하지 않거나 현재 사용자에게 속하지 않습니다
ErrorCode.USER_BLANCE_NOT_ENOUGH	크레딧 잔액 부족

---

부록

OrderType (주문 유형)

값	설명
track-separation	트랙 분리 (보컬과 반주 분리)
extract-voice	보컬 추출
extract-music	반주 추출
extract-text	텍스트 추출

OrderStatus (주문 상태)

값	설명
pending	대기 중
processing	처리 중
finish	완료
failed	실패
timeout	시간 초과

지원되는 쇼트 비디오 플랫폼

• Douyin (도우인)
• Kuaishou (콰이쇼우)
• Xiaohongshu (샤오홍슈)
• Weibo (웨이보)
• 기타 주류 쇼트 비디오 플랫폼