API Reference

Reels QUELSUITE Developer API Reference

Base URLhttps://reels.quelsuite.com

Authentication

모든 API 요청에는 Authorization 헤더에 Bearer 토큰을 포함해야 합니다. API 키는 qsk_live_ 접두사로 시작하며 총 52자입니다.

header

Authorization: Bearer qsk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

API 키는 /developer 페이지에서 발급받을 수 있습니다. 키는 생성 시 한 번만 표시되므로 안전한 곳에 보관하세요.

Render API

POST/api/v1/render

이미지 또는 동영상 소스를 전달하면 AI가 자동으로 마케팅 숏폼 영상을 생성합니다. 렌더링은 비동기로 진행되며, 완료 시 webhook_url로 결과가 전송되거나 상태 조회 API로 폴링할 수 있습니다.

Headers

헤더	값	필수
`Authorization`	Bearer qsk_live_...	✓
`Content-Type`	application/json	✓

Request Body

필드	타입	필수	설명
`images`	string[]	✓	Base64 인코딩 이미지. data:image/jpeg;base64,... 형식. 최대 8장
`videos`	string[]	—	Base64 인코딩 동영상. data:video/mp4;base64,... 형식
`product`	object	—	상품 메타데이터
`product.category`	string	—	상품 카테고리 (예: `"전자기기"`)
`product.brand`	string	—	브랜드명 (예: `"삼성"`)
`product.name`	string	—	상품명 (예: `"갤럭시 S25"`)
`product.details`	string	—	상품 상세 설명
`selling_points`	string[]	—	셀링포인트 배열. 최대 10개
`mode`	string	—	기본값: `"marketing"`. 가능한 값: `marketing`, `vlog`, `review`, `educational`, `lifestyle`
`tone`	string	—	기본값: `"informative"`. 가능한 값: `trendy`, `funny`, `informative`, `premium`, `energetic`, `emotional`
`bgm`	string	—	기본값: `"upbeat"`. 가능한 값: `upbeat`, `calm`, `none`
`webhook_url`	string	—	렌더 완료 시 POST 호출할 URL

요청 예시

bash

curl -X POST https://reels.quelsuite.com/api/v1/render \
  -H "Authorization: Bearer qsk_live_xxxx...xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "images": ["data:image/jpeg;base64,/9j/4AAQ..."],
    "product": {
      "category": "전자기기",
      "brand": "삼성",
      "name": "갤럭시 S25",
      "details": "6.2인치 다이나믹 아몰레드 디스플레이"
    },
    "selling_points": [
      "역대 가장 얇은 디자인",
      "AI 실시간 통역"
    ],
    "mode": "marketing",
    "tone": "trendy",
    "bgm": "upbeat",
    "webhook_url": "https://your-server.com/webhook"
  }'

응답 (200)

json

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "queued",
  "usage": { "calls_used": 42, "calls_limit": 200 }
}

Status

GET/api/v1/render/{jobId}

렌더링 작업의 현재 상태를 조회합니다. completed 상태가 될 때까지 폴링하세요. 권장 간격: 3~5초.

URL 파라미터

파라미터	타입	설명
`jobId`	UUID	렌더 API 응답에서 받은 job_id

상태 값

상태	설명
`queued`	대기 중. 서버 리소스 확보 대기
`processing`	렌더링 중. AI 분석 및 영상 합성 진행 중
`completed`	완료. video_url 필드에 다운로드 URL 포함
`failed`	실패. error 필드에 에러 코드 포함

응답 (completed)

json

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "video_url": "https://reels.quelsuite.com/rendered/550e8400.mp4",
  "duration": 15.2,
  "created_at": "2026-03-01T12:00:00Z",
  "completed_at": "2026-03-01T12:01:32Z"
}

응답 (failed)

json

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "failed",
  "error": "ai_analysis_failed",
  "message": "이미지에서 상품을 인식할 수 없습니다",
  "created_at": "2026-03-01T12:00:00Z"
}

Analyze API

POST/api/v1/analyze

이미지를 AI로 분석하여 스토리 레이어, 캡션, 해시태그 등 마케팅 데이터를 JSON으로 반환합니다. 렌더링은 수행하지 않으며, 분석 결과만 즉시 응답합니다.

Request Body

필드	타입	필수	설명
`images`	string[]	✓	Base64 인코딩 이미지. data:image/jpeg;base64,... 형식. 최대 8장
`product`	object	—	상품 메타데이터 (product.category, product.brand, product.name, product.details)
`selling_points`	string[]	—	셀링포인트 배열. 최대 10개
`mode`	string	—	기본값: `"marketing"`. 가능한 값: `marketing`, `vlog`, `review`, `educational`, `lifestyle`
`tone`	string	—	기본값: `"informative"`. 가능한 값: `trendy`, `funny`, `informative`, `premium`, `energetic`, `emotional`

요청 예시

bash

curl -X POST https://reels.quelsuite.com/api/v1/analyze \
  -H "Authorization: Bearer qsk_live_xxxx...xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "images": ["data:image/jpeg;base64,/9j/4AAQ..."],
    "product": {
      "category": "패션",
      "brand": "ZARA",
      "name": "오버사이즈 블레이저"
    },
    "selling_points": ["트렌디한 핏", "데일리룩 필수템"],
    "mode": "review",
    "tone": "trendy"
  }'

응답 (200)

json

{
  "story_layers": [
    {
      "text": "이건 진짜 달라요",
      "narrative_role": "hook",
      "animation": "zoom",
      "style_preset": "bold_outline"
    }
  ],
  "caption": "당신의 스타일을 완성할 아이템",
  "hashtags": ["#신상", "#추천템", "#꿀템"],
  "best_posting_time": "18:30",
  "usage": { "calls_used": 43, "calls_limit": 200 }
}

Error Codes

에러 발생 시 응답 본문에 error 코드와 message가 포함됩니다.

HTTP 상태	코드	설명
400	`invalid_json`	요청 본문이 올바른 JSON이 아님
400	`missing_images`	images 배열이 비어있거나 없음
401	`invalid_key_format`	Authorization 헤더 형식이 올바르지 않음
401	`invalid_key`	API 키가 유효하지 않거나 삭제됨
403	`insufficient_credits`	크레딧 부족. /developer 페이지에서 충전 필요
404	`job_not_found`	렌더 작업을 찾을 수 없음
500	`ai_analysis_failed`	AI 분석 처리 실패
500	`render_failed`	렌더링 작업 생성 실패

에러 응답 예시

json

{
  "error": "missing_images",
  "message": "images 배열이 비어있거나 제공되지 않았습니다."
}

금방 갈게잉~Almost there!もうすぐだよ！馬上就好囉～Sắp xong rồi!เดี๋ยวนะ～Bentar ya~Gleich da!Ya casi!거의 다 왔어!Quase lá!すぐ行くよ！금방 갈게잉~Almost there!もうすぐだよ！馬上就好囉～Sắp xong rồi!เดี๋ยวนะ～Bentar ya~Gleich da!Ya casi!거의 다 왔어!Quase lá!すぐ行くよ！

On y va !Hang tight~快好了！Uda mau jadi~โหลดอยู่นะ잠깐만~Wait for it...Presque!もうちょい！Sebentar~Subito!곧이야~On y va !Hang tight~快好了！Uda mau jadi~โหลดอยู่นะ잠깐만~Wait for it...Presque!もうちょい！Sebentar~Subito!곧이야~

조금만 기다려~Coming right up!ちょっと待ってね等一下喔～Tunggu ya~รอแป๊บนะUn momento!Gleich fertig!Casi listo!이제 곧!ほぼ完了！Pronto!조금만 기다려~Coming right up!ちょっと待ってね等一下喔～Tunggu ya~รอแป๊บนะUn momento!Gleich fertig!Casi listo!이제 곧!ほぼ完了！Pronto!

얼른 갈게~Bientôt!Just a sec~もう少し！다 됐어!Here we go!Yuk tunggu~กำลังมา～준비 중~Loading...Patience~少々お待ちを얼른 갈게~Bientôt!Just a sec~もう少し！다 됐어!Here we go!Yuk tunggu~กำลังมา～준비 중~Loading...Patience~少々お待ちを

Developer/API Docs

API Reference

Reels QUELSUITE Developer API Reference

Base URLhttps://reels.quelsuite.com

Authentication

모든 API 요청에는 Authorization 헤더에 Bearer 토큰을 포함해야 합니다. API 키는 qsk_live_ 접두사로 시작하며 총 52자입니다.

header

Authorization: Bearer qsk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

API 키는 /developer 페이지에서 발급받을 수 있습니다. 키는 생성 시 한 번만 표시되므로 안전한 곳에 보관하세요.

Render API

POST/api/v1/render

Headers

헤더	값	필수
`Authorization`	Bearer qsk_live_...	✓
`Content-Type`	application/json	✓

Request Body

필드	타입	필수	설명
`images`	string[]	✓	Base64 인코딩 이미지. data:image/jpeg;base64,... 형식. 최대 8장
`videos`	string[]	—	Base64 인코딩 동영상. data:video/mp4;base64,... 형식
`product`	object	—	상품 메타데이터
`product.category`	string	—	상품 카테고리 (예: `"전자기기"`)
`product.brand`	string	—	브랜드명 (예: `"삼성"`)
`product.name`	string	—	상품명 (예: `"갤럭시 S25"`)
`product.details`	string	—	상품 상세 설명
`selling_points`	string[]	—	셀링포인트 배열. 최대 10개
`mode`	string	—	기본값: `"marketing"`. 가능한 값: `marketing`, `vlog`, `review`, `educational`, `lifestyle`
`tone`	string	—	기본값: `"informative"`. 가능한 값: `trendy`, `funny`, `informative`, `premium`, `energetic`, `emotional`
`bgm`	string	—	기본값: `"upbeat"`. 가능한 값: `upbeat`, `calm`, `none`
`webhook_url`	string	—	렌더 완료 시 POST 호출할 URL

요청 예시

bash

curl -X POST https://reels.quelsuite.com/api/v1/render \
  -H "Authorization: Bearer qsk_live_xxxx...xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "images": ["data:image/jpeg;base64,/9j/4AAQ..."],
    "product": {
      "category": "전자기기",
      "brand": "삼성",
      "name": "갤럭시 S25",
      "details": "6.2인치 다이나믹 아몰레드 디스플레이"
    },
    "selling_points": [
      "역대 가장 얇은 디자인",
      "AI 실시간 통역"
    ],
    "mode": "marketing",
    "tone": "trendy",
    "bgm": "upbeat",
    "webhook_url": "https://your-server.com/webhook"
  }'

응답 (200)

json

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "queued",
  "usage": { "calls_used": 42, "calls_limit": 200 }
}

Status

GET/api/v1/render/{jobId}

렌더링 작업의 현재 상태를 조회합니다. completed 상태가 될 때까지 폴링하세요. 권장 간격: 3~5초.

URL 파라미터

파라미터	타입	설명
`jobId`	UUID	렌더 API 응답에서 받은 job_id

상태 값

상태	설명
`queued`	대기 중. 서버 리소스 확보 대기
`processing`	렌더링 중. AI 분석 및 영상 합성 진행 중
`completed`	완료. video_url 필드에 다운로드 URL 포함
`failed`	실패. error 필드에 에러 코드 포함

응답 (completed)

json

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "video_url": "https://reels.quelsuite.com/rendered/550e8400.mp4",
  "duration": 15.2,
  "created_at": "2026-03-01T12:00:00Z",
  "completed_at": "2026-03-01T12:01:32Z"
}

응답 (failed)

json

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "failed",
  "error": "ai_analysis_failed",
  "message": "이미지에서 상품을 인식할 수 없습니다",
  "created_at": "2026-03-01T12:00:00Z"
}

Analyze API

POST/api/v1/analyze

Request Body

필드	타입	필수	설명
`images`	string[]	✓	Base64 인코딩 이미지. data:image/jpeg;base64,... 형식. 최대 8장
`product`	object	—	상품 메타데이터 (product.category, product.brand, product.name, product.details)
`selling_points`	string[]	—	셀링포인트 배열. 최대 10개
`mode`	string	—	기본값: `"marketing"`. 가능한 값: `marketing`, `vlog`, `review`, `educational`, `lifestyle`
`tone`	string	—	기본값: `"informative"`. 가능한 값: `trendy`, `funny`, `informative`, `premium`, `energetic`, `emotional`

요청 예시

bash

curl -X POST https://reels.quelsuite.com/api/v1/analyze \
  -H "Authorization: Bearer qsk_live_xxxx...xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "images": ["data:image/jpeg;base64,/9j/4AAQ..."],
    "product": {
      "category": "패션",
      "brand": "ZARA",
      "name": "오버사이즈 블레이저"
    },
    "selling_points": ["트렌디한 핏", "데일리룩 필수템"],
    "mode": "review",
    "tone": "trendy"
  }'

응답 (200)

json

{
  "story_layers": [
    {
      "text": "이건 진짜 달라요",
      "narrative_role": "hook",
      "animation": "zoom",
      "style_preset": "bold_outline"
    }
  ],
  "caption": "당신의 스타일을 완성할 아이템",
  "hashtags": ["#신상", "#추천템", "#꿀템"],
  "best_posting_time": "18:30",
  "usage": { "calls_used": 43, "calls_limit": 200 }
}

Error Codes

에러 발생 시 응답 본문에 error 코드와 message가 포함됩니다.

HTTP 상태	코드	설명
400	`invalid_json`	요청 본문이 올바른 JSON이 아님
400	`missing_images`	images 배열이 비어있거나 없음
401	`invalid_key_format`	Authorization 헤더 형식이 올바르지 않음
401	`invalid_key`	API 키가 유효하지 않거나 삭제됨
403	`insufficient_credits`	크레딧 부족. /developer 페이지에서 충전 필요
404	`job_not_found`	렌더 작업을 찾을 수 없음
500	`ai_analysis_failed`	AI 분석 처리 실패
500	`render_failed`	렌더링 작업 생성 실패

에러 응답 예시

json

{
  "error": "missing_images",
  "message": "images 배열이 비어있거나 제공되지 않았습니다."
}