SaaS API가이드라인 V4
전체 가이드라인 생성 (Step 2)
선택한 컨셉으로 가이드라인 전체(shots / appeal points / hashtags 등)를 생성합니다.
전체 가이드라인 생성
컨셉 생성 후 선택한 컨셉을 기반으로 가이드라인 본문을 생성합니다. 세션 status 가 GUIDELINE_GENERATED 로 전이됩니다.
HTTP 요청
POST /ai/guideline/v4/{collabNo}/generate
Authorization: Bearer {access_token}
Content-Type: application/jsonRequest Body
{
"conceptIndex": 0
}| 필드 | 타입 | 필수 | 설명 |
|---|---|---|---|
conceptIndex | Integer | 예 | concepts 배열에서 선택한 컨셉 인덱스 (0, 1, 2) |
촬영 옵션 적용
클라이언트는 생성 요청에서 촬영 옵션 목록을 직접 보내지 않습니다. Spring이 협업 정보의 카테고리/콘텐츠 타입을 기준으로 촬영 옵션을 구성해 Python 생성 API에 전달합니다.
- 기본 생성 구조는
beginningHOOK 1개,middle샷 3개,endingCTA 1개입니다. middle샷은 Spring이 전달한basicShots + additionalOptions후보 안에서만 생성됩니다.NARRATION은 촬영 샷이 아니므로 샷 후보에서 제외됩니다.- MongoDB 템플릿의
shootingOptions가 비어 있으면 Spring V4 fallback catalog를 사용합니다. basicShots후보는optionType=BASIC,additionalOptions후보는optionType=ADDITIONAL로 응답됩니다.- HOOK/CTA는 촬영 옵션 후보와 별개로 고정 생성되며
optionType=BASIC입니다. - 추가금 금액은 별도 DB sync 흐름에서 처리하므로 생성 응답에
price_tag를 내려주지 않습니다.
AI 생성 결과에 나올 수 있는 샷 코드
shots.middle[].code 는 아래 코드 중 하나로 내려갑니다. 프론트에서는 scene 문구가 아니라 code 와 optionType 을 기준으로 샷 종류를 매핑해야 합니다.
BASIC은 기본 촬영 옵션입니다.ADDITIONAL은 추가 촬영/추가금 옵션입니다.NARRATION은 촬영 샷이 아니므로 AI 생성 후보에서 제외됩니다.HOOK,CTA는 고정 장면 코드이며 아래 카테고리별 후보와 별개입니다.
| 카테고리 | BASIC 코드 | ADDITIONAL 코드 |
|---|---|---|
| 뷰티 | TEXTURE_SHOT, COLOR_SHOT, PACKAGE_SHOT, USAGE_SHOT, TIP_SHOT, ETC | BEFORE_AFTER, PROCEDURE, OUTDOOR |
| 패션 | MATERIAL_SHOT, UNBOXING_SHOT, STYLING_TIP_SHOT, LOOKBOOK_SHOT | OUTDOOR, BODY_EXPOSURE |
| 여행 | PRODUCT_INTRO_SHOT, ACCOMMODATION_SHOT, FOOD_SHOT, ACTIVITY_SHOT, LANDMARK_SHOT | BODY_EXPOSURE |
| 금융/비즈니스 | PRODUCT_INTRO_SHOT, USAGE_GUIDE_SHOT, COPYWRITING_SHOT, TIP_SHOT | - |
| 맛집/요리 | STORE_SHOT, COOKING_SHOT, TABLE_SHOT, TIP_SHOT, MENU_DESC_SHOT | - |
| IT | FEATURE_DEMO_SHOT, SCREEN_SHOT, USAGE_SCENE_SHOT, PRODUCT_DESC_SHOT | OUTDOOR |
| 운동/건강 | INGREDIENT_SHOT, PACKAGE_SHOT, USAGE_SHOT, ROUTINE_SHOT | BODY_EXPOSURE, BEFORE_AFTER, OUTDOOR |
| 육아/결혼 | PRODUCT_INTRO_SHOT, STRENGTH_SHOT, PACKAGE_SHOT, TIP_SHOT | CHILD_USAGE, BODY_EXPOSURE, OUTDOOR |
| 인테리어 | PRODUCT_INTRO_SHOT, MULTI_ANGLE_SHOT, STRENGTH_SHOT, PACKAGE_SHOT, FULL_VIEW_SHOT | FACE_EXPOSURE, OUTDOOR |
추가 촬영 코드 :
| 코드 | 의미 |
|---|---|
BEFORE_AFTER | 비포&애프터 샷 |
PROCEDURE | 시술 관련 샷 |
OUTDOOR | 야외/방문 촬영 |
BODY_EXPOSURE | 얼굴 외 다른 신체가 노출이 되는 촬영 |
CHILD_USAGE | 아이가 제품을 사용하는 샷 |
FACE_EXPOSURE | 얼굴이 노출되는 촬영 |
응답
성공 응답 (200 OK)
이 응답이 GuidelineDocument.data 에 그대로 저장됩니다.
{
"status": 200,
"code": null,
"message": "가이드라인 생성 완료",
"data": {
"concept_one_liner": "자연스러운 일상 속 제품 노출",
"shots": {
"beginning": [
{
"code": "HOOK",
"scene": "일상적인 모닝 루틴에서 제품을 자연스럽게 꺼내는 도입 장면",
"example_comment": "요즘 아침마다 꼭 챙기는 루틴이 있어요.",
"reference_url": null,
"optionType": "BASIC"
}
],
"middle": [
{
"code": "TEXTURE_SHOT",
"scene": "제품 제형을 손등에 덜어 질감이 보이도록 보여주는 장면",
"example_comment": "묽지 않고 부드럽게 밀착되는 제형이에요.",
"reference_url": null,
"optionType": "BASIC"
},
{
"code": "PACKAGE_SHOT",
"scene": "제품 패키지와 구성품을 한 화면에 정리해 보여주는 장면",
"example_comment": "패키지도 깔끔해서 선물용으로 괜찮더라고요.",
"reference_url": null,
"optionType": "BASIC"
},
{
"code": "BEFORE_AFTER",
"scene": "사용 전후 차이를 같은 구도로 비교해 보여주는 장면",
"example_comment": "전후 차이가 화면에서도 자연스럽게 보이죠.",
"reference_url": null,
"optionType": "ADDITIONAL"
}
],
"ending": [
{
"code": "CTA",
"scene": "제품 만족 포인트를 정리하며 구매/사용을 유도하는 마무리 장면",
"example_comment": "궁금한 분들은 상세 페이지에서 확인해보세요.",
"reference_url": null,
"optionType": "BASIC"
}
]
},
"used_shot_codes": ["TEXTURE_SHOT", "PACKAGE_SHOT", "BEFORE_AFTER"],
"remaining_shot_codes": ["COLOR_SHOT", "USAGE_SHOT", "TIP_SHOT", "ETC", "PROCEDURE", "OUTDOOR"],
"required_appeal_points": ["#광고 표기 필수", "브랜드 계정 태그"],
"optional_appeal_points": ["제품 사용감 언급", "구매 링크 안내"],
"hashtags": ["브랜드명", "제품명", "광고"],
"upload_requirements": {
"account_name": "brand_official",
"narration_required": false,
"brand_tag": {
"enabled": true,
"tag_methods": ["PERSON_TAG", "CAPTION_TAG"]
},
"sponsor_label": {
"enabled": true,
"replace_ad_tag": true
},
"collaborator": {
"enabled": true
},
"product_link": {
"enabled": true,
"channel": null,
"link": null
},
"is_ai_suggested": true
},
"reference_metadata": {
"reels_metadata": [
{
"id": "reels_metadata_1",
"source_url": "https://www.instagram.com/reel/abc123/",
"hook_summary": "초반 시선 끌기 요약",
"story_arc": "전개 방식 요약",
"video_flow": [ ... ],
"shooting_style": ["핸드헬드"],
"editing_style": ["빠른 컷"],
"text_overlay_style": "짧은 자막",
"product_or_scene_cues": ["제품 클로즈업"],
"cta_or_ending": "프로필 링크 유도",
"reference_takeaways": ["훅 구성 참고"]
}
]
}
}
}data 필드 설명
| 필드 | 타입 | 설명 |
|---|---|---|
concept_one_liner | String | 선택된 컨셉 한 줄 요약 |
shots | ShotsStructure | 장면 구조 (beginning / middle / ending) |
shots.beginning | Array<ShotItem> | 시작 장면. 기본 1개 HOOK |
shots.middle | Array<ShotItem> | 중간 장면. 촬영 옵션 후보에서 기본 3개 생성 |
shots.ending | Array<ShotItem> | 마무리 장면. 기본 1개 CTA |
ShotItem 구조
| 필드 | 타입 | 설명 |
|---|---|---|
code | String | 장면 코드. HOOK, CTA 또는 Spring 촬영 옵션 코드 |
scene | String | 장면 설명 |
example_comment | String | 예시 코멘트/나레이션 |
reference_url | String | null | 참고 URL |
optionType | String | BASIC 또는 ADDITIONAL |
기타 필드
| 필드 | 타입 | 설명 |
|---|---|---|
used_shot_codes | Array<String> | middle에서 사용된 촬영 후보 코드 목록 |
remaining_shot_codes | Array<String> | 아직 사용하지 않은 촬영 후보 코드. add-item에서 활용 |
required_appeal_points | Array<String> | 필수 어필 포인트 |
optional_appeal_points | Array<String> | 선택 어필 포인트 |
hashtags | Array<String> | 해시태그 |
upload_requirements | UploadRequirements | null | 업로드 요구사항 (PDF 메타데이터 기반) |
UploadRequirements 구조
| 필드 | 타입 | 설명 |
|---|---|---|
account_name | String | null | 브랜드 태그/협찬 레이블/공동 작업자에서 공통으로 쓰는 계정명 |
narration_required | Boolean | 나레이션 필수 여부 |
brand_tag | Object | 브랜드 계정 태그 설정. enabled, tag_methods 포함 |
brand_tag.tag_methods | Array<String> | PERSON_TAG, CAPTION_TAG |
sponsor_label | Object | 협찬/유료광고 레이블 설정. enabled, replace_ad_tag 포함 |
collaborator | Object | 공동 작업자 추가 설정. enabled 포함 |
product_link | Object | 제품 링크 공유 설정. AI 생성 단계에서는 enabled=true, channel/link=null 가능 |
product_link.channel | String | null | DM, PROFILE, CAPTION, COMMENT. 저장 전 null이면 추가금 미확정 |
is_ai_suggested | Boolean | AI 추출 여부 |
ReferenceMetadata — concepts 단계에서 반환된 참고 릴스 영상 흐름 메타데이터가 그대로 포함됩니다. 릴스가 없으면 null. 구조는 컨셉 생성 참고.
에러
IllegalArgumentException: 유효하지 않은 컨셉 인덱스 (세션에 컨셉 없거나 범위 초과)- 세션 미존재 시
"V4 세션이 없습니다. 컨셉 생성부터 시작하세요."