스타가 허락한 얼굴과 목소리를 API로
CELENOVA API로 본인이 허락한 스타를 찾고, 광고가 허락 범위에 맞는지 확인하고, 라이선스를 받아 광고를 만들 수 있습니다. 섭외, 계약, 스타 승인, 정산은 CELENOVA가 처리합니다.
이 문서는 공개 전 초안입니다. 주소, 필드, 금액은 확정되지 않았습니다.
무엇을 할 수 있나요
공개 표시는 누구나 샌드박스에서 쓸 수 있고, 파트너 전용 표시는 파트너 계약 후 열립니다.
인증
서버 간 호출은 OAuth 2.0 client credentials를 씁니다. 콘솔에서 발급한 client_id와 client_secret으로 토큰을 받아 모든 요청 헤더에 넣습니다. 토큰은 1시간 동안 유효합니다.
# 토큰 발급
curl -X POST https://api.celenova.studio/oauth/token \
-d grant_type=client_credentials \
-d client_id=$CELENOVA_CLIENT_ID \
-d client_secret=$CELENOVA_CLIENT_SECRET \
-d scope="models:read licenses:write"
# 호출
curl https://api.celenova.studio/v1/models \
-H "Authorization: Bearer $TOKEN"AI 에이전트용 MCP는 OAuth 2.1 로그인이나 API 키 헤더를 씁니다. MCP 서버를 보세요.
샌드박스
샌드박스 주소는 https://sandbox.api.celenova.studio/v1입니다. 실제 스타 대신 샘플 모델 5명이 들어 있고, 결제와 스타 승인은 자동으로 처리됩니다. 시안에는 "SAMPLE" 워터마크가 붙습니다.
모델
GET/v1/models공개
허락한 스타를 검색합니다. 썸네일은 항상 워터마크 이미지이고, 원본 사진은 어떤 응답에도 포함되지 않습니다.
| 쿼리 | 설명 |
|---|---|
| industry | 이 업종 광고를 허락한 모델만. 예: restaurant, beauty |
| era | 활동 시대. 예: 1990s |
| age_band | 현재 연령대. 예: 50s |
| assets | face, voice, motion 중 허락한 것 |
| max_price | 1개월 기본가 상한(원) |
{
"data": [{
"id": "mdl_8Kq2",
"stage_name": "샘플 모델 A",
"eras": ["1990s", "2000s"],
"assets": ["face", "voice"],
"thumbnail_url": "https://cdn.celenova.studio/wm/mdl_8Kq2.jpg",
"price_1m_krw": 1500000
}],
"next_cursor": null
}GET/v1/models/{id}공개
허락 범위(업종, 금지 표현, 지역), 기간별 가격, 독점 옵션 가능 여부를 돌려줍니다.
허락 범위 확인
POST/v1/clearances공개
광고를 만들기 전에 이 조건으로 쓸 수 있는지 확인합니다. 스타가 막은 항목과 법규 위반(예: 의료기기 AI 전문가 광고, 주류, 대부업)은 사유와 함께 거절합니다.
POST /v1/clearances
{
"model_id": "mdl_8Kq2",
"industry": "restaurant",
"media": ["instagram", "store_poster"],
"region": "서울 마포구",
"concept": "20년 단골집을 소개하는 따뜻한 영상"
}
→ 200
{ "allowed": true, "warnings": ["AI 생성 표시 필수"], "exclusive_available": true }견적과 라이선스
POST/v1/quotes공개
기간은 1·3·6·12개월이고 가격은 1개월 기본가의 1·2.5·4·7배입니다. 업종·지역 독점을 더하면 스타 단가가 [50]% 올라갑니다.
POST/v1/licenses파트너 전용
견적을 라이선스 요청으로 바꿉니다. 라이선스 1건은 광고 1건이며, 상태는 아래 순서로 바뀝니다.
스타가 거절하거나 [7]일 안에 답하지 않으면 rejected가 됩니다. 스타가 계약을 끝내면 revoked가 됩니다.
시안 생성
POST/v1/renders파트너 전용
귀사 모델로 만든 대역 인물 영상이나 이미지를 보내면, CELENOVA가 스타의 얼굴과 목소리를 입혀 워터마크 시안으로 돌려줍니다. 원본은 CELENOVA 밖으로 나가지 않습니다. 처리에 시간이 걸리므로 결과는 웹훅으로 알립니다.
POST /v1/renders
{
"license_id": "lic_3Fw9",
"input_url": "https://partner.example/standin.mp4",
"apply": ["face", "voice"],
"era": "1990s"
}
→ 202
{ "render_id": "rnd_71Ha", "status": "processing" }최종본과 스타 승인
POST/v1/licenses/{id}/final파트너 전용
편집을 마친 최종본을 올리면 스타에게 승인 요청이 갑니다. 승인되면 C2PA 메타데이터와 비가시 워터마크에 라이선스 토큰을 넣은 파일을 받을 수 있습니다. 승인 전에는 게재할 수 없습니다.
GET/v1/licenses/{id}파트너 전용
상태, 승인 결과, 거절 사유, 최종본 다운로드 링크(10분 유효)를 돌려줍니다.
사용 보고
POST/v1/usage-reports파트너 전용
게재 매체, 시작일, 종료일을 보고합니다. 정산은 매월 보고 기준으로 하고, 다음 달 [10]일에 지급합니다.
라이선스 확인
GET/v1/verify/{token}공개 · 인증 불필요
광고 파일에 들어 있는 토큰으로 정식 라이선스인지, 기간이 남았는지 누구나 확인할 수 있습니다. 매체사와 플랫폼의 광고 심사용입니다.
웹훅
| 이벤트 | 언제 |
|---|---|
| render.completed | 시안이 준비됨 |
| license.approved | 스타가 최종본을 승인함 |
| license.rejected | 스타가 거절함. 사유 포함 |
| license.expiring | 만료 7일 전 |
| license.revoked | 스타 계약 종료 등으로 사용 중단. 게재 내림 요청 |
모든 웹훅 요청에는 Celenova-Signature 헤더(HMAC-SHA256)가 붙습니다. 서명을 확인한 뒤 처리하세요.
MCP 서버
AI 에이전트에서 CELENOVA를 쓰려면 MCP 서버 주소 https://mcp.celenova.studio/mcp를 연결합니다. 전송 방식은 Streamable HTTP입니다. 도구는 위 API와 1:1로 대응합니다.
| 도구 | 하는 일 | API |
|---|---|---|
| search_models | 스타 검색 | GET /models |
| get_model_profile | 허락 범위·가격 | GET /models/{id} |
| check_ad_allowed | 허락 범위 확인 | POST /clearances |
| quote_license | 견적 | POST /quotes |
| request_license | 라이선스 요청. 결제는 웹 콘솔에서 | POST /licenses |
| create_draft_ad | 워터마크 시안 생성 | POST /renders |
| get_order_status | 진행 상태 | GET /licenses/{id} |
AI별 연결 방법
이용 정책
- 라이선스 1건은 광고 1건입니다. 업종, 매체, 지역, 기간을 벗어나 쓸 수 없습니다.
- 스타가 최종본을 승인하기 전에는 게재할 수 없습니다.
- 광고에 "AI 생성" 표시를 해야 합니다(공정위 추천·보증 심사지침).
- 워터마크와 C2PA 정보를 지우거나 바꾸면 안 됩니다.
- 받은 자료를 보관하거나, 모델 학습에 쓰거나, 다른 곳에 넘길 수 없습니다.
- 금지 업종과 표현은 API가 막습니다. 이를 피해 가면 즉시 차단되고 위약금 [3]배가 부과됩니다.