SaaS API가이드라인 V4
컨셉 3개 생성 (Step 1)
사용자가 입력한 컨셉 텍스트 / 파일 / 참고 링크 기반으로 컨셉 3개 후보를 생성합니다.
컨셉 3개 생성
Python AI 서비스를 호출해 캠페인 컨셉 3개 후보를 생성하고 GuidelineDocument 세션에 저장합니다. 세션의 status 가 CONCEPTS_GENERATED 로 전이됩니다.
HTTP 요청
POST /ai/guideline/v4/{collabNo}/concepts
Authorization: Bearer {access_token}
Content-Type: application/jsonRequest Body
{
"conceptText": "...",
"fileUrls": ["https://..."],
"referenceLinks": ["https://..."],
"regenerate": false
}| 필드 | 타입 | 필수 | 설명 |
|---|---|---|---|
conceptText | String | 아니오 | 컨셉 자유 입력 텍스트 |
fileUrls | Array<String> | 아니오 | 참고 이미지/PDF 등 GCS URL |
referenceLinks | Array<String> | 아니오 | 참고 링크 |
regenerate | Boolean | 아니오 | true 면 기존 세션 컨셉을 previous_concepts 로 Python 에 전달 |
응답
성공 응답 (200 OK)
{
"status": 200,
"code": null,
"message": "컨셉 생성 완료",
"data": {
"concepts": [
{
"name": "컨셉 이름",
"description": "컨셉 상세 설명 텍스트",
"one_liner": "컨셉을 한 줄로 요약"
},
{ "name": "...", "description": "...", "one_liner": "..." },
{ "name": "...", "description": "...", "one_liner": "..." }
],
"gemini_file_ids": ["files/abc123", "files/def456"],
"pdf_metadata": {
"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": false
},
"product_link": {
"enabled": false,
"channel": null,
"link": null
},
"forbidden_expressions": ["최고", "1등"],
"required_mentions": ["#광고"],
"is_ai_suggested": true
},
"reference_metadata": {
"reels_metadata": [
{
"id": "reels_metadata_1",
"source_url": "https://www.instagram.com/reel/abc123/",
"hook_summary": "초반 1~3초의 시선 끌기 방식 요약",
"story_arc": "영상 전체 전개 방식 요약",
"video_flow": [
{
"part": "hook",
"time_range": "0-3초",
"visual": "클로즈업 장면 설명",
"text_or_caption": "화면 자막",
"audio_or_narration": "음성/음악",
"editing": "전환/편집",
"intent": "장면 의도"
}
],
"shooting_style": ["핸드헬드", "자연광"],
"editing_style": ["빠른 컷", "자막 강조"],
"text_overlay_style": "짧고 굵은 자막, 중앙 배치",
"product_or_scene_cues": ["제품 클로즈업", "사용 장면"],
"cta_or_ending": "프로필 링크 유도",
"reference_takeaways": ["훅 구성 참고", "전개 속도 참고"]
}
]
}
}
}data 필드 설명
| 필드 | 타입 | 설명 |
|---|---|---|
concepts | Array<ConceptItem> | 컨셉 3개 후보 |
concepts[].name | String | 컨셉 이름 |
concepts[].description | String | 컨셉 설명 |
concepts[].one_liner | String | 한 줄 요약 |
gemini_file_ids | Array<String> | 업로드된 Gemini 파일 ID (Step 2에서 재사용) |
pdf_metadata | PdfMetadata | null | PDF에서 추출한 메타데이터 (PDF 없으면 null) |
pdf_metadata.account_name | String | null | 브랜드 태그/협찬 레이블/공동 작업자에서 공통으로 쓰는 계정명 |
pdf_metadata.narration_required | Boolean | 나레이션 필수 여부 |
pdf_metadata.brand_tag | Object | 브랜드 계정 태그 설정. enabled, tag_methods 포함 |
pdf_metadata.brand_tag.tag_methods | Array<String> | PERSON_TAG, CAPTION_TAG |
pdf_metadata.sponsor_label | Object | 협찬/유료광고 레이블 설정. enabled, replace_ad_tag 포함 |
pdf_metadata.collaborator | Object | 공동 작업자 추가 설정. enabled 포함 |
pdf_metadata.product_link | Object | 제품 링크 공유 설정. PDF 추출 시 enabled=true, channel/link=null 가능 |
pdf_metadata.product_link.channel | String | null | DM, PROFILE, CAPTION, COMMENT. 저장 전 null이면 추가금 미확정 |
pdf_metadata.forbidden_expressions | Array<String> | 금지 표현 |
pdf_metadata.required_mentions | Array<String> | 필수 멘션 |
pdf_metadata.is_ai_suggested | Boolean | AI 추출 여부 |
reference_metadata | ReferenceMetadata | null | 참고 릴스 영상 흐름 메타데이터. 릴스 링크가 없으면 null |
reference_metadata.reels_metadata | Array<ReelsMetadataItem> | 릴스별 분석 결과 |
reference_metadata.reels_metadata[].id | String | 메타데이터 식별자 (reels_metadata_1, ...) |
reference_metadata.reels_metadata[].source_url | String | 원본 릴스 URL |
reference_metadata.reels_metadata[].hook_summary | String | 초반 훅 방식 요약 |
reference_metadata.reels_metadata[].story_arc | String | 영상 전체 전개 방식 |
reference_metadata.reels_metadata[].video_flow | Array<Object> | 초반/중반/후반 흐름 (3~6단계) |
reference_metadata.reels_metadata[].shooting_style | Array<String> | 촬영 스타일 |
reference_metadata.reels_metadata[].editing_style | Array<String> | 편집 스타일 |
reference_metadata.reels_metadata[].reference_takeaways | Array<String> | 컨셉 참고 포인트 |
부가 처리
geminiFileIds,pdfMetadata,referenceMetadata,concepts를 세션에 저장- 세션
expiresAt= 현재 + 48시간 (172,800초)