Star API

Star API 개발자 가이드

Star API가 포함된 파트너 계정의 외부 개발자를 위한 가이드입니다. 플랫폼을 Star에 연결해 피칭 수신, 캠페인 상태 추적, 핏 숏리스트 검토, 납품 에셋 가져오기, 웹훅 수신을 합니다. 데이터는 파트너 키 범위로만 보입니다.

베이스/api/star/v1

인증Bearer star_live_… / star_test_…

Star 시작하기 ← Star로 돌아가기

인증

모든 요청에 Star API가 견적에 포함된 회사용 파트너 API 키가 필요합니다. 라이브 키는 star_live_, 샌드박스는 star_test_로 시작합니다. 대시보드에서 생성 시 한 번만 보이므로 다른 비밀처럼 보관하세요.

Authorization: Bearer star_live_…

키가 응답 범위를 정합니다. 파트너 계정에 연결된 브리프, 숏리스트, 크리에이터만 받습니다. Star는 공개 로스터 디렉터리가 아닙니다.

브리프와 캠페인 파이프라인

캠페인 브리프를 제출한 뒤 Branch B 제작 상태를 읽습니다. 단계는 다음 순서입니다. RECEIVED → REVIEWED → PITCHED → GREENLIT → PRE_PROD → LIVE → DELIVERED.

POST /briefs

{
  "title": "Summer launch PV",
  "brief": "Music-led campaign for JP + EN audiences…",
  "brand": "Acme",
  "ownerName": "Maya Chen",
  "budgetNote": "Premium",
  "genres": ["J-pop"],
  "formats": ["Music video"],
  "languages": ["Japanese", "English"]
}

GET /briefs · GET /briefs/:id

브리프 목록 또는 id로 조회. 파이프라인 시각, daysInStage, 지연 플래그, 숏리스트, 납품 에셋을 포함합니다.

PATCH /briefs/:id

연동에 필요한 필드를 업데이트할 수 있습니다.

{ "stage": "PITCHED", "ownerName": "Maya Chen" }

핏이 있는 크리에이터 숏리스트

탐색 가능한 크리에이터 카탈로그는 없습니다. 브리프마다 숏리스트가 옵니다. 제안 크리에이터, 핏 이유(장르, 포맷, 언어, 검증 리치), 예상 조회 대역, 좌석 상태 PROPOSED / ACCEPTED / DECLINED.

POST /briefs/:id/shortlist

브리프 목표와 계정 필터에 맞는 로스터에서 좌석 제안을 요청합니다.

{ "action": "propose", "limit": 5 }

또는 크리에이터를 붙이고 좌석 결정을 직접 설정합니다.

{
  "creatorId": "clx…",
  "seatStatus": "ACCEPTED",
  "fitNote": "Strong EN anime audience, Live2D ready"
}

GET /briefs/:id/shortlist

이 브리프의 핏 카드만 반환합니다. 판정, 점수, 일치 태그, 이유, 예상 노출, 크리에이터 지표.

{
  "shortlist": [{
    "status": "PROPOSED",
    "fit": {
      "verdict": "Strong fit",
      "reasons": ["Genre match: J-pop", "Language match: English"],
      "matched": { "genres": ["J-pop"], "formats": [], "languages": ["English"] }
    },
    "estimatedImpressions": { "min": 80000, "max": 150000 },
    "creator": { "id": "…", "name": "…", "reach": 32000 }
  }]
}

크리에이터와 검증 지표

이미 숏리스트에 있는 크리에이터만 목록으로 줍니다. 언어, 장르, 포맷, 검증 팔로워, 평균 조회, 성장, lastCheckedAt 포함. 검색도 이 파트너 범위로 제한됩니다.

GET /creators?q=english
GET /creators/:id

납품 에셋

컷과 파이널이 준비되면 브리프에서 가져옵니다. DAM이나 검토 큐로 URL을 동기화할 수 있습니다.

PATCH /briefs/:id
{
  "asset": {
    "kind": "FINAL",
    "label": "Master 1080p",
    "url": "https://…",
    "deliveredAt": "2026-08-15T18:00:00.000Z"
  }
}

웹훅

서버의 HTTPS 엔드포인트를 등록합니다. 이벤트 발생 시 서명된 페이로드를 POST합니다. 시크릿이 발급되면 X-Star-Signature(sha256=…)를 검증하세요.

POST /webhooks
{
  "url": "https://your.app/hooks/star",
  "events": ["pitch.sent", "status.changed", "creator.accepted", "asset.ready"]
}

계정과 설정

파트너 계정을 읽고, 연동 필터(최소 팔로워, 플랫폼, 언어, 일시중지 제외)를 업데이트합니다.

GET /account
PATCH /account
{
  "config": {
    "minFollowers": 40000,
    "platforms": ["YOUTUBE"],
    "excludePaused": true,
    "languages": ["Japanese", "English"]
  }
}

내보내기

캠페인 CSV를 내려받아 스프레드시트나 오프라인 동기화에 사용합니다.

GET /export/briefs

이벤트 목록

brief.created: 새 브리프 제출
pitch.sent: 파이프라인 피칭 또는 숏리스트 제안
status.changed: 기타 단계 변경
creator.accepted / creator.declined: 크리에이터 좌석 수락 또는 거절
asset.ready: 납품 링크 첨부