Glowb Dev Docs
SaaS API가이드라인 V4

전체 가이드라인 생성 (Step 2)

선택한 컨셉으로 가이드라인 전체(shots / appeal points / hashtags 등)를 생성합니다.

전체 가이드라인 생성

컨셉 생성 후 선택한 컨셉을 기반으로 가이드라인 본문을 생성합니다. 세션 statusGUIDELINE_GENERATED 로 전이됩니다.

HTTP 요청

POST /ai/guideline/v4/{collabNo}/generate
Authorization: Bearer {access_token}
Content-Type: application/json

Request Body

{
  "conceptIndex": 0
}
필드타입필수설명
conceptIndexIntegerconcepts 배열에서 선택한 컨셉 인덱스 (0, 1, 2)

촬영 옵션 적용

클라이언트는 생성 요청에서 촬영 옵션 목록을 직접 보내지 않습니다. Spring이 협업 정보의 카테고리/콘텐츠 타입을 기준으로 촬영 옵션을 구성해 Python 생성 API에 전달합니다.

  • 기본 생성 구조는 beginning HOOK 1개, middle 샷 3개, ending CTA 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 문구가 아니라 codeoptionType 을 기준으로 샷 종류를 매핑해야 합니다.

  • BASIC 은 기본 촬영 옵션입니다.
  • ADDITIONAL 은 추가 촬영/추가금 옵션입니다.
  • NARRATION 은 촬영 샷이 아니므로 AI 생성 후보에서 제외됩니다.
  • HOOK, CTA 는 고정 장면 코드이며 아래 카테고리별 후보와 별개입니다.
카테고리BASIC 코드ADDITIONAL 코드
뷰티TEXTURE_SHOT, COLOR_SHOT, PACKAGE_SHOT, USAGE_SHOT, TIP_SHOT, ETCBEFORE_AFTER, PROCEDURE, OUTDOOR
패션MATERIAL_SHOT, UNBOXING_SHOT, STYLING_TIP_SHOT, LOOKBOOK_SHOTOUTDOOR, BODY_EXPOSURE
여행PRODUCT_INTRO_SHOT, ACCOMMODATION_SHOT, FOOD_SHOT, ACTIVITY_SHOT, LANDMARK_SHOTBODY_EXPOSURE
금융/비즈니스PRODUCT_INTRO_SHOT, USAGE_GUIDE_SHOT, COPYWRITING_SHOT, TIP_SHOT-
맛집/요리STORE_SHOT, COOKING_SHOT, TABLE_SHOT, TIP_SHOT, MENU_DESC_SHOT-
ITFEATURE_DEMO_SHOT, SCREEN_SHOT, USAGE_SCENE_SHOT, PRODUCT_DESC_SHOTOUTDOOR
운동/건강INGREDIENT_SHOT, PACKAGE_SHOT, USAGE_SHOT, ROUTINE_SHOTBODY_EXPOSURE, BEFORE_AFTER, OUTDOOR
육아/결혼PRODUCT_INTRO_SHOT, STRENGTH_SHOT, PACKAGE_SHOT, TIP_SHOTCHILD_USAGE, BODY_EXPOSURE, OUTDOOR
인테리어PRODUCT_INTRO_SHOT, MULTI_ANGLE_SHOT, STRENGTH_SHOT, PACKAGE_SHOT, FULL_VIEW_SHOTFACE_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_linerString선택된 컨셉 한 줄 요약
shotsShotsStructure장면 구조 (beginning / middle / ending)
shots.beginningArray<ShotItem>시작 장면. 기본 1개 HOOK
shots.middleArray<ShotItem>중간 장면. 촬영 옵션 후보에서 기본 3개 생성
shots.endingArray<ShotItem>마무리 장면. 기본 1개 CTA

ShotItem 구조

필드타입설명
codeString장면 코드. HOOK, CTA 또는 Spring 촬영 옵션 코드
sceneString장면 설명
example_commentString예시 코멘트/나레이션
reference_urlString | null참고 URL
optionTypeStringBASIC 또는 ADDITIONAL

기타 필드

필드타입설명
used_shot_codesArray<String>middle에서 사용된 촬영 후보 코드 목록
remaining_shot_codesArray<String>아직 사용하지 않은 촬영 후보 코드. add-item에서 활용
required_appeal_pointsArray<String>필수 어필 포인트
optional_appeal_pointsArray<String>선택 어필 포인트
hashtagsArray<String>해시태그
upload_requirementsUploadRequirements | null업로드 요구사항 (PDF 메타데이터 기반)

UploadRequirements 구조

필드타입설명
account_nameString | null브랜드 태그/협찬 레이블/공동 작업자에서 공통으로 쓰는 계정명
narration_requiredBoolean나레이션 필수 여부
brand_tagObject브랜드 계정 태그 설정. enabled, tag_methods 포함
brand_tag.tag_methodsArray<String>PERSON_TAG, CAPTION_TAG
sponsor_labelObject협찬/유료광고 레이블 설정. enabled, replace_ad_tag 포함
collaboratorObject공동 작업자 추가 설정. enabled 포함
product_linkObject제품 링크 공유 설정. AI 생성 단계에서는 enabled=true, channel/link=null 가능
product_link.channelString | nullDM, PROFILE, CAPTION, COMMENT. 저장 전 null이면 추가금 미확정
is_ai_suggestedBooleanAI 추출 여부

ReferenceMetadata — concepts 단계에서 반환된 참고 릴스 영상 흐름 메타데이터가 그대로 포함됩니다. 릴스가 없으면 null. 구조는 컨셉 생성 참고.

에러

  • IllegalArgumentException: 유효하지 않은 컨셉 인덱스 (세션에 컨셉 없거나 범위 초과)
  • 세션 미존재 시 "V4 세션이 없습니다. 컨셉 생성부터 시작하세요."

API 테스트

On this page