{
  "components": {
    "schemas": {
      "AnalysisFieldCatalogItem": {
        "properties": {
          "aggregate_field_key": {
            "default": "",
            "title": "Aggregate Field Key",
            "type": "string"
          },
          "aliases": {
            "items": {
              "type": "string"
            },
            "title": "Aliases",
            "type": "array"
          },
          "allows_free_value": {
            "default": false,
            "title": "Allows Free Value",
            "type": "boolean"
          },
          "created_at": {
            "anyOf": [
              {
                "format": "date-time",
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Created At"
          },
          "db_column": {
            "default": "",
            "title": "Db Column",
            "type": "string"
          },
          "default_operator": {
            "default": "",
            "title": "Default Operator",
            "type": "string"
          },
          "description": {
            "default": "",
            "title": "Description",
            "type": "string"
          },
          "display_name": {
            "default": "",
            "title": "Display Name",
            "type": "string"
          },
          "examples": {
            "items": {},
            "title": "Examples",
            "type": "array"
          },
          "field_key": {
            "title": "Field Key",
            "type": "string"
          },
          "is_active": {
            "default": true,
            "title": "Is Active",
            "type": "boolean"
          },
          "is_llm_output": {
            "default": true,
            "title": "Is Llm Output",
            "type": "boolean"
          },
          "is_promptable": {
            "default": true,
            "title": "Is Promptable",
            "type": "boolean"
          },
          "is_searchable": {
            "default": false,
            "title": "Is Searchable",
            "type": "boolean"
          },
          "item_type": {
            "title": "Item Type",
            "type": "string"
          },
          "max_value": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ],
            "title": "Max Value"
          },
          "metadata": {
            "additionalProperties": true,
            "title": "Metadata",
            "type": "object"
          },
          "min_value": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ],
            "title": "Min Value"
          },
          "parent_field_key": {
            "default": "",
            "title": "Parent Field Key",
            "type": "string"
          },
          "parent_value_key": {
            "default": "",
            "title": "Parent Value Key",
            "type": "string"
          },
          "prompt_hint": {
            "default": "",
            "title": "Prompt Hint",
            "type": "string"
          },
          "sort_order": {
            "default": 0,
            "title": "Sort Order",
            "type": "integer"
          },
          "source": {
            "default": "",
            "title": "Source",
            "type": "string"
          },
          "updated_at": {
            "anyOf": [
              {
                "format": "date-time",
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Updated At"
          },
          "value_key": {
            "default": "",
            "title": "Value Key",
            "type": "string"
          },
          "value_type": {
            "default": "string",
            "title": "Value Type",
            "type": "string"
          }
        },
        "required": [
          "item_type",
          "field_key"
        ],
        "title": "AnalysisFieldCatalogItem",
        "type": "object"
      },
      "CreatorAdFitPresetItem": {
        "description": "외부 서비스가 선택할 수 있는 creator 광고 적합성 프리셋.",
        "properties": {
          "created_at": {
            "anyOf": [
              {
                "format": "date-time",
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Created At"
          },
          "criteria": {
            "additionalProperties": true,
            "title": "Criteria",
            "type": "object"
          },
          "is_default": {
            "default": false,
            "title": "Is Default",
            "type": "boolean"
          },
          "owner_email": {
            "default": "",
            "title": "Owner Email",
            "type": "string"
          },
          "preset_name": {
            "title": "Preset Name",
            "type": "string"
          },
          "updated_at": {
            "anyOf": [
              {
                "format": "date-time",
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Updated At"
          }
        },
        "required": [
          "preset_name",
          "criteria"
        ],
        "title": "CreatorAdFitPresetItem",
        "type": "object"
      },
      "CreatorFeeAdjustment": {
        "properties": {
          "code": {
            "description": "적용한 modifier 코드입니다.",
            "title": "Code",
            "type": "string"
          },
          "fee_delta_usd": {
            "$ref": "#/components/schemas/CreatorFeeRange",
            "description": "modifier로 더하거나 뺀 금액입니다."
          },
          "max_rate": {
            "description": "최대 fee에 적용한 조정률입니다.",
            "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$",
            "title": "Max Rate",
            "type": "string"
          },
          "min_rate": {
            "description": "최소 fee에 적용한 조정률입니다.",
            "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$",
            "title": "Min Rate",
            "type": "string"
          },
          "reason": {
            "description": "modifier 적용 근거입니다.",
            "title": "Reason",
            "type": "string"
          }
        },
        "required": [
          "code",
          "min_rate",
          "max_rate",
          "fee_delta_usd",
          "reason"
        ],
        "title": "CreatorFeeAdjustment",
        "type": "object"
      },
      "CreatorFeeBenchmarkInfo": {
        "properties": {
          "category": {
            "const": "beauty",
            "default": "beauty",
            "title": "Category",
            "type": "string"
          },
          "currency": {
            "const": "USD",
            "default": "USD",
            "title": "Currency",
            "type": "string"
          },
          "source_reviewed_at": {
            "description": "benchmark 검토 기준일입니다.",
            "title": "Source Reviewed At",
            "type": "string"
          },
          "source_url": {
            "description": "benchmark 출처 URL입니다.",
            "title": "Source Url",
            "type": "string"
          },
          "version": {
            "description": "적용한 fee benchmark 버전입니다.",
            "title": "Version",
            "type": "string"
          }
        },
        "required": [
          "version",
          "source_url",
          "source_reviewed_at"
        ],
        "title": "CreatorFeeBenchmarkInfo",
        "type": "object"
      },
      "CreatorFeeMetricInfo": {
        "properties": {
          "creator_followers": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "description": "snapshot 기준 팔로워 수입니다.",
            "title": "Creator Followers"
          },
          "expected_views": {
            "anyOf": [
              {
                "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$",
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "fee 계산에 사용한 예상 조회수입니다.",
            "title": "Expected Views"
          },
          "metric_source": {
            "description": "metric을 가져온 source 이름입니다.",
            "title": "Metric Source",
            "type": "string"
          },
          "quality_signals": {
            "additionalProperties": {
              "anyOf": [
                {
                  "type": "number"
                },
                {
                  "type": "null"
                }
              ]
            },
            "description": "추천 snapshot에 함께 보관된 분석 품질 신호입니다.",
            "title": "Quality Signals",
            "type": "object"
          },
          "recent_video_count": {
            "default": 0,
            "description": "snapshot에 반영된 최근 영상 수입니다.",
            "title": "Recent Video Count",
            "type": "integer"
          },
          "snapshot_generation": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "description": "source snapshot generation 번호입니다.",
            "title": "Snapshot Generation"
          },
          "snapshot_status": {
            "description": "source snapshot 조회 상태입니다.",
            "title": "Snapshot Status",
            "type": "string"
          }
        },
        "required": [
          "metric_source",
          "snapshot_status"
        ],
        "title": "CreatorFeeMetricInfo",
        "type": "object"
      },
      "CreatorFeePredictionResponse": {
        "example": {
          "adjustments": [
            {
              "code": "engagement_high",
              "fee_delta_usd": {
                "max_usd": "540.00",
                "min_usd": "90.00"
              },
              "max_rate": "0.30",
              "min_rate": "0.10",
              "reason": "Engagement rate가 8%를 초과해 프리미엄을 적용했습니다."
            },
            {
              "code": "us_audience_60_plus",
              "fee_delta_usd": {
                "max_usd": "720.00",
                "min_usd": "180.00"
              },
              "max_rate": "0.40",
              "min_rate": "0.20",
              "reason": "US audience 비중이 60% 이상이라 프리미엄을 적용했습니다."
            }
          ],
          "base_fee_usd": {
            "max_usd": "1800.00",
            "min_usd": "900.00"
          },
          "beauty_content_ratio": "0.82",
          "benchmark": {
            "category": "beauty",
            "currency": "USD",
            "source_reviewed_at": "2026-07-21",
            "source_url": "https://influencerfee.com/blog/tiktok-pricing-guide-2025/",
            "version": "influencerfee-tiktok-2026-07-21"
          },
          "benchmark_notes": [
            "조회수 기반 CPV base fee가 follower tier 참고 범위와 일부 겹칩니다."
          ],
          "calculated_at": "2026-07-22T00:00:00Z",
          "calculation_basis": [
            "최근 90일 영상 20개 중 viral outlier 2개를 제외한 18개 median 조회수 60,000회를 적용했습니다."
          ],
          "confidence": "high",
          "content_complexity": "standard",
          "creator_handle": "@abigailcanfieldd",
          "creator_id": "7420747151917691909",
          "creator_unique_id": "abigailcanfieldd",
          "deliverable_type": "standard_video",
          "disclaimer": "This creator fee prediction is a non-binding estimate based on an external USD benchmark and currently collected creator metrics. Actual fees vary by campaign scope and negotiation.",
          "engagement_rate": "8.70",
          "exclusivity_days": 0,
          "expected_views_method": "median_90d",
          "fee_metric_video_count": 18,
          "metrics": {
            "creator_followers": 98000,
            "expected_views": "60000.00",
            "metric_source": "recommendation_source_snapshot",
            "quality_signals": {
              "avg_ad_density_score": 0.18,
              "avg_organic_look_score": 0.79,
              "avg_visual_quality_score": 0.84
            },
            "recent_video_count": 50,
            "snapshot_generation": 12,
            "snapshot_status": "hit"
          },
          "missing_metrics": [],
          "negotiation_ceiling_usd": "3060.00",
          "outlier_count": 2,
          "platform": "TIKTOK",
          "posting_count": 1,
          "predicted_fee_usd": {
            "max_usd": "3060.00",
            "min_usd": "1170.00"
          },
          "reasons": [
            "최근 90일 영상 20개 중 viral outlier 2개를 제외한 18개 median 조회수 60,000회를 적용했습니다.",
            "2개 modifier를 적용했습니다: engagement_high, us_audience_60_plus.",
            "조회수 기반 CPV base fee가 follower tier 참고 범위와 일부 겹칩니다."
          ],
          "skipped_adjustments": [],
          "spark_ads_usage_days": 0,
          "suggested_offer_usd": {
            "max_usd": "2115.00",
            "min_usd": "1170.00"
          },
          "tier_benchmark_position": "overlaps",
          "tier_reference_usd": {
            "max_usd": "125000.00",
            "min_usd": "15000.00"
          },
          "us_audience_share": "0.62"
        },
        "properties": {
          "adjustments": {
            "description": "예측 fee에 적용한 modifier 목록입니다.",
            "items": {
              "$ref": "#/components/schemas/CreatorFeeAdjustment"
            },
            "title": "Adjustments",
            "type": "array"
          },
          "base_fee_usd": {
            "$ref": "#/components/schemas/CreatorFeeRange",
            "description": "CPV 기준 기본 fee 범위입니다."
          },
          "beauty_content_ratio": {
            "anyOf": [
              {
                "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$",
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "최근 영상 중 뷰티 콘텐츠 비율입니다.",
            "title": "Beauty Content Ratio"
          },
          "benchmark": {
            "$ref": "#/components/schemas/CreatorFeeBenchmarkInfo",
            "description": "적용한 benchmark 정보입니다."
          },
          "benchmark_notes": {
            "description": "팔로워 tier 등 외부 benchmark와 비교한 참고 설명입니다.",
            "items": {
              "type": "string"
            },
            "title": "Benchmark Notes",
            "type": "array"
          },
          "calculated_at": {
            "description": "계산 시각입니다.",
            "format": "date-time",
            "title": "Calculated At",
            "type": "string"
          },
          "calculation_basis": {
            "description": "실제 fee 계산에 사용한 핵심 기준입니다.",
            "items": {
              "type": "string"
            },
            "title": "Calculation Basis",
            "type": "array"
          },
          "confidence": {
            "description": "분석 영상 수 기반 신뢰도입니다. 1-4개 low, 5-9개 medium, 10개 이상 high입니다.",
            "enum": [
              "low",
              "medium",
              "high"
            ],
            "title": "Confidence",
            "type": "string"
          },
          "content_complexity": {
            "description": "제작 난이도입니다. dedicated_video는 자동으로 complex로 계산됩니다.",
            "enum": [
              "standard",
              "complex"
            ],
            "title": "Content Complexity",
            "type": "string"
          },
          "creator_handle": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "@를 포함한 TikTok handle입니다.",
            "title": "Creator Handle"
          },
          "creator_id": {
            "description": "정규화된 내부 creator ID입니다.",
            "title": "Creator Id",
            "type": "string"
          },
          "creator_unique_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "TikTok unique ID입니다.",
            "title": "Creator Unique Id"
          },
          "deliverable_type": {
            "description": "예측 대상 납품물 유형입니다.",
            "enum": [
              "standard_video",
              "dedicated_video"
            ],
            "title": "Deliverable Type",
            "type": "string"
          },
          "disclaimer": {
            "description": "fee 예측 고지 문구입니다.",
            "title": "Disclaimer",
            "type": "string"
          },
          "engagement_rate": {
            "anyOf": [
              {
                "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$",
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "최근 영상 engagement rate(%)입니다.",
            "title": "Engagement Rate"
          },
          "exclusivity_days": {
            "description": "경쟁사 독점권 기간(일)입니다.",
            "enum": [
              0,
              30,
              60,
              90
            ],
            "title": "Exclusivity Days",
            "type": "integer"
          },
          "expected_views_method": {
            "description": "예상 조회수 산정 방식입니다.",
            "enum": [
              "median_90d",
              "average_fallback",
              "follower_tier"
            ],
            "title": "Expected Views Method",
            "type": "string"
          },
          "fee_metric_video_count": {
            "description": "fee 계산에 사용한 분석 영상 수입니다. median 집계가 없으면 추천 snapshot의 최근 분석 영상 수를 사용합니다.",
            "title": "Fee Metric Video Count",
            "type": "integer"
          },
          "metrics": {
            "$ref": "#/components/schemas/CreatorFeeMetricInfo",
            "description": "예측에 사용한 snapshot metric입니다."
          },
          "missing_metrics": {
            "description": "계산 시 없어서 보조 기준이나 생략 처리를 한 metric입니다.",
            "items": {
              "type": "string"
            },
            "title": "Missing Metrics",
            "type": "array"
          },
          "negotiation_ceiling_usd": {
            "description": "협상 상한으로 볼 수 있는 금액입니다.",
            "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$",
            "title": "Negotiation Ceiling Usd",
            "type": "string"
          },
          "outlier_count": {
            "description": "viral outlier로 제외한 영상 수입니다.",
            "title": "Outlier Count",
            "type": "integer"
          },
          "platform": {
            "const": "TIKTOK",
            "default": "TIKTOK",
            "description": "현재 fee 예측은 TikTok만 지원합니다.",
            "title": "Platform",
            "type": "string"
          },
          "posting_count": {
            "description": "계산에 반영한 광고 포스팅 수입니다.",
            "title": "Posting Count",
            "type": "integer"
          },
          "predicted_fee_usd": {
            "$ref": "#/components/schemas/CreatorFeeRange",
            "description": "modifier와 수량을 반영한 예측 fee 범위입니다."
          },
          "quote_assessment": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/CreatorFeeQuoteAssessment"
              },
              {
                "type": "null"
              }
            ],
            "description": "creator 제시가를 넘겼을 때의 협상 판정입니다."
          },
          "reasons": {
            "description": "계산 근거 문장입니다.",
            "items": {
              "type": "string"
            },
            "title": "Reasons",
            "type": "array"
          },
          "skipped_adjustments": {
            "description": "데이터 부족 또는 조건 미충족으로 적용하지 않은 modifier입니다.",
            "items": {
              "type": "string"
            },
            "title": "Skipped Adjustments",
            "type": "array"
          },
          "spark_ads_addon_usd": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/CreatorFeeRange"
              },
              {
                "type": "null"
              }
            ],
            "description": "Spark Ads 사용권 add-on 금액입니다."
          },
          "spark_ads_usage_days": {
            "description": "Spark Ads 사용권 기간(일)입니다.",
            "title": "Spark Ads Usage Days",
            "type": "integer"
          },
          "suggested_offer_usd": {
            "$ref": "#/components/schemas/CreatorFeeRange",
            "description": "초기 제안에 권장하는 범위입니다."
          },
          "tier_benchmark_position": {
            "description": "조회수 기반 base fee와 팔로워 tier 참고 범위의 상대 위치입니다.",
            "enum": [
              "below",
              "overlaps",
              "within",
              "above",
              "unavailable"
            ],
            "title": "Tier Benchmark Position",
            "type": "string"
          },
          "tier_reference_usd": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/CreatorFeeRange"
              },
              {
                "type": "null"
              }
            ],
            "description": "팔로워 tier 기준 참고 범위입니다."
          },
          "us_audience_share": {
            "anyOf": [
              {
                "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$",
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "US audience 비중입니다. 0.62는 62%를 의미합니다.",
            "title": "Us Audience Share"
          }
        },
        "required": [
          "creator_id",
          "deliverable_type",
          "posting_count",
          "spark_ads_usage_days",
          "content_complexity",
          "exclusivity_days",
          "base_fee_usd",
          "predicted_fee_usd",
          "suggested_offer_usd",
          "negotiation_ceiling_usd",
          "tier_benchmark_position",
          "expected_views_method",
          "fee_metric_video_count",
          "outlier_count",
          "confidence",
          "metrics",
          "benchmark",
          "disclaimer",
          "calculated_at"
        ],
        "title": "CreatorFeePredictionResponse",
        "type": "object"
      },
      "CreatorFeeQuoteAssessment": {
        "properties": {
          "implied_total_cpv_usd": {
            "anyOf": [
              {
                "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$",
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "제시가를 예상 조회수 기준으로 환산한 CPV입니다.",
            "title": "Implied Total Cpv Usd"
          },
          "position": {
            "description": "제시가가 예측 범위 대비 낮은지, 적정한지, 높은지의 판정입니다.",
            "enum": [
              "below_fair",
              "within_fair",
              "above_fair"
            ],
            "title": "Position",
            "type": "string"
          },
          "quoted_fee_usd": {
            "description": "creator가 제시한 총액(USD)입니다.",
            "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$",
            "title": "Quoted Fee Usd",
            "type": "string"
          },
          "suggested_counter_usd": {
            "$ref": "#/components/schemas/CreatorFeeRange",
            "description": "협상 시 제안할 수 있는 counter 범위입니다."
          }
        },
        "required": [
          "quoted_fee_usd",
          "position",
          "suggested_counter_usd"
        ],
        "title": "CreatorFeeQuoteAssessment",
        "type": "object"
      },
      "CreatorFeeRange": {
        "properties": {
          "max_usd": {
            "description": "예측 범위의 최대 금액(USD)입니다.",
            "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$",
            "title": "Max Usd",
            "type": "string"
          },
          "min_usd": {
            "description": "예측 범위의 최소 금액(USD)입니다.",
            "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$",
            "title": "Min Usd",
            "type": "string"
          }
        },
        "required": [
          "min_usd",
          "max_usd"
        ],
        "title": "CreatorFeeRange",
        "type": "object"
      },
      "CreatorRecommendationItem": {
        "description": "프리셋 추천 결과 목록의 creator 한 명을 표현한다.",
        "properties": {
          "contact_email": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Contact Email"
          },
          "creator_email": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Creator Email"
          },
          "creator_followers": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "title": "Creator Followers"
          },
          "creator_followings": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "title": "Creator Followings"
          },
          "creator_handle": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Creator Handle"
          },
          "creator_id": {
            "title": "Creator Id",
            "type": "string"
          },
          "creator_likes": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "title": "Creator Likes"
          },
          "creator_signature": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Creator Signature"
          },
          "creator_unique_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Creator Unique Id"
          },
          "platform": {
            "title": "Platform",
            "type": "string"
          }
        },
        "required": [
          "creator_id",
          "platform"
        ],
        "title": "CreatorRecommendationItem",
        "type": "object"
      },
      "CreatorRecommendationPage": {
        "properties": {
          "items": {
            "items": {
              "$ref": "#/components/schemas/CreatorRecommendationItem"
            },
            "title": "Items",
            "type": "array"
          },
          "limit": {
            "title": "Limit",
            "type": "integer"
          },
          "start": {
            "title": "Start",
            "type": "integer"
          },
          "total_count": {
            "title": "Total Count",
            "type": "integer"
          }
        },
        "required": [
          "total_count",
          "start",
          "limit",
          "items"
        ],
        "title": "CreatorRecommendationPage",
        "type": "object"
      },
      "HTTPValidationError": {
        "properties": {
          "detail": {
            "items": {
              "$ref": "#/components/schemas/ValidationError"
            },
            "title": "Detail",
            "type": "array"
          }
        },
        "title": "HTTPValidationError",
        "type": "object"
      },
      "TaxonomyCategoryItem": {
        "properties": {
          "aliases": {
            "items": {
              "type": "string"
            },
            "title": "Aliases",
            "type": "array"
          },
          "category_key": {
            "title": "Category Key",
            "type": "string"
          },
          "category_type": {
            "title": "Category Type",
            "type": "string"
          },
          "created_at": {
            "anyOf": [
              {
                "format": "date-time",
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Created At"
          },
          "description": {
            "default": "",
            "title": "Description",
            "type": "string"
          },
          "display_name": {
            "title": "Display Name",
            "type": "string"
          },
          "is_active": {
            "default": true,
            "title": "Is Active",
            "type": "boolean"
          },
          "parent_key": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Parent Key"
          },
          "sort_order": {
            "default": 0,
            "title": "Sort Order",
            "type": "integer"
          },
          "source": {
            "default": "",
            "title": "Source",
            "type": "string"
          },
          "updated_at": {
            "anyOf": [
              {
                "format": "date-time",
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Updated At"
          }
        },
        "required": [
          "category_key",
          "category_type",
          "display_name"
        ],
        "title": "TaxonomyCategoryItem",
        "type": "object"
      },
      "ValidationError": {
        "properties": {
          "ctx": {
            "title": "Context",
            "type": "object"
          },
          "input": {
            "title": "Input"
          },
          "loc": {
            "items": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "integer"
                }
              ]
            },
            "title": "Location",
            "type": "array"
          },
          "msg": {
            "title": "Message",
            "type": "string"
          },
          "type": {
            "title": "Error Type",
            "type": "string"
          }
        },
        "required": [
          "loc",
          "msg",
          "type"
        ],
        "title": "ValidationError",
        "type": "object"
      },
      "TrendMetricMeta": {
        "type": "object",
        "properties": {
          "metric_status": {
            "type": "string",
            "enum": ["available", "limited", "unavailable", "stale"]
          },
          "data_source": {
            "type": "string",
            "enum": ["observed", "analyzed", "inferred", "estimated", "verified"]
          },
          "sample_count": {"type": "integer", "format": "int64"},
          "coverage_ratio": {
            "anyOf": [{"type": "number"}, {"type": "null"}]
          },
          "data_through": {
            "type": "string",
            "description": "분석 기준일입니다. unavailable 상태에서는 빈 문자열일 수 있습니다."
          },
          "confidence": {
            "type": "string",
            "enum": ["high", "medium", "low"]
          },
          "refreshed_at": {
            "type": "string",
            "description": "서빙 스냅샷 갱신 시각입니다."
          },
          "limitations": {
            "type": "array",
            "items": {"type": "string"}
          }
        },
        "required": [
          "metric_status",
          "data_source",
          "sample_count",
          "coverage_ratio",
          "data_through",
          "limitations"
        ]
      },
      "ProductTrend": {
        "allOf": [
          {"$ref": "#/components/schemas/TrendMetricMeta"},
          {
            "type": "object",
            "properties": {
              "product_id": {"type": "integer", "format": "int64", "minimum": 1},
              "product_name": {"type": "string"},
              "brand_id": {
                "anyOf": [
                  {"type": "integer", "format": "int64", "minimum": 1},
                  {"type": "null"}
                ]
              },
              "brand_name": {
                "anyOf": [
                  {"type": "string"},
                  {"type": "null"}
                ]
              },
              "product_asin": {"type": "string"},
              "brand_resolution_status": {
                "type": "string",
                "enum": ["single_brand", "brand_missing", "ambiguous_brand"]
              },
              "canonical_source": {
                "type": "string",
                "enum": ["campaign_asin", "brand_product_name", "video_scoped_unresolved"]
              },
              "entity_confidence": {
                "anyOf": [{"type": "number"}, {"type": "null"}],
                "minimum": 0,
                "maximum": 1
              },
              "period_days": {"type": "integer", "enum": [7, 30]},
              "mention_video_count": {"type": "integer", "format": "int64"},
              "previous_video_count": {"type": "integer", "format": "int64"},
              "mention_growth_rate": {
                "anyOf": [{"type": "number"}, {"type": "null"}]
              },
              "creator_count": {"type": "integer", "format": "int64"},
              "previous_creator_count": {"type": "integer", "format": "int64"},
              "creator_growth_rate": {
                "anyOf": [{"type": "number"}, {"type": "null"}]
              },
              "avg_view_velocity": {
                "anyOf": [{"type": "number"}, {"type": "null"}]
              },
              "engagement_rate": {
                "anyOf": [{"type": "number"}, {"type": "null"}]
              },
              "attention_score": {
                "anyOf": [{"type": "number"}, {"type": "null"}]
              },
              "score_components": {
                "type": "object",
                "additionalProperties": true
              },
              "score_version": {"type": "string", "description": "점수 계산 규칙의 버전이며 HTTP API 버전과는 별개입니다."},
              "gmv_observed_video_count": {"type": "integer", "format": "int64"},
              "attributed_gmv": {
                "anyOf": [{"type": "number"}, {"type": "null"}]
              },
              "gmv_coverage_ratio": {
                "anyOf": [{"type": "number"}, {"type": "null"}]
              }
            },
            "required": [
              "product_id",
              "product_name",
              "brand_id",
              "brand_resolution_status",
              "canonical_source",
              "entity_confidence",
              "period_days",
              "mention_video_count",
              "previous_video_count",
              "mention_growth_rate",
              "creator_count",
              "previous_creator_count",
              "creator_growth_rate",
              "avg_view_velocity",
              "engagement_rate",
              "attention_score",
              "gmv_observed_video_count",
              "attributed_gmv",
              "gmv_coverage_ratio"
            ]
          }
        ]
      },
      "CreatorTrend": {
        "allOf": [
          {"$ref": "#/components/schemas/TrendMetricMeta"},
          {
            "type": "object",
            "properties": {
              "platform": {"type": "string"},
              "creator_id": {"type": "string"},
              "unique_id": {"type": "string"},
              "handle": {"type": "string"},
              "contactable": {"type": "boolean"},
              "followers": {
                "anyOf": [{"type": "integer", "format": "int64"}, {"type": "null"}]
              },
              "avg_views": {
                "anyOf": [{"type": "number"}, {"type": "null"}]
              },
              "recent_video_count": {"type": "integer"},
              "analyzed_video_count": {"type": "integer"},
              "top_products": {
                "type": "array",
                "items": {"type": "string"}
              },
              "top_categories": {
                "type": "array",
                "items": {"type": "string"}
              },
              "top_sub_categories": {
                "type": "array",
                "items": {"type": "string"}
              },
              "top_skin_concerns": {
                "type": "array",
                "items": {"type": "string"}
              },
              "top_claims": {
                "type": "array",
                "items": {"type": "string"}
              },
              "top_demo_methods": {
                "type": "array",
                "items": {"type": "string"}
              },
              "top_brands": {
                "type": "array",
                "items": {"type": "string"}
              },
              "top_content_formats": {
                "type": "array",
                "items": {"type": "string"}
              },
              "audience_region_distribution": {
                "type": "object",
                "additionalProperties": true
              },
              "avg_visual_quality_score": {
                "anyOf": [{"type": "number"}, {"type": "null"}]
              },
              "avg_organic_look_score": {
                "anyOf": [{"type": "number"}, {"type": "null"}]
              },
              "avg_ad_density_score": {
                "anyOf": [{"type": "number"}, {"type": "null"}]
              },
              "follower_growth_rate": {
                "anyOf": [{"type": "number"}, {"type": "null"}]
              },
              "avg_views_growth_rate": {
                "anyOf": [{"type": "number"}, {"type": "null"}]
              },
              "follower_growth_rate_7d": {
                "anyOf": [{"type": "number"}, {"type": "null"}]
              },
              "follower_growth_rate_30d": {
                "anyOf": [{"type": "number"}, {"type": "null"}]
              },
              "avg_views_growth_rate_7d": {
                "anyOf": [{"type": "number"}, {"type": "null"}]
              },
              "avg_views_growth_rate_30d": {
                "anyOf": [{"type": "number"}, {"type": "null"}]
              },
              "history_span_days": {
                "type": "integer",
                "minimum": 0
              },
              "max_views": {
                "anyOf": [{"type": "integer", "format": "int64"}, {"type": "null"}]
              },
              "engagement_rate": {
                "anyOf": [{"type": "number"}, {"type": "null"}]
              },
              "breakout_score": {"type": "number"},
              "creator_relevance_score": {
                "anyOf": [{"type": "number"}, {"type": "null"}]
              },
              "creator_quality_score": {
                "anyOf": [{"type": "number"}, {"type": "null"}]
              },
              "activation_readiness_score": {
                "anyOf": [{"type": "number"}, {"type": "null"}]
              },
              "creator_seeding_fit_score": {
                "anyOf": [{"type": "number"}, {"type": "null"}]
              },
              "score_components": {
                "type": "object",
                "additionalProperties": true
              },
              "external_post_rate_raw": {
                "anyOf": [{"type": "number"}, {"type": "null"}]
              },
              "external_median_gmv": {
                "anyOf": [{"type": "number"}, {"type": "null"}]
              },
              "external_signal_status": {"type": "string"},
              "risk_flags": {
                "type": "array",
                "items": {"type": "string"}
              },
              "evidence_videos": {
                "type": "array",
                "items": {"$ref": "#/components/schemas/CreatorEvidenceVideo"}
              },
              "feature_version": {"type": "string", "description": "분석 특성 산출 규칙의 버전이며 HTTP API 버전과는 별개입니다."},
              "score_version": {"type": "string", "description": "점수 계산 규칙의 버전이며 HTTP API 버전과는 별개입니다."},
              "estimated_posting_price": {
                "type": "object",
                "additionalProperties": true
              },
              "segments": {
                "type": "array",
                "items": {
                  "type": "string",
                  "enum": ["million_view", "newly_observed", "fast_growing"]
                }
              }
            },
            "required": [
              "platform",
              "creator_id",
              "contactable",
              "followers",
              "avg_views",
              "recent_video_count",
              "analyzed_video_count",
              "top_products",
              "top_categories",
              "top_sub_categories",
              "top_skin_concerns",
              "top_claims",
              "top_demo_methods",
              "top_brands",
              "top_content_formats",
              "avg_visual_quality_score",
              "avg_organic_look_score",
              "avg_ad_density_score",
              "follower_growth_rate",
              "avg_views_growth_rate",
              "follower_growth_rate_7d",
              "follower_growth_rate_30d",
              "avg_views_growth_rate_7d",
              "avg_views_growth_rate_30d",
              "history_span_days",
              "max_views",
              "engagement_rate",
              "breakout_score",
              "creator_relevance_score",
              "creator_quality_score",
              "activation_readiness_score",
              "creator_seeding_fit_score",
              "score_components",
              "risk_flags",
              "evidence_videos",
              "segments"
            ]
          }
        ]
      },
      "CreatorProductFit": {
        "allOf": [
          {"$ref": "#/components/schemas/TrendMetricMeta"},
          {
            "type": "object",
            "properties": {
              "product_id": {"type": "integer", "format": "int64", "minimum": 1},
              "product_name": {"type": "string"},
              "brand_name": {"type": "string"},
              "creator_id": {"type": "string"},
              "related_video_count": {"type": "integer", "format": "int64"},
              "related_video_share": {
                "anyOf": [{"type": "number"}, {"type": "null"}]
              },
              "related_avg_views": {
                "anyOf": [{"type": "number"}, {"type": "null"}]
              },
              "related_engagement_rate": {
                "anyOf": [{"type": "number"}, {"type": "null"}]
              },
              "production_fit": {
                "anyOf": [{"type": "number"}, {"type": "null"}]
              },
              "fit_score": {
                "anyOf": [{"type": "number"}, {"type": "null"}]
              },
              "score_components": {
                "type": "object",
                "additionalProperties": true
              },
              "score_version": {"type": "string", "description": "점수 계산 규칙의 버전이며 HTTP API 버전과는 별개입니다."}
            },
            "required": [
              "product_id",
              "creator_id",
              "related_video_count",
              "related_video_share",
              "related_avg_views",
              "related_engagement_rate",
              "production_fit",
              "fit_score"
            ]
          }
        ]
      },
      "PromotionPattern": {
        "allOf": [
          {"$ref": "#/components/schemas/TrendMetricMeta"},
          {
            "type": "object",
            "properties": {
              "product_id": {"type": "integer", "format": "int64", "minimum": 1},
              "pattern_type": {"type": "string"},
              "pattern_value": {"type": "string"},
              "video_count": {"type": "integer", "format": "int64"},
              "creator_count": {"type": "integer", "format": "int64"},
              "avg_views": {
                "anyOf": [{"type": "number"}, {"type": "null"}]
              },
              "engagement_rate": {
                "anyOf": [{"type": "number"}, {"type": "null"}]
              },
              "pattern_rank": {"type": "integer", "format": "int64"}
            },
            "required": [
              "product_id",
              "pattern_type",
              "pattern_value",
              "video_count",
              "creator_count",
              "avg_views",
              "engagement_rate",
              "pattern_rank"
            ]
          }
        ]
      },
      "WeeklyProductTrend": {
        "type": "object",
        "properties": {
          "product_id": {"type": "integer", "format": "int64", "minimum": 1},
          "brand_id": {
            "anyOf": [
              {"type": "integer", "format": "int64", "minimum": 1},
              {"type": "null"}
            ]
          },
          "product_name": {"type": "string"},
          "attention_score": {"type": "number"},
          "mention_growth_rate": {
            "anyOf": [{"type": "number"}, {"type": "null"}]
          }
        },
        "required": ["product_id", "brand_id", "product_name", "attention_score", "mention_growth_rate"]
      },
      "WeeklyCreatorTrend": {
        "type": "object",
        "properties": {
          "creator_id": {"type": "string"},
          "handle": {"type": "string"},
          "breakout_score": {"type": "number"},
          "segments": {
            "type": "array",
            "items": {"type": "string"}
          }
        },
        "required": ["creator_id", "breakout_score", "segments"]
      },
      "WeeklySegmentInsight": {
        "type": "object",
        "properties": {
          "week_start": {"type": "string", "format": "date"},
          "week_end": {"type": "string", "format": "date"},
          "primary_category": {"type": "string"},
          "sub_category": {"type": "string"},
          "creator_gender": {"type": "string"},
          "creator_age_band": {"type": "string"},
          "creator_skin_type": {"type": "string"},
          "summary_ko": {"type": "string"},
          "winning_patterns": {"type": "array", "items": {"type": "string"}},
          "recommended_brief_angles": {"type": "array", "items": {"type": "string"}},
          "notable_shifts": {"type": "array", "items": {"type": "string"}},
          "risk_notes": {"type": "array", "items": {"type": "string"}},
          "sample_count": {"type": "integer"},
          "model_provider": {"type": "string"},
          "model_name": {"type": "string"},
          "prompt_version": {"type": "string", "description": "요약 생성 프롬프트의 버전이며 HTTP API 버전과는 별개입니다."},
          "source_stats_hash": {"type": "string"},
          "data_through": {"type": "string", "format": "date"},
          "limitations": {"type": "array", "items": {"type": "string"}},
          "refreshed_at": {"type": "string"}
        },
        "required": [
          "week_start",
          "week_end",
          "summary_ko",
          "sample_count",
          "data_through",
          "limitations"
        ]
      },
      "WeeklyTrendBrief": {
        "allOf": [
          {"$ref": "#/components/schemas/TrendMetricMeta"},
          {
            "type": "object",
            "properties": {
              "week_start": {"type": "string", "format": "date"},
              "week_end": {"type": "string", "format": "date"},
              "top_products": {
                "type": "array",
                "items": {"$ref": "#/components/schemas/WeeklyProductTrend"}
              },
              "breakout_creators": {
                "type": "array",
                "items": {"$ref": "#/components/schemas/WeeklyCreatorTrend"}
              },
              "summary_ko": {"type": "string"},
              "segment_insights": {
                "type": "array",
                "items": {"$ref": "#/components/schemas/WeeklySegmentInsight"}
              }
            },
            "required": [
              "week_start",
              "week_end",
              "top_products",
              "breakout_creators",
              "summary_ko"
            ]
          }
        ]
      },
      "DataStatus": {
        "type": "object",
        "properties": {
          "capability": {"type": "string"},
          "metric_status": {
            "type": "string",
            "enum": ["available", "limited", "unavailable", "stale"]
          },
          "data_source": {
            "type": "string",
            "enum": ["observed", "analyzed", "inferred", "estimated", "verified"]
          },
          "sample_count": {"type": "integer", "format": "int64"},
          "coverage_ratio": {
            "anyOf": [{"type": "number"}, {"type": "null"}]
          },
          "data_through": {
            "type": "string",
            "description": "데이터 기준일입니다. unavailable 상태에서는 빈 문자열일 수 있습니다."
          },
          "freshness_status": {
            "type": "string",
            "enum": ["available", "limited", "unavailable", "stale"]
          },
          "run_id": {"type": "string"},
          "last_successful_run_at": {"type": "string"},
          "delay_days": {"type": "integer", "minimum": 0},
          "archive_through": {"type": "string"},
          "limitations": {
            "type": "array",
            "items": {"type": "string"}
          }
        },
        "required": [
          "capability",
          "metric_status",
          "data_source",
          "sample_count",
          "coverage_ratio",
          "data_through",
          "freshness_status",
          "limitations"
        ]
      },
      "CreatorHistoryPoint": {
        "type": "object",
        "properties": {
          "creator_id": {"type": "string"},
          "platform": {"type": "string"},
          "period_start": {"type": "string", "format": "date"},
          "granularity": {"type": "string", "enum": ["day", "month"]},
          "followers": {
            "anyOf": [{"type": "integer", "format": "int64"}, {"type": "null"}]
          },
          "avg_views": {
            "anyOf": [{"type": "number"}, {"type": "null"}]
          },
          "recent_video_count": {
            "anyOf": [{"type": "integer"}, {"type": "null"}]
          },
          "creator_relevance_score": {
            "anyOf": [{"type": "number"}, {"type": "null"}]
          },
          "creator_quality_score": {
            "anyOf": [{"type": "number"}, {"type": "null"}]
          },
          "activation_readiness_score": {
            "anyOf": [{"type": "number"}, {"type": "null"}]
          },
          "creator_seeding_fit_score": {
            "anyOf": [{"type": "number"}, {"type": "null"}]
          },
          "score_version": {"type": "string", "description": "점수 계산 규칙의 버전이며 HTTP API 버전과는 별개입니다."},
          "data_through": {"type": "string", "format": "date"}
        },
        "required": [
          "creator_id",
          "platform",
          "period_start",
          "granularity",
          "data_through"
        ]
      },
      "CreatorHistoryPage": {
        "type": "object",
        "properties": {
          "items": {
            "type": "array",
            "items": {"$ref": "#/components/schemas/CreatorHistoryPoint"}
          },
          "total_count": {"type": "integer"}
        },
        "required": ["items", "total_count"]
      },
      "TrendHistoryPoint": {
        "type": "object",
        "properties": {
          "facet_type": {"type": "string"},
          "facet_key": {"type": "string"},
          "period_start": {"type": "string", "format": "date"},
          "granularity": {"type": "string", "enum": ["day", "month"]},
          "video_count": {"type": "integer", "format": "int64"},
          "creator_count": {"type": "integer", "format": "int64"},
          "total_views": {
            "anyOf": [{"type": "integer", "format": "int64"}, {"type": "null"}]
          },
          "avg_view_velocity": {
            "anyOf": [{"type": "number"}, {"type": "null"}]
          },
          "engagement_rate": {
            "anyOf": [{"type": "number"}, {"type": "null"}]
          },
          "trend_score": {
            "anyOf": [{"type": "number"}, {"type": "null"}]
          },
          "score_version": {"type": "string", "description": "점수 계산 규칙의 버전이며 HTTP API 버전과는 별개입니다."},
          "data_through": {"type": "string", "format": "date"}
        },
        "required": [
          "facet_type",
          "facet_key",
          "period_start",
          "granularity",
          "video_count",
          "creator_count",
          "data_through"
        ]
      },
      "TrendHistoryPage": {
        "type": "object",
        "properties": {
          "items": {
            "type": "array",
            "items": {"$ref": "#/components/schemas/TrendHistoryPoint"}
          },
          "total_count": {"type": "integer"}
        },
        "required": ["items", "total_count"]
      },
      "ProductTrendPage": {
        "type": "object",
        "properties": {
          "items": {
            "type": "array",
            "items": {"$ref": "#/components/schemas/ProductTrend"}
          },
          "total_count": {"type": "integer"},
          "start": {"type": "integer"},
          "limit": {"type": "integer"}
        },
        "required": ["items", "total_count", "start", "limit"]
      },
      "CreatorSearchItem": {
        "type": "object",
        "properties": {
          "platform": {"type": "string"},
          "creator_id": {"type": "string"},
          "creator_unique_id": {"type": "string"},
          "creator_handle": {"type": "string"},
          "creator_followers": {
            "anyOf": [{"type": "integer", "format": "int64"}, {"type": "null"}]
          },
          "average_views": {
            "anyOf": [{"type": "number"}, {"type": "null"}]
          },
          "engagement_rate": {
            "anyOf": [{"type": "number"}, {"type": "null"}]
          },
          "top_categories": {
            "type": "array",
            "items": {"type": "string"}
          },
          "top_content_formats": {
            "type": "array",
            "items": {"type": "string"}
          },
          "contactable": {"type": "boolean"},
          "intelligence_status": {
            "type": "string",
            "enum": ["available", "unavailable"]
          },
          "rank": {"type": "integer", "minimum": 1},
          "rank_score": {
            "anyOf": [{"type": "number"}, {"type": "null"}]
          },
          "matched_facets": {
            "type": "array",
            "items": {"type": "string"}
          }
        },
        "required": [
          "platform",
          "creator_id",
          "creator_followers",
          "average_views",
          "engagement_rate",
          "top_categories",
          "top_content_formats",
          "contactable",
          "intelligence_status",
          "rank",
          "rank_score",
          "matched_facets"
        ]
      },
      "CreatorSearchPage": {
        "type": "object",
        "properties": {
          "items": {
            "type": "array",
            "items": {"$ref": "#/components/schemas/CreatorSearchItem"}
          },
          "total_count": {"type": "integer"},
          "start": {"type": "integer"},
          "limit": {"type": "integer"},
          "snapshot_version": {"type": "string", "description": "사전 적재 스냅샷 세대 버전이며 HTTP API 버전과는 별개입니다."},
          "data_through": {"type": "string"}
        },
        "required": ["items", "total_count", "start", "limit", "data_through"]
      },
      "CreatorProfile": {
        "type": "object",
        "properties": {
          "creator_id": {"type": "string"},
          "platform": {"type": "string"},
          "creator_unique_id": {
            "anyOf": [{"type": "string"}, {"type": "null"}]
          },
          "creator_handle": {
            "anyOf": [{"type": "string"}, {"type": "null"}]
          },
          "creator_signature": {
            "anyOf": [{"type": "string"}, {"type": "null"}]
          },
          "creator_followers": {
            "anyOf": [{"type": "integer", "format": "int64"}, {"type": "null"}]
          },
          "creator_followings": {
            "anyOf": [{"type": "integer", "format": "int64"}, {"type": "null"}]
          },
          "creator_likes": {
            "anyOf": [{"type": "integer", "format": "int64"}, {"type": "null"}]
          },
          "contactable": {"type": "boolean"},
          "intelligence_status": {
            "type": "string",
            "enum": ["available", "unavailable"]
          },
          "profile_updated_at": {"type": "string", "format": "date-time"}
        },
        "required": [
          "creator_id",
          "platform",
          "creator_unique_id",
          "creator_handle",
          "creator_signature",
          "creator_followers",
          "creator_followings",
          "creator_likes",
          "contactable",
          "intelligence_status"
        ]
      },
      "CreatorScores": {
        "type": "object",
        "properties": {
          "relevance": {"anyOf": [{"type": "number"}, {"type": "null"}]},
          "quality": {"anyOf": [{"type": "number"}, {"type": "null"}]},
          "activation_readiness": {"anyOf": [{"type": "number"}, {"type": "null"}]},
          "seeding_fit": {"anyOf": [{"type": "number"}, {"type": "null"}]},
          "breakout": {"type": "number"},
          "components": {"type": "object", "additionalProperties": true}
        },
        "required": [
          "relevance",
          "quality",
          "activation_readiness",
          "seeding_fit",
          "breakout",
          "components"
        ]
      },
      "CreatorExpertise": {
        "type": "object",
        "properties": {
          "categories": {"type": "array", "items": {"type": "string"}},
          "sub_categories": {"type": "array", "items": {"type": "string"}},
          "skin_concerns": {"type": "array", "items": {"type": "string"}},
          "claims": {"type": "array", "items": {"type": "string"}},
          "demo_methods": {"type": "array", "items": {"type": "string"}},
          "products": {"type": "array", "items": {"type": "string"}},
          "brands": {"type": "array", "items": {"type": "string"}},
          "content_formats": {"type": "array", "items": {"type": "string"}}
        },
        "required": [
          "categories",
          "sub_categories",
          "skin_concerns",
          "claims",
          "demo_methods",
          "products",
          "brands",
          "content_formats"
        ]
      },
      "CreatorPerformance": {
        "type": "object",
        "properties": {
          "avg_views": {"anyOf": [{"type": "number"}, {"type": "null"}]},
          "max_views": {
            "anyOf": [{"type": "integer", "format": "int64"}, {"type": "null"}]
          },
          "engagement_rate": {"anyOf": [{"type": "number"}, {"type": "null"}]},
          "recent_video_count": {"type": "integer"},
          "analyzed_video_count": {"type": "integer"},
          "history_span_days": {"type": "integer"},
          "follower_growth_rate": {"anyOf": [{"type": "number"}, {"type": "null"}]},
          "avg_views_growth_rate": {"anyOf": [{"type": "number"}, {"type": "null"}]},
          "follower_growth_rate_7d": {"anyOf": [{"type": "number"}, {"type": "null"}]},
          "follower_growth_rate_30d": {"anyOf": [{"type": "number"}, {"type": "null"}]},
          "avg_views_growth_rate_7d": {"anyOf": [{"type": "number"}, {"type": "null"}]},
          "avg_views_growth_rate_30d": {"anyOf": [{"type": "number"}, {"type": "null"}]},
          "avg_visual_quality_score": {"anyOf": [{"type": "number"}, {"type": "null"}]},
          "avg_organic_look_score": {"anyOf": [{"type": "number"}, {"type": "null"}]},
          "avg_ad_density_score": {"anyOf": [{"type": "number"}, {"type": "null"}]}
        },
        "required": [
          "avg_views",
          "max_views",
          "engagement_rate",
          "recent_video_count",
          "analyzed_video_count",
          "history_span_days",
          "follower_growth_rate",
          "avg_views_growth_rate",
          "follower_growth_rate_7d",
          "follower_growth_rate_30d",
          "avg_views_growth_rate_7d",
          "avg_views_growth_rate_30d",
          "avg_visual_quality_score",
          "avg_organic_look_score",
          "avg_ad_density_score"
        ]
      },
      "CreatorCommercialSignals": {
        "type": "object",
        "properties": {
          "external_post_rate_raw": {"anyOf": [{"type": "number"}, {"type": "null"}]},
          "external_median_gmv": {"anyOf": [{"type": "number"}, {"type": "null"}]},
          "external_signal_status": {"type": "string"}
        },
        "required": ["external_post_rate_raw", "external_median_gmv"]
      },
      "CreatorIntelligence": {
        "allOf": [
          {"$ref": "#/components/schemas/TrendMetricMeta"},
          {
            "type": "object",
            "properties": {
              "creator_id": {"type": "string"},
              "status": {
                "type": "string",
                "enum": ["available", "unavailable"]
              },
              "schema_version": {"type": "string", "description": "응답 데이터 구조의 버전이며 HTTP API 버전과는 별개입니다."},
              "feature_version": {"type": "string", "description": "분석 특성 산출 규칙의 버전이며 HTTP API 버전과는 별개입니다."},
              "segments": {"type": "array", "items": {"type": "string"}},
              "scores": {"$ref": "#/components/schemas/CreatorScores"},
              "expertise": {"$ref": "#/components/schemas/CreatorExpertise"},
              "performance": {"$ref": "#/components/schemas/CreatorPerformance"},
              "audience_region_distribution": {
                "type": "object",
                "additionalProperties": true
              },
              "commercial_signals": {
                "$ref": "#/components/schemas/CreatorCommercialSignals"
              },
              "risk_flags": {"type": "array", "items": {"type": "string"}},
              "resources": {
                "type": "object",
                "properties": {
                  "evidence_video_count": {"type": "integer"}
                },
                "required": ["evidence_video_count"]
              }
            },
            "required": [
              "creator_id",
              "status",
              "schema_version",
              "segments",
              "scores",
              "expertise",
              "performance",
              "commercial_signals",
              "risk_flags",
              "resources"
            ]
          }
        ]
      },
      "CreatorEvidenceVideoPage": {
        "type": "object",
        "properties": {
          "items": {
            "type": "array",
            "items": {"$ref": "#/components/schemas/CreatorEvidenceVideo"}
          },
          "total_count": {"type": "integer"},
          "start": {"type": "integer"},
          "limit": {"type": "integer"},
          "data_through": {"type": "string"}
        },
        "required": ["items", "total_count", "start", "limit", "data_through"]
      },
      "CreatorVideoPreviewGroup": {
        "type": "object",
        "properties": {
          "creator_id": {"type": "string"},
          "videos": {
            "type": "array",
            "items": {"$ref": "#/components/schemas/CreatorEvidenceVideo"}
          }
        },
        "required": ["creator_id", "videos"]
      },
      "CreatorVideoPreviewResponse": {
        "type": "object",
        "properties": {
          "items": {
            "type": "array",
            "items": {"$ref": "#/components/schemas/CreatorVideoPreviewGroup"}
          },
          "limit_per_creator": {"type": "integer", "minimum": 1, "maximum": 3},
          "data_through": {"type": "string"}
        },
        "required": ["items", "limit_per_creator", "data_through"]
      },
      "CreatorProductFitPage": {
        "type": "object",
        "properties": {
          "items": {
            "type": "array",
            "items": {"$ref": "#/components/schemas/CreatorProductFit"}
          },
          "total_count": {"type": "integer"},
          "start": {"type": "integer"},
          "limit": {"type": "integer"}
        },
        "required": ["items", "total_count", "start", "limit"]
      },
      "ProductTrendDetail": {
        "type": "object",
        "properties": {
          "product_id": {"type": "integer", "format": "int64", "minimum": 1},
          "trends": {
            "type": "array",
            "items": {"$ref": "#/components/schemas/ProductTrend"}
          }
        },
        "required": ["product_id", "trends"]
      },
      "PromotionPatternList": {
        "type": "object",
        "properties": {
          "items": {
            "type": "array",
            "items": {"$ref": "#/components/schemas/PromotionPattern"}
          },
          "total_count": {"type": "integer"}
        },
        "required": ["items", "total_count"]
      },
      "WeeklyTrendBriefList": {
        "type": "object",
        "properties": {
          "items": {
            "type": "array",
            "items": {"$ref": "#/components/schemas/WeeklyTrendBrief"}
          },
          "total_count": {"type": "integer"}
        },
        "required": ["items", "total_count"]
      },
      "DataStatusList": {
        "type": "object",
        "properties": {
          "items": {
            "type": "array",
            "items": {"$ref": "#/components/schemas/DataStatus"}
          },
          "total_count": {"type": "integer"}
        },
        "required": ["items", "total_count"]
      },
      "IngredientTrend": {
        "allOf": [
          {"$ref": "#/components/schemas/TrendMetricMeta"},
          {
            "type": "object",
            "properties": {
              "ingredient_key": {"type": "string"},
              "ingredient_name": {"type": "string"},
              "period_days": {"type": "integer", "enum": [7, 30]},
              "mention_video_count": {"type": "integer", "format": "int64"},
              "attention_score": {"type": "number"}
            },
            "required": [
              "ingredient_key",
              "ingredient_name",
              "period_days",
              "mention_video_count",
              "attention_score"
            ]
          }
        ]
      },
      "IngredientTrendResponse": {
        "type": "object",
        "properties": {
          "items": {
            "type": "array",
            "items": {"$ref": "#/components/schemas/IngredientTrend"}
          },
          "total_count": {"type": "integer"},
          "data_status": {"$ref": "#/components/schemas/DataStatus"}
        },
        "required": ["items", "total_count", "data_status"]
      },
      "CreatorEvidenceVideo": {
        "type": "object",
        "properties": {
          "video_id": {"type": "string"},
          "video_url": {"type": "string"},
          "caption": {"type": "string"},
          "video_created_date": {"type": "string", "format": "date"},
          "views": {"anyOf": [{"type": "integer", "format": "int64"}, {"type": "null"}]},
          "likes": {"anyOf": [{"type": "integer", "format": "int64"}, {"type": "null"}]},
          "comments": {"anyOf": [{"type": "integer", "format": "int64"}, {"type": "null"}]},
          "shares": {"anyOf": [{"type": "integer", "format": "int64"}, {"type": "null"}]},
          "content_format": {"type": "string"},
          "brands": {"type": "array", "items": {"type": "string"}},
          "products": {"type": "array", "items": {"type": "string"}},
          "evidence_rank": {"type": "integer"},
          "evidence_reason": {"type": "string"}
        },
        "required": [
          "video_id", "views", "likes", "comments", "shares", "brands",
          "products", "evidence_rank", "evidence_reason"
        ]
      },
      "BeautyTrendRadar": {
        "allOf": [
          {"$ref": "#/components/schemas/TrendMetricMeta"},
          {
            "type": "object",
            "properties": {
              "facet_type": {"type": "string"},
              "facet_key": {"type": "string"},
              "beauty_category": {"type": "string"},
              "primary_category": {"type": "string"},
              "sub_category": {"type": "string"},
              "period_days": {"type": "integer", "enum": [7, 30, 60, 90]},
              "mention_video_count": {"type": "integer", "format": "int64"},
              "previous_video_count": {"type": "integer", "format": "int64"},
              "mention_growth_rate": {"anyOf": [{"type": "number"}, {"type": "null"}]},
              "creator_count": {"type": "integer", "format": "int64"},
              "previous_creator_count": {"type": "integer", "format": "int64"},
              "creator_growth_rate": {"anyOf": [{"type": "number"}, {"type": "null"}]},
              "avg_view_velocity": {"anyOf": [{"type": "number"}, {"type": "null"}]},
              "view_velocity_growth_rate": {"anyOf": [{"type": "number"}, {"type": "null"}]},
              "engagement_rate": {"anyOf": [{"type": "number"}, {"type": "null"}]},
              "new_creator_share": {"anyOf": [{"type": "number"}, {"type": "null"}]},
              "trend_score": {
                "anyOf": [{"type": "number"}, {"type": "null"}]
              },
              "score_components": {
                "type": "object",
                "additionalProperties": true
              },
              "score_version": {"type": "string", "description": "점수 계산 규칙의 버전이며 HTTP API 버전과는 별개입니다."},
              "trend_phase": {
                "type": "string",
                "enum": ["emerging", "accelerating", "sustained", "cooling"]
              }
            },
            "required": [
              "facet_type", "facet_key", "period_days", "mention_video_count",
              "previous_video_count", "mention_growth_rate", "creator_count",
              "previous_creator_count", "creator_growth_rate", "avg_view_velocity",
              "view_velocity_growth_rate", "engagement_rate", "new_creator_share",
              "trend_score", "trend_phase"
            ]
          }
        ]
      },
      "BeautyTrendRelation": {
        "type": "object",
        "properties": {
          "source_facet_type": {"type": "string"},
          "source_facet_key": {"type": "string"},
          "target_facet_type": {"type": "string"},
          "target_facet_key": {"type": "string"},
          "video_count": {"type": "integer", "format": "int64"},
          "creator_count": {"type": "integer", "format": "int64"},
          "relation_score": {"type": "number"},
          "score_version": {"type": "string", "description": "점수 계산 규칙의 버전이며 HTTP API 버전과는 별개입니다."},
          "data_through": {"type": "string", "format": "date"},
          "data_source": {"type": "string"},
          "refreshed_at": {"type": "string"}
        },
        "required": [
          "source_facet_type", "source_facet_key", "target_facet_type",
          "target_facet_key", "video_count", "creator_count", "relation_score",
          "data_through", "data_source"
        ]
      },
      "TrendFilterCatalogItem": {
        "type": "object",
        "properties": {
          "dimension_group": {"type": "string"},
          "dimension_type": {"type": "string"},
          "value_key": {"type": "string"},
          "display_name": {"type": "string"},
          "parent_dimension_type": {"type": "string"},
          "parent_value_key": {"type": "string"},
          "sort_order": {"type": "integer"},
          "mapped_video_count": {"type": "integer", "format": "int64"},
          "data_source": {"type": "string"},
          "data_through": {"type": "string", "format": "date"},
          "refreshed_at": {"type": "string"}
        },
        "required": [
          "dimension_group", "dimension_type", "value_key", "display_name",
          "sort_order", "mapped_video_count", "data_source", "data_through"
        ]
      },
      "CreatorTrendRadar": {
        "type": "object",
        "properties": {
          "platform": {"type": "string"},
          "creator_id": {"type": "string"},
          "unique_id": {"type": "string"},
          "handle": {"type": "string"},
          "period_days": {"type": "integer", "enum": [7, 30, 60, 90]},
          "followers": {"anyOf": [{"type": "integer", "format": "int64"}, {"type": "null"}]},
          "follower_tier": {"type": "string"},
          "avg_view_tier": {"type": "string"},
          "creator_gender": {"type": "string"},
          "creator_age_band": {"anyOf": [{"type": "integer"}, {"type": "null"}]},
          "creator_gender_distribution": {"type": "object", "additionalProperties": true},
          "creator_age_distribution": {"type": "object", "additionalProperties": true},
          "creator_attribute_confidence": {"anyOf": [{"type": "number"}, {"type": "null"}]},
          "audience_gender_distribution": {"type": "object", "additionalProperties": true},
          "audience_age_distribution": {"type": "object", "additionalProperties": true},
          "audience_region_distribution": {"type": "object", "additionalProperties": true},
          "top_sub_categories": {"type": "array", "items": {"type": "string"}},
          "analysis_fields": {"type": "object", "additionalProperties": true},
          "video_count": {"type": "integer", "format": "int64"},
          "comparison_video_count": {"type": "integer", "format": "int64"},
          "avg_views": {"anyOf": [{"type": "number"}, {"type": "null"}]},
          "comparison_avg_views": {"anyOf": [{"type": "number"}, {"type": "null"}]},
          "follower_growth_rate": {"anyOf": [{"type": "number"}, {"type": "null"}]},
          "avg_views_growth_rate": {"anyOf": [{"type": "number"}, {"type": "null"}]},
          "posting_growth_rate": {"anyOf": [{"type": "number"}, {"type": "null"}]},
          "engagement_rate": {"anyOf": [{"type": "number"}, {"type": "null"}]},
          "trend_score": {"anyOf": [{"type": "number"}, {"type": "null"}]},
          "score_components": {"type": "object", "additionalProperties": true},
          "creator_quality_score": {"anyOf": [{"type": "number"}, {"type": "null"}]},
          "activation_readiness_score": {"anyOf": [{"type": "number"}, {"type": "null"}]},
          "creator_seeding_fit_score": {"anyOf": [{"type": "number"}, {"type": "null"}]},
          "score_version": {"type": "string", "description": "점수 계산 규칙의 버전이며 HTTP API 버전과는 별개입니다."},
          "confidence": {"type": "string", "enum": ["high", "medium", "low"]},
          "metric_status": {
            "type": "string",
            "enum": ["available", "unavailable", "limited", "stale"]
          },
          "data_source": {
            "type": "string",
            "enum": ["observed", "analyzed", "inferred", "estimated", "verified"]
          },
          "sample_count": {"type": "integer", "format": "int64"},
          "coverage_ratio": {"anyOf": [{"type": "number"}, {"type": "null"}]},
          "data_through": {"type": "string", "format": "date"},
          "limitations": {"type": "array", "items": {"type": "string"}},
          "refreshed_at": {"type": "string"}
        },
        "required": [
          "platform", "creator_id", "period_days", "followers", "creator_age_band",
          "video_count", "comparison_video_count", "trend_score", "score_components",
          "score_version", "metric_status", "data_source", "sample_count",
          "coverage_ratio", "data_through", "limitations"
        ]
      },
      "CreatorSegmentTrend": {
        "allOf": [
          {"$ref": "#/components/schemas/TrendMetricMeta"},
          {
            "type": "object",
            "properties": {
              "period_days": {"type": "integer", "enum": [7, 30, 60, 90], "description": "세그먼트를 집계한 최근 기간입니다."},
              "primary_category": {"type": "string", "description": "analysis_field_catalog의 활성 primary_category 키입니다."},
              "sub_category": {"type": "string", "description": "analysis_field_catalog의 활성 sub_categories 값입니다."},
              "beauty_category": {"type": "string", "description": "analysis_field_catalog의 뷰티 서브카테고리 키입니다."},
              "beauty_category_name": {"type": "string", "description": "뷰티 서브카테고리 표시명입니다."},
              "dimension_type": {"type": "string", "enum": ["follower_tier", "avg_view_tier", "creator_gender", "creator_age", "audience_country"], "description": "비교에 사용한 크리에이터 세그먼트 차원입니다."},
              "dimension_value": {"type": "string", "description": "세그먼트 차원의 실제 값입니다."},
              "creator_count": {"type": "integer", "format": "int64", "description": "해당 세그먼트 값에 포함된 중복 제거 크리에이터 수입니다."},
              "weighted_creator_count": {"type": "number", "description": "티어는 크리에이터 수, 분포형 차원은 관측 비율을 합산한 가중 크리에이터 수입니다."},
              "weighted_video_count": {"type": "number", "description": "크리에이터별 카테고리 영상 수에 세그먼트 비율을 적용한 가중 영상 수입니다."},
              "creator_share": {"anyOf": [{"type": "number"}, {"type": "null"}], "description": "카테고리 전체 크리에이터 대비 가중 크리에이터 비율입니다."},
              "median_followers": {"anyOf": [{"type": "number"}, {"type": "null"}], "description": "세그먼트 크리에이터의 팔로워 중앙값입니다."},
              "median_avg_views": {"anyOf": [{"type": "number"}, {"type": "null"}], "description": "세그먼트 크리에이터의 평균 조회수 중앙값입니다."},
              "weighted_avg_views": {"anyOf": [{"type": "number"}, {"type": "null"}], "description": "세그먼트 비율로 가중한 크리에이터 평균 조회수입니다."},
              "weighted_engagement_rate": {"anyOf": [{"type": "number"}, {"type": "null"}], "description": "세그먼트 비율로 가중한 참여율입니다."},
              "weighted_trend_score": {"anyOf": [{"type": "number"}, {"type": "null"}], "description": "세그먼트 비율로 가중한 트렌드 점수입니다."},
              "view_efficiency": {"anyOf": [{"type": "number"}, {"type": "null"}], "description": "평균 조회수 중앙값을 팔로워 중앙값으로 나눈 조회 효율입니다."},
              "breakout_creator_count": {"type": "number", "description": "트렌드 점수 80 이상 크리에이터의 가중 수입니다."},
              "breakout_share": {"anyOf": [{"type": "number"}, {"type": "null"}], "description": "가중 크리에이터 중 트렌드 점수 80 이상이 차지하는 비율입니다."},
              "observed_creator_count": {"type": "integer", "format": "int64", "description": "해당 차원 값을 하나 이상 보유한 중복 제거 크리에이터 수입니다."},
              "total_creator_count": {"type": "integer", "format": "int64", "description": "같은 기간·카테고리의 전체 중복 제거 크리에이터 수입니다."},
              "score_version": {"type": "string", "description": "크리에이터 세그먼트 집계 규칙 버전입니다."}
            },
            "required": [
              "period_days", "beauty_category", "beauty_category_name",
              "dimension_type", "dimension_value", "creator_count",
              "weighted_creator_count", "weighted_video_count", "creator_share",
              "median_followers", "median_avg_views", "weighted_avg_views",
              "weighted_engagement_rate", "weighted_trend_score", "view_efficiency",
              "breakout_creator_count", "breakout_share", "observed_creator_count",
              "total_creator_count", "score_version"
            ]
          }
        ]
      },
      "ProductTrendRadar": {
        "type": "object",
        "properties": {
          "product_id": {"type": "integer", "format": "int64"},
          "product_name": {"type": "string"},
          "brand_id": {"anyOf": [{"type": "integer", "format": "int64"}, {"type": "null"}]},
          "brand_name": {"type": "string"},
          "product_asin": {"type": "string"},
          "period_days": {"type": "integer", "enum": [7, 30, 60, 90]},
          "mention_video_count": {"type": "integer", "format": "int64"},
          "previous_video_count": {"type": "integer", "format": "int64"},
          "mention_growth_rate": {"anyOf": [{"type": "number"}, {"type": "null"}]},
          "creator_count": {"type": "integer", "format": "int64"},
          "previous_creator_count": {"type": "integer", "format": "int64"},
          "creator_growth_rate": {"anyOf": [{"type": "number"}, {"type": "null"}]},
          "avg_view_velocity": {"anyOf": [{"type": "number"}, {"type": "null"}]},
          "engagement_rate": {"anyOf": [{"type": "number"}, {"type": "null"}]},
          "ad_saturation": {"anyOf": [{"type": "number"}, {"type": "null"}]},
          "organic_strength": {"anyOf": [{"type": "number"}, {"type": "null"}]},
          "gmv_observed_video_count": {"type": "integer", "format": "int64"},
          "attributed_gmv": {"anyOf": [{"type": "number"}, {"type": "null"}]},
          "gmv_coverage_ratio": {"anyOf": [{"type": "number"}, {"type": "null"}]},
          "trend_score": {"anyOf": [{"type": "number"}, {"type": "null"}]},
          "score_components": {"type": "object", "additionalProperties": true},
          "catalog_facets": {"type": "object", "additionalProperties": true},
          "creator_mix": {"type": "object", "additionalProperties": true},
          "audience_mix": {"type": "object", "additionalProperties": true},
          "score_version": {"type": "string", "description": "점수 계산 규칙의 버전이며 HTTP API 버전과는 별개입니다."},
          "confidence": {"type": "string", "enum": ["high", "medium", "low"]},
          "metric_status": {
            "type": "string",
            "enum": ["available", "unavailable", "limited", "stale"]
          },
          "data_source": {
            "type": "string",
            "enum": ["observed", "analyzed", "inferred", "estimated", "verified"]
          },
          "sample_count": {"type": "integer", "format": "int64"},
          "coverage_ratio": {"anyOf": [{"type": "number"}, {"type": "null"}]},
          "data_through": {"type": "string", "format": "date"},
          "limitations": {"type": "array", "items": {"type": "string"}},
          "refreshed_at": {"type": "string"}
        },
        "required": [
          "product_id", "product_name", "brand_id", "period_days",
          "mention_video_count", "previous_video_count", "creator_count",
          "previous_creator_count", "gmv_observed_video_count", "trend_score",
          "score_components", "score_version", "metric_status", "data_source",
          "sample_count", "coverage_ratio", "data_through", "limitations"
        ]
      },
      "VideoGrowthBenchmark": {
        "allOf": [
          {"$ref": "#/components/schemas/TrendMetricMeta"},
          {
            "type": "object",
            "properties": {
              "platform": {"type": "string"},
              "video_id": {"type": "string"},
              "creator_id": {"type": "string"},
              "unique_id": {"type": "string"},
              "handle": {"type": "string"},
              "video_url": {"type": "string"},
              "caption": {"type": "string"},
              "video_created_date": {"type": "string", "format": "date"},
              "period_days": {"type": "integer", "enum": [7, 30, 60, 90]},
              "category_key": {"type": "string"},
              "category_name": {"type": "string"},
              "follower_tier": {"type": "string"},
              "avg_view_tier": {"type": "string"},
              "followers": {"anyOf": [{"type": "integer", "format": "int64"}, {"type": "null"}]},
              "views": {"anyOf": [{"type": "integer", "format": "int64"}, {"type": "null"}]},
              "likes": {"anyOf": [{"type": "integer", "format": "int64"}, {"type": "null"}]},
              "comments": {"anyOf": [{"type": "integer", "format": "int64"}, {"type": "null"}]},
              "shares": {"anyOf": [{"type": "integer", "format": "int64"}, {"type": "null"}]},
              "engagement_rate": {"anyOf": [{"type": "number"}, {"type": "null"}]},
              "creator_median_views": {"anyOf": [{"type": "number"}, {"type": "null"}]},
              "creator_baseline_video_count": {"type": "integer", "format": "int64"},
              "outlier_index": {"anyOf": [{"type": "number"}, {"type": "null"}]},
              "view_percentile": {"anyOf": [{"type": "number"}, {"type": "null"}]},
              "outlier_percentile": {"anyOf": [{"type": "number"}, {"type": "null"}]},
              "observed_gmv": {"anyOf": [{"type": "number"}, {"type": "null"}]},
              "observed_gpm": {"anyOf": [{"type": "number"}, {"type": "null"}]},
              "gmv_percentile": {"anyOf": [{"type": "number"}, {"type": "null"}]},
              "gmv_coverage_ratio": {"anyOf": [{"type": "number"}, {"type": "null"}]},
              "is_ad": {"anyOf": [{"type": "boolean"}, {"type": "null"}]},
              "content_type": {"type": "string"},
              "content_format": {"type": "string"},
              "analysis_facets": {"type": "object", "additionalProperties": true},
              "view_rank": {"type": "integer", "format": "int64"},
              "outlier_rank": {"type": "integer", "format": "int64"},
              "gmv_rank": {"type": "integer", "format": "int64"},
              "creator_count": {"type": "integer", "format": "int64"},
              "score_version": {"type": "string", "description": "영상 성장 벤치마크 계산 규칙 버전입니다."}
            },
            "required": [
              "platform", "video_id", "creator_id", "video_created_date", "period_days",
              "category_key", "category_name", "followers", "views", "likes", "comments",
              "shares", "engagement_rate", "creator_median_views", "creator_baseline_video_count",
              "outlier_index", "view_percentile", "outlier_percentile", "observed_gmv",
              "observed_gpm", "gmv_percentile", "gmv_coverage_ratio", "is_ad",
              "analysis_facets", "view_rank", "outlier_rank", "gmv_rank", "creator_count",
              "score_version"
            ]
          }
        ]
      },
      "CreatorPeerBenchmark": {
        "allOf": [
          {"$ref": "#/components/schemas/TrendMetricMeta"},
          {
            "type": "object",
            "properties": {
              "platform": {"type": "string"},
              "creator_id": {"type": "string"},
              "unique_id": {"type": "string"},
              "handle": {"type": "string"},
              "period_days": {"type": "integer", "enum": [7, 30, 60, 90]},
              "category_key": {"type": "string"},
              "category_name": {"type": "string"},
              "follower_tier": {"type": "string"},
              "avg_view_tier": {"type": "string"},
              "followers": {"anyOf": [{"type": "integer", "format": "int64"}, {"type": "null"}]},
              "video_count": {"type": "integer", "format": "int64"},
              "avg_views": {"anyOf": [{"type": "number"}, {"type": "null"}]},
              "engagement_rate": {"anyOf": [{"type": "number"}, {"type": "null"}]},
              "follower_growth_rate": {"anyOf": [{"type": "number"}, {"type": "null"}]},
              "avg_views_growth_rate": {"anyOf": [{"type": "number"}, {"type": "null"}]},
              "posting_growth_rate": {"anyOf": [{"type": "number"}, {"type": "null"}]},
              "trend_score": {"anyOf": [{"type": "number"}, {"type": "null"}]},
              "avg_views_percentile": {"anyOf": [{"type": "number"}, {"type": "null"}]},
              "engagement_percentile": {"anyOf": [{"type": "number"}, {"type": "null"}]},
              "growth_percentile": {"anyOf": [{"type": "number"}, {"type": "null"}]},
              "posting_consistency_percentile": {"anyOf": [{"type": "number"}, {"type": "null"}]},
              "trend_percentile": {"anyOf": [{"type": "number"}, {"type": "null"}]},
              "peer_count": {"type": "integer", "format": "int64"},
              "score_version": {"type": "string", "description": "동료 비교 계산 규칙 버전입니다."}
            },
            "required": [
              "platform", "creator_id", "period_days", "category_key", "category_name",
              "followers", "video_count", "avg_views", "engagement_rate",
              "follower_growth_rate", "avg_views_growth_rate", "posting_growth_rate",
              "trend_score", "avg_views_percentile", "engagement_percentile",
              "growth_percentile", "posting_consistency_percentile", "trend_percentile",
              "peer_count", "score_version"
            ]
          }
        ]
      },
      "CreatorGrowthOpportunity": {
        "allOf": [
          {"$ref": "#/components/schemas/TrendMetricMeta"},
          {
            "type": "object",
            "properties": {
              "creator_id": {"type": "string"},
              "objective": {"type": "string", "enum": ["reach", "authority", "monetization"]},
              "facet_type": {"type": "string"},
              "facet_key": {"type": "string"},
              "beauty_category": {"type": "string"},
              "title": {"type": "string"},
              "opportunity_score": {"anyOf": [{"type": "number"}, {"type": "null"}]},
              "score_components": {"type": "object", "additionalProperties": true},
              "why_now": {"type": "string"},
              "why_creator": {"type": "string"},
              "recommended_action": {"type": "string"},
              "evidence_videos": {"type": "array", "items": {"$ref": "#/components/schemas/VideoGrowthBenchmark"}},
              "score_version": {"type": "string", "description": "크리에이터 성장 기회 점수 규칙 버전입니다."}
            },
            "required": [
              "creator_id", "objective", "facet_type", "facet_key", "beauty_category",
              "title", "opportunity_score", "score_components", "why_now", "why_creator",
              "recommended_action", "evidence_videos", "score_version"
            ]
          }
        ]
      },
      "CreatorContentBriefRequest": {
        "type": "object",
        "properties": {
          "objective": {"type": "string", "enum": ["reach", "authority", "monetization"], "description": "도달, 전문성 또는 수익화 중 콘텐츠 목표입니다."},
          "facet_type": {"type": "string", "description": "선택할 분석 관점 종류입니다. facet_key와 함께 생략할 수 있습니다."},
          "facet_key": {"type": "string", "description": "선택할 분석 관점 값입니다. facet_type과 함께 생략할 수 있습니다."},
          "period_days": {"type": "integer", "enum": [7, 30, 60, 90], "default": 30, "description": "근거 트렌드 분석 기간입니다."}
        },
        "additionalProperties": false
      },
      "CreatorContentBrief": {
        "allOf": [
          {"$ref": "#/components/schemas/TrendMetricMeta"},
          {
            "type": "object",
            "properties": {
              "creator_id": {"type": "string"},
              "objective": {"type": "string", "enum": ["reach", "authority", "monetization"]},
              "facet_type": {"type": "string"},
              "facet_key": {"type": "string"},
              "beauty_category": {"type": "string"},
              "title": {"type": "string"},
              "why_now": {"type": "string"},
              "why_creator": {"type": "string"},
              "hooks": {"type": "array", "items": {"type": "string"}},
              "production_steps": {"type": "array", "items": {"type": "string"}},
              "suggested_formats": {"type": "array", "items": {"type": "string"}},
              "demo_methods": {"type": "array", "items": {"type": "string"}},
              "claims": {"type": "array", "items": {"type": "string"}},
              "risk_notes": {"type": "array", "items": {"type": "string"}},
              "evidence_videos": {"type": "array", "items": {"$ref": "#/components/schemas/VideoGrowthBenchmark"}},
              "score_version": {"type": "string", "description": "콘텐츠 브리프 생성 규칙 버전입니다."}
            },
            "required": [
              "creator_id", "objective", "facet_type", "facet_key", "beauty_category",
              "title", "why_now", "why_creator", "hooks", "production_steps",
              "suggested_formats", "demo_methods", "claims", "risk_notes",
              "evidence_videos", "score_version"
            ]
          }
        ]
      },
      "TrendFilterCatalogPage": {
        "type": "object",
        "properties": {
          "items": {"type": "array", "items": {"$ref": "#/components/schemas/TrendFilterCatalogItem"}},
          "total_count": {"type": "integer"},
          "start": {"type": "integer"},
          "limit": {"type": "integer"}
        },
        "required": ["items", "total_count", "start", "limit"]
      },
      "CreatorTrendRadarPage": {
        "type": "object",
        "properties": {
          "items": {"type": "array", "items": {"$ref": "#/components/schemas/CreatorTrendRadar"}},
          "total_count": {"type": "integer"},
          "start": {"type": "integer"},
          "limit": {"type": "integer"}
        },
        "required": ["items", "total_count", "start", "limit"]
      },
      "CreatorSegmentTrendPage": {
        "type": "object",
        "properties": {
          "items": {"type": "array", "items": {"$ref": "#/components/schemas/CreatorSegmentTrend"}},
          "total_count": {"type": "integer"},
          "start": {"type": "integer"},
          "limit": {"type": "integer"}
        },
        "required": ["items", "total_count", "start", "limit"]
      },
      "ProductTrendRadarPage": {
        "type": "object",
        "properties": {
          "items": {"type": "array", "items": {"$ref": "#/components/schemas/ProductTrendRadar"}},
          "total_count": {"type": "integer"},
          "start": {"type": "integer"},
          "limit": {"type": "integer"}
        },
        "required": ["items", "total_count", "start", "limit"]
      },
      "BeautyTrendRadarPage": {
        "type": "object",
        "properties": {
          "items": {"type": "array", "items": {"$ref": "#/components/schemas/BeautyTrendRadar"}},
          "total_count": {"type": "integer"},
          "start": {"type": "integer"},
          "limit": {"type": "integer"}
        },
        "required": ["items", "total_count", "start", "limit"]
      },
      "BeautyTrendRelationPage": {
        "type": "object",
        "properties": {
          "items": {"type": "array", "items": {"$ref": "#/components/schemas/BeautyTrendRelation"}},
          "total_count": {"type": "integer"},
          "start": {"type": "integer"},
          "limit": {"type": "integer"}
        },
        "required": ["items", "total_count", "start", "limit"]
      },
      "VideoGrowthBenchmarkPage": {
        "type": "object",
        "properties": {
          "items": {"type": "array", "items": {"$ref": "#/components/schemas/VideoGrowthBenchmark"}},
          "total_count": {"type": "integer"},
          "start": {"type": "integer"},
          "limit": {"type": "integer"}
        },
        "required": ["items", "total_count", "start", "limit"]
      },
      "CreatorPeerBenchmarkPage": {
        "type": "object",
        "properties": {
          "items": {"type": "array", "items": {"$ref": "#/components/schemas/CreatorPeerBenchmark"}},
          "total_count": {"type": "integer"},
          "start": {"type": "integer"},
          "limit": {"type": "integer"}
        },
        "required": ["items", "total_count", "start", "limit"]
      },
      "CreatorGrowthOpportunityPage": {
        "type": "object",
        "properties": {
          "items": {"type": "array", "items": {"$ref": "#/components/schemas/CreatorGrowthOpportunity"}},
          "total_count": {"type": "integer"},
          "start": {"type": "integer"},
          "limit": {"type": "integer"}
        },
        "required": ["items", "total_count", "start", "limit"]
      },
      "ErrorResponse": {
        "type": "object",
        "description": "API 요청 처리 중 발생한 일반 오류입니다.",
        "properties": {
          "detail": {"type": "string", "description": "오류 원인을 설명하는 메시지입니다."}
        },
        "required": ["detail"],
        "additionalProperties": false
      }
    },
    "responses": {
      "BadRequest": {
        "description": "요청 조합 또는 페이지 범위가 올바르지 않습니다.",
        "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorResponse"}}}
      },
      "NotFound": {
        "description": "요청한 리소스를 찾을 수 없습니다.",
        "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorResponse"}}}
      },
      "Conflict": {
        "description": "식별자가 둘 이상의 리소스와 일치해 하나로 결정할 수 없습니다.",
        "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorResponse"}}}
      },
      "ValidationError": {
        "description": "경로, 쿼리 또는 본문 입력값이 올바르지 않습니다.",
        "content": {
          "application/json": {
            "schema": {
              "oneOf": [
                {"$ref": "#/components/schemas/HTTPValidationError"},
                {"$ref": "#/components/schemas/ErrorResponse"}
              ]
            }
          }
        }
      },
      "TooManyRequests": {
        "description": "요청 속도 또는 동시 처리 한도를 초과했습니다.",
        "headers": {
          "Retry-After": {
            "description": "재시도까지 기다릴 초 단위 시간입니다.",
            "schema": {"type": "integer", "minimum": 1}
          }
        },
        "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorResponse"}}}
      },
      "ServiceUnavailable": {
        "description": "필요한 스냅샷 또는 데이터 소스를 사용할 수 없습니다.",
        "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorResponse"}}}
      }
    },
    "parameters": {
      "TrendStart": {
        "in": "query",
        "name": "start",
        "required": false,
        "description": "0부터 시작하는 결과 위치입니다. 기본값은 0이며 start와 limit의 합은 100,000 이하여야 합니다.",
        "schema": {
          "type": "integer",
          "minimum": 0,
          "maximum": 100000,
          "default": 0
        }
      },
      "TrendLimit": {
        "in": "query",
        "name": "limit",
        "required": false,
        "description": "한 번에 반환할 항목 수입니다. 기본값은 20이며 최대 200개입니다.",
        "schema": {
          "type": "integer",
          "minimum": 1,
          "maximum": 200,
          "default": 20
        }
      },
      "GrowthPeriodDays": {
        "in": "query",
        "name": "period_days",
        "required": false,
        "description": "성장 근거를 집계할 기간입니다. 기본값은 최근 30일입니다.",
        "schema": {
          "type": "integer",
          "enum": [7, 30, 60, 90],
          "default": 30
        }
      },
      "CreatorQuery": {
        "in": "query",
        "name": "query",
        "required": false,
        "description": "크리에이터 ID, 핸들, 상품, 브랜드 또는 콘텐츠 포맷 검색어",
        "schema": {"type": "string"}
      },
      "CreatorSegment": {
        "in": "query",
        "name": "segment",
        "required": false,
        "description": "크리에이터 성장 특성입니다. 생략하면 모든 세그먼트를 조회합니다.",
        "schema": {
          "type": "string",
          "enum": ["million_view", "newly_observed", "fast_growing"]
        }
      },
      "CreatorProduct": {
        "in": "query",
        "name": "product",
        "required": false,
        "description": "콘텐츠에서 다룬 상품명 또는 상품 키 필터입니다.",
        "schema": {"type": "string"}
      },
      "CreatorBrand": {
        "in": "query",
        "name": "brand",
        "required": false,
        "description": "콘텐츠에서 다룬 브랜드명 또는 브랜드 키 필터입니다.",
        "schema": {"type": "string"}
      },
      "CreatorFormat": {
        "in": "query",
        "name": "format",
        "required": false,
        "description": "리뷰, 튜토리얼 등 콘텐츠 형식 필터입니다.",
        "schema": {"type": "string"}
      },
      "CreatorCategory": {
        "in": "query",
        "name": "category",
        "required": false,
        "description": "sub_category의 한시적 호환 alias입니다.",
        "schema": {"type": "string"}
      },
      "PrimaryCategory": {
        "in": "query",
        "name": "primary_category",
        "required": false,
        "description": "analysis_field_catalog의 활성 primary_category 키입니다.",
        "schema": {"type": "string"}
      },
      "SubCategory": {
        "in": "query",
        "name": "sub_category",
        "required": false,
        "description": "analysis_field_catalog의 활성 sub_categories 값입니다. primary_category와 함께 쓰면 부모가 일치해야 합니다.",
        "schema": {"type": "string"}
      },
      "CreatorSkinConcern": {
        "in": "query",
        "name": "skin_concern",
        "required": false,
        "description": "건조함, 민감성 등 피부 고민 필터입니다.",
        "schema": {"type": "string"}
      },
      "CreatorClaim": {
        "in": "query",
        "name": "claim",
        "required": false,
        "description": "보습, 진정 등 콘텐츠의 제품 효능 표현 필터입니다.",
        "schema": {"type": "string"}
      },
      "CreatorDemoMethod": {
        "in": "query",
        "name": "demo_method",
        "required": false,
        "description": "제품 사용 또는 시연 방식 필터입니다.",
        "schema": {"type": "string"}
      },
      "CreatorContactable": {
        "in": "query",
        "name": "contactable",
        "required": false,
        "description": "true면 연락처가 확인된 크리에이터만, false면 확인되지 않은 크리에이터만 조회합니다. 생략하면 제한하지 않습니다.",
        "schema": {"type": "boolean"}
      },
      "CreatorMaxAdDensity": {
        "in": "query",
        "name": "max_ad_density",
        "required": false,
        "description": "허용할 최근 콘텐츠의 최대 광고 밀도입니다. 0부터 1 사이의 비율입니다.",
        "schema": {"type": "number", "minimum": 0, "maximum": 1}
      },
      "CreatorSort": {
        "in": "query",
        "name": "sort",
        "required": false,
        "description": "결과 정렬 기준입니다. 기본값은 시딩 적합도 내림차순입니다.",
        "schema": {
          "type": "string",
          "enum": [
            "seeding_fit_desc", "breakout_desc", "quality_desc",
            "activation_desc", "followers_desc", "avg_views_desc", "engagement_desc"
          ],
          "default": "seeding_fit_desc"
        }
      },
      "CreatorMinFollowers": {
        "in": "query",
        "name": "min_followers",
        "required": false,
        "description": "최소 팔로워 수입니다.",
        "schema": {"type": "integer", "format": "int64", "minimum": 0}
      },
      "CreatorMaxFollowers": {
        "in": "query",
        "name": "max_followers",
        "required": false,
        "description": "최대 팔로워 수입니다.",
        "schema": {"type": "integer", "format": "int64", "minimum": 0}
      },
      "CreatorMinAverageViews": {
        "in": "query",
        "name": "min_avg_views",
        "required": false,
        "description": "최근 분석 영상의 최소 평균 조회수입니다.",
        "schema": {"type": "number", "minimum": 0}
      },
      "CreatorMinEngagementRate": {
        "in": "query",
        "name": "min_engagement_rate",
        "required": false,
        "description": "최소 참여율입니다. 0부터 1 사이의 비율입니다.",
        "schema": {"type": "number", "minimum": 0, "maximum": 1}
      },
      "ProductQuery": {
        "in": "query",
        "name": "query",
        "required": false,
        "description": "상품명, 상품 키 또는 브랜드 키 검색어",
        "schema": {"type": "string"}
      },
      "ProductPeriodDays": {
        "in": "query",
        "name": "period_days",
        "required": false,
        "description": "상품 관심도를 집계할 기간입니다. 기본값은 최근 7일입니다.",
        "schema": {
          "type": "integer",
          "enum": [7, 30],
          "default": 7
        }
      }
    }
  },
  "info": {
    "description": "크리에이터 추천, 종합 분석, 트렌드와 상품 인사이트를 제공하는 v1 API입니다. /v1은 HTTP 계약의 주 버전이며 응답의 score_version, feature_version 등은 데이터 계산 규칙 버전으로 API 버전과 별개입니다.",
    "title": "Agent API",
    "version": "1.0.0"
  },
  "openapi": "3.1.0",
  "servers": [
    {
      "url": ".",
      "description": "현재 Swagger 문서와 동일한 API 경로"
    }
  ],
  "tags": [
    {"name": "시스템", "description": "서비스 상태와 운영 확인 API"},
    {"name": "카탈로그", "description": "추천·검색 조건과 분석 필드 카탈로그 API"},
    {"name": "크리에이터 추천", "description": "프리셋·조건·자연어 기반 크리에이터 추천 API"},
    {"name": "크리에이터", "description": "크리에이터 검색, 프로필, 분석, 근거 영상과 예상 가격 API"},
    {"name": "트렌드", "description": "뷰티·크리에이터·상품·성분 트렌드와 이력·연관 관계 API"},
    {"name": "상품", "description": "상품 검색, 상세 분석, 추천 크리에이터와 홍보 패턴 API"},
    {"name": "인사이트", "description": "주간 브리프와 데이터 가용 상태 API"}
  ],
  "paths": {
    "/health": {
      "get": {
        "tags": ["시스템"],
        "summary": "서비스 상태 확인",
        "description": "프로세스가 HTTP 요청을 처리할 수 있는지 확인합니다.",
        "operationId": "getHealth",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": {
                    "type": "string"
                  },
                  "title": "Response Health Health Get",
                  "type": "object"
                }
              }
            },
            "description": "서비스명과 정상 상태를 반환합니다."
          }
        }
      }
    },
    "/v1/creators/search": {
      "get": {
        "tags": ["크리에이터"],
        "summary": "크리에이터 검색",
        "description": "필터와 정렬 조건으로 크리에이터 목록을 검색합니다. 상세 분석은 개별 조회 API에서 제공합니다.",
        "operationId": "searchCreators",
        "parameters": [
          {"$ref": "#/components/parameters/CreatorQuery"},
          {"$ref": "#/components/parameters/CreatorSegment"},
          {"$ref": "#/components/parameters/CreatorProduct"},
          {"$ref": "#/components/parameters/CreatorBrand"},
          {"$ref": "#/components/parameters/CreatorFormat"},
          {"$ref": "#/components/parameters/CreatorCategory"},
          {"$ref": "#/components/parameters/PrimaryCategory"},
          {"$ref": "#/components/parameters/SubCategory"},
          {"$ref": "#/components/parameters/CreatorSkinConcern"},
          {"$ref": "#/components/parameters/CreatorClaim"},
          {"$ref": "#/components/parameters/CreatorDemoMethod"},
          {"$ref": "#/components/parameters/CreatorContactable"},
          {"$ref": "#/components/parameters/CreatorMaxAdDensity"},
          {"$ref": "#/components/parameters/CreatorSort"},
          {"$ref": "#/components/parameters/CreatorMinFollowers"},
          {"$ref": "#/components/parameters/CreatorMaxFollowers"},
          {"$ref": "#/components/parameters/CreatorMinAverageViews"},
          {"$ref": "#/components/parameters/CreatorMinEngagementRate"},
          {"$ref": "#/components/parameters/TrendStart"},
          {"$ref": "#/components/parameters/TrendLimit"}
        ],
        "responses": {
          "200": {
            "description": "목록 렌더링용 최소 크리에이터 검색 결과",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreatorSearchPage"
                }
              }
            }
          },
          "400": {"$ref": "#/components/responses/BadRequest"},
          "422": {"$ref": "#/components/responses/ValidationError"},
          "429": {"$ref": "#/components/responses/TooManyRequests"},
          "503": {"$ref": "#/components/responses/ServiceUnavailable"}
        }
      }
    },
    "/v1/creators/video-previews": {
      "get": {
        "tags": ["크리에이터"],
        "summary": "크리에이터 대표 영상 일괄 조회",
        "description": "목록 화면에 표시할 여러 크리에이터의 대표 영상을 요청 순서대로 조회합니다.",
        "operationId": "getCreatorVideoPreviews",
        "parameters": [
          {
            "in": "query",
            "name": "creator_ids",
            "required": true,
            "description": "쉼표로 구분한 크리에이터 ID. 최대 20개",
            "schema": {"type": "string"}
          },
          {
            "in": "query",
            "name": "limit_per_creator",
            "required": false,
            "description": "크리에이터 한 명당 반환할 대표 영상 수입니다. 기본값은 2개이며 최대 3개입니다.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 3,
              "default": 2
            }
          }
        ],
        "responses": {
          "200": {
            "description": "요청한 순서대로 반환되는 대표 영상 그룹",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreatorVideoPreviewResponse"
                }
              }
            }
          },
          "422": {"$ref": "#/components/responses/ValidationError"},
          "429": {"$ref": "#/components/responses/TooManyRequests"},
          "503": {"$ref": "#/components/responses/ServiceUnavailable"}
        }
      }
    },
    "/v1/creators/{creatorId}": {
      "get": {
        "tags": ["크리에이터"],
        "summary": "크리에이터 기본 프로필 조회",
        "description": "크리에이터 식별자, 핸들, 팔로워와 분석 가용 상태를 포함한 기본 프로필을 조회합니다.",
        "operationId": "getCreatorProfile",
        "parameters": [
          {
            "in": "path",
            "name": "creatorId",
            "required": true,
            "description": "creator ID, TikTok unique ID 또는 @handle입니다.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "검색 디렉터리 기준의 안정적인 기본 프로필",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreatorProfile"
                }
              }
            }
          },
          "404": {"$ref": "#/components/responses/NotFound"},
          "429": {"$ref": "#/components/responses/TooManyRequests"},
          "503": {"$ref": "#/components/responses/ServiceUnavailable"}
        }
      }
    },
    "/v1/creators/{creatorId}/intelligence": {
      "get": {
        "tags": ["크리에이터"],
        "summary": "크리에이터 종합 분석 조회",
        "description": "크리에이터의 전문성, 성과, 점수, 오디언스와 상업 신호를 종합해 조회합니다.",
        "operationId": "getCreatorIntelligence",
        "parameters": [
          {
            "in": "path",
            "name": "creatorId",
            "required": true,
            "description": "creator ID, TikTok unique ID 또는 @handle입니다.",
            "schema": {"type": "string"}
          }
        ],
        "responses": {
          "200": {
            "description": "근거 영상과 가격을 제외한 크리에이터 분석",
            "content": {
              "application/json": {
                "schema": {"$ref": "#/components/schemas/CreatorIntelligence"}
              }
            }
          },
          "404": {"$ref": "#/components/responses/NotFound"},
          "429": {"$ref": "#/components/responses/TooManyRequests"},
          "503": {"$ref": "#/components/responses/ServiceUnavailable"}
        }
      }
    },
    "/v1/creators/{creatorId}/history": {
      "get": {
        "tags": ["크리에이터"],
        "summary": "크리에이터 성과 이력 조회",
        "description": "최근 120일은 일별, 이전 구간은 월별 크리에이터 성과와 점수 이력을 조회합니다.",
        "operationId": "getCreatorHistory",
        "parameters": [
          {
            "in": "path",
            "name": "creatorId",
            "required": true,
            "description": "creator ID, TikTok unique ID 또는 @handle입니다.",
            "schema": {"type": "string"}
          },
          {
            "in": "query",
            "name": "from",
            "required": false,
            "description": "조회 시작일입니다. YYYY-MM-DD 형식이며 생략하면 시작일을 제한하지 않습니다.",
            "schema": {"type": "string", "format": "date"}
          },
          {
            "in": "query",
            "name": "to",
            "required": false,
            "description": "조회 종료일입니다. YYYY-MM-DD 형식이며 생략하면 종료일을 제한하지 않습니다.",
            "schema": {"type": "string", "format": "date"}
          }
        ],
        "responses": {
          "200": {
            "description": "일별·월별 크리에이터 이력",
            "content": {
              "application/json": {
                "schema": {"$ref": "#/components/schemas/CreatorHistoryPage"}
              }
            }
          },
          "404": {"$ref": "#/components/responses/NotFound"},
          "409": {"$ref": "#/components/responses/Conflict"},
          "422": {"$ref": "#/components/responses/ValidationError"},
          "429": {"$ref": "#/components/responses/TooManyRequests"},
          "503": {"$ref": "#/components/responses/ServiceUnavailable"}
        }
      }
    },
    "/v1/creators/{creatorId}/peer-benchmark": {
      "get": {
        "tags": ["크리에이터"],
        "summary": "크리에이터 동료 비교 조회",
        "description": "같은 뷰티 카테고리와 팔로워 티어 크리에이터 사이의 조회·참여·성장·게시 백분위를 조회합니다.",
        "operationId": "getCreatorPeerBenchmark",
        "parameters": [
          {
            "in": "path",
            "name": "creatorId",
            "required": true,
            "description": "creator ID, TikTok unique ID 또는 @handle입니다.",
            "schema": {"type": "string"}
          },
          {"$ref": "#/components/parameters/GrowthPeriodDays"},
          {
            "in": "query",
            "name": "category",
            "required": false,
            "description": "sub_category의 한시적 호환 alias입니다.",
            "schema": {"type": "string"}
          },
          {"$ref": "#/components/parameters/PrimaryCategory"},
          {"$ref": "#/components/parameters/SubCategory"}
        ],
        "responses": {
          "200": {
            "description": "카테고리별 동료 비교 백분위 목록",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/CreatorPeerBenchmarkPage"}}}
          },
          "400": {"$ref": "#/components/responses/BadRequest"},
          "404": {"$ref": "#/components/responses/NotFound"},
          "409": {"$ref": "#/components/responses/Conflict"},
          "422": {"$ref": "#/components/responses/ValidationError"},
          "429": {"$ref": "#/components/responses/TooManyRequests"},
          "503": {"$ref": "#/components/responses/ServiceUnavailable"}
        }
      }
    },
    "/v1/creators/{creatorId}/growth-opportunities": {
      "get": {
        "tags": ["크리에이터"],
        "summary": "크리에이터 성장 기회 조회",
        "description": "크리에이터의 기존 전문성과 최근 시장 모멘텀을 연결해 근거 영상이 포함된 콘텐츠 성장 기회를 조회합니다.",
        "operationId": "listCreatorGrowthOpportunities",
        "parameters": [
          {
            "in": "path",
            "name": "creatorId",
            "required": true,
            "description": "creator ID, TikTok unique ID 또는 @handle입니다.",
            "schema": {"type": "string"}
          },
          {"$ref": "#/components/parameters/GrowthPeriodDays"},
          {"in": "query", "name": "sort", "required": false, "description": "성장 기회 정렬입니다.", "schema": {"type": "string", "enum": ["opportunity_score_desc", "confidence_desc", "title_asc"], "default": "opportunity_score_desc"}},
          {"$ref": "#/components/parameters/TrendStart"},
          {"$ref": "#/components/parameters/TrendLimit"}
        ],
        "responses": {
          "200": {
            "description": "설명과 근거 영상을 포함한 성장 기회 목록",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/CreatorGrowthOpportunityPage"}}}
          },
          "400": {"$ref": "#/components/responses/BadRequest"},
          "404": {"$ref": "#/components/responses/NotFound"},
          "409": {"$ref": "#/components/responses/Conflict"},
          "422": {"$ref": "#/components/responses/ValidationError"},
          "429": {"$ref": "#/components/responses/TooManyRequests"},
          "503": {"$ref": "#/components/responses/ServiceUnavailable"}
        }
      }
    },
    "/v1/creators/{creatorId}/content-briefs": {
      "post": {
        "tags": ["크리에이터"],
        "summary": "크리에이터 콘텐츠 브리프 생성",
        "description": "선택한 성장 기회와 대표 영상 근거를 사용해 훅, 제작 순서, 포맷과 주의사항을 생성합니다.",
        "operationId": "createCreatorContentBrief",
        "parameters": [
          {
            "in": "path",
            "name": "creatorId",
            "required": true,
            "description": "creator ID, TikTok unique ID 또는 @handle입니다.",
            "schema": {"type": "string"}
          }
        ],
        "requestBody": {
          "required": true,
          "description": "콘텐츠 목표와 선택할 분석 관점입니다. 분석 관점을 생략하면 가장 높은 성장 기회를 사용합니다.",
          "content": {"application/json": {"schema": {"$ref": "#/components/schemas/CreatorContentBriefRequest"}}}
        },
        "responses": {
          "200": {
            "description": "근거와 위험 요소를 포함한 콘텐츠 제작 브리프",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/CreatorContentBrief"}}}
          },
          "404": {"$ref": "#/components/responses/NotFound"},
          "409": {"$ref": "#/components/responses/Conflict"},
          "422": {"$ref": "#/components/responses/ValidationError"},
          "429": {"$ref": "#/components/responses/TooManyRequests"},
          "503": {"$ref": "#/components/responses/ServiceUnavailable"}
        }
      }
    },
    "/v1/creators/{creatorId}/evidence-videos": {
      "get": {
        "tags": ["크리에이터"],
        "summary": "크리에이터 분석 근거 영상 조회",
        "description": "크리에이터 분석 결과의 근거가 된 영상을 페이지 단위로 조회합니다.",
        "operationId": "listCreatorEvidenceVideos",
        "parameters": [
          {
            "in": "path",
            "name": "creatorId",
            "required": true,
            "description": "creator ID, TikTok unique ID 또는 @handle입니다.",
            "schema": {"type": "string"}
          },
          {"in": "query", "name": "sort", "required": false, "description": "근거 영상 정렬입니다.", "schema": {"type": "string", "enum": ["evidence_rank", "views_desc", "recent_desc"], "default": "evidence_rank"}},
          {"$ref": "#/components/parameters/TrendStart"},
          {"$ref": "#/components/parameters/TrendLimit"}
        ],
        "responses": {
          "200": {
            "description": "페이지 단위 근거 영상",
            "content": {
              "application/json": {
                "schema": {"$ref": "#/components/schemas/CreatorEvidenceVideoPage"}
              }
            }
          },
          "400": {"$ref": "#/components/responses/BadRequest"},
          "404": {"$ref": "#/components/responses/NotFound"},
          "409": {"$ref": "#/components/responses/Conflict"},
          "422": {"$ref": "#/components/responses/ValidationError"},
          "429": {"$ref": "#/components/responses/TooManyRequests"},
          "503": {"$ref": "#/components/responses/ServiceUnavailable"}
        }
      }
    },
    "/v1/creators/{creatorId}/products": {
      "get": {
        "tags": ["크리에이터"],
        "summary": "크리에이터별 상품 적합도 조회",
        "description": "크리에이터와 상품 사이의 적합 점수와 계산 근거를 조회합니다.",
        "operationId": "listCreatorProducts",
        "parameters": [
          {
            "in": "path",
            "name": "creatorId",
            "required": true,
            "description": "creator ID, TikTok unique ID 또는 @handle입니다.",
            "schema": {
              "type": "string"
            }
          },
          {"in": "query", "name": "sort", "required": false, "description": "상품 적합도 정렬입니다.", "schema": {"type": "string", "enum": ["fit_score_desc", "related_views_desc", "engagement_desc", "video_count_desc"], "default": "fit_score_desc"}},
          {"$ref": "#/components/parameters/TrendStart"},
          {"$ref": "#/components/parameters/TrendLimit"}
        ],
        "responses": {
          "200": {
            "description": "상품 적합도 목록",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreatorProductFitPage"
                }
              }
            }
          },
          "400": {"$ref": "#/components/responses/BadRequest"},
          "404": {"$ref": "#/components/responses/NotFound"},
          "409": {"$ref": "#/components/responses/Conflict"},
          "422": {"$ref": "#/components/responses/ValidationError"},
          "429": {"$ref": "#/components/responses/TooManyRequests"},
          "503": {"$ref": "#/components/responses/ServiceUnavailable"}
        }
      }
    },
    "/v1/videos/benchmarks": {
      "get": {
        "tags": ["트렌드"],
        "summary": "성장 근거 영상 조회",
        "description": "뷰티 카테고리·팔로워 티어별 조회 상위, 본인 평소 대비 고성과와 관측 GMV 영상 후보를 조회합니다.",
        "operationId": "listVideoGrowthBenchmarks",
        "parameters": [
          {"$ref": "#/components/parameters/GrowthPeriodDays"},
          {
            "in": "query",
            "name": "query",
            "required": false,
            "description": "캡션, 크리에이터 핸들 또는 분석 관점 검색어입니다.",
            "schema": {"type": "string"}
          },
          {
            "in": "query",
            "name": "category",
            "required": false,
            "description": "sub_category의 한시적 호환 alias입니다.",
            "schema": {"type": "string"}
          },
          {"$ref": "#/components/parameters/PrimaryCategory"},
          {"$ref": "#/components/parameters/SubCategory"},
          {
            "in": "query",
            "name": "follower_tier",
            "required": false,
            "description": "비교할 팔로워 규모 티어입니다.",
            "schema": {"type": "string"}
          },
          {
            "in": "query",
            "name": "metric_status",
            "required": false,
            "description": "available, limited 또는 stale 데이터 상태 필터입니다.",
            "schema": {"type": "string", "enum": ["available", "limited", "stale"]}
          },
          {
            "in": "query",
            "name": "sort",
            "required": false,
            "description": "평소 대비 성과, 조회수, 관측 GMV 또는 참여율 정렬 기준입니다. 기본값은 평소 대비 성과입니다.",
            "schema": {"type": "string", "enum": ["outlier", "views", "gmv", "engagement"], "default": "outlier"}
          },
          {"$ref": "#/components/parameters/TrendStart"},
          {"$ref": "#/components/parameters/TrendLimit"}
        ],
        "responses": {
          "200": {
            "description": "성과 근거와 데이터 한계를 포함한 영상 벤치마크 목록",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/VideoGrowthBenchmarkPage"}}}
          },
          "400": {"$ref": "#/components/responses/BadRequest"},
          "422": {"$ref": "#/components/responses/ValidationError"},
          "429": {"$ref": "#/components/responses/TooManyRequests"},
          "503": {"$ref": "#/components/responses/ServiceUnavailable"}
        }
      }
    },
    "/v1/products/search": {
      "get": {
        "tags": ["상품"],
        "summary": "상품·브랜드 검색",
        "description": "상품명 또는 브랜드 검색어와 기간 조건으로 콘텐츠 관심도 상품을 조회합니다.",
        "operationId": "searchProducts",
        "parameters": [
          {"$ref": "#/components/parameters/ProductQuery"},
          {"$ref": "#/components/parameters/ProductPeriodDays"},
          {"$ref": "#/components/parameters/TrendStart"},
          {"$ref": "#/components/parameters/TrendLimit"}
        ],
        "responses": {
          "200": {
            "description": "상품 관심도 검색 결과",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProductTrendPage"
                }
              }
            }
          },
          "400": {"$ref": "#/components/responses/BadRequest"},
          "422": {"$ref": "#/components/responses/ValidationError"},
          "429": {"$ref": "#/components/responses/TooManyRequests"},
          "503": {"$ref": "#/components/responses/ServiceUnavailable"}
        }
      }
    },
    "/v1/products/{productId}": {
      "get": {
        "tags": ["상품"],
        "summary": "상품 트렌드 상세 조회",
        "description": "상품의 콘텐츠 관심도, 추세와 관련 분석 정보를 조회합니다.",
        "operationId": "getProduct",
        "parameters": [
          {
            "in": "path",
            "name": "productId",
            "required": true,
            "description": "조회할 상품의 양의 정수 ID입니다.",
            "schema": {
              "type": "integer",
              "format": "int64",
              "minimum": 1
            }
          }
        ],
        "responses": {
          "200": {
            "description": "7일·30일 상품 트렌드",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProductTrendDetail"
                }
              }
            }
          },
          "404": {"$ref": "#/components/responses/NotFound"},
          "409": {"$ref": "#/components/responses/Conflict"},
          "422": {"$ref": "#/components/responses/ValidationError"},
          "429": {"$ref": "#/components/responses/TooManyRequests"},
          "503": {"$ref": "#/components/responses/ServiceUnavailable"}
        }
      }
    },
    "/v1/products/{productId}/creators": {
      "get": {
        "tags": ["상품"],
        "summary": "상품별 추천 크리에이터 조회",
        "description": "선택한 상품에 적합한 크리에이터와 적합 점수를 조회합니다.",
        "operationId": "listProductCreators",
        "parameters": [
          {
            "in": "path",
            "name": "productId",
            "required": true,
            "description": "추천 크리에이터를 조회할 상품의 양의 정수 ID입니다.",
            "schema": {
              "type": "integer",
              "format": "int64",
              "minimum": 1
            }
          },
          {"in": "query", "name": "sort", "required": false, "description": "상품 적합 크리에이터 정렬입니다.", "schema": {"type": "string", "enum": ["fit_score_desc", "related_views_desc", "engagement_desc", "video_count_desc"], "default": "fit_score_desc"}},
          {"$ref": "#/components/parameters/TrendStart"},
          {"$ref": "#/components/parameters/TrendLimit"}
        ],
        "responses": {
          "200": {
            "description": "적합 점수와 근거를 포함한 크리에이터 목록",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreatorProductFitPage"
                }
              }
            }
          },
          "400": {"$ref": "#/components/responses/BadRequest"},
          "404": {"$ref": "#/components/responses/NotFound"},
          "409": {"$ref": "#/components/responses/Conflict"},
          "422": {"$ref": "#/components/responses/ValidationError"},
          "429": {"$ref": "#/components/responses/TooManyRequests"},
          "503": {"$ref": "#/components/responses/ServiceUnavailable"}
        }
      }
    },
    "/v1/products/{productId}/promotion-patterns": {
      "get": {
        "tags": ["상품"],
        "summary": "상품별 홍보 패턴 조회",
        "description": "선택한 상품에 자주 사용되는 콘텐츠 형식, 메시지와 태그를 조회합니다.",
        "operationId": "listProductPromotionPatterns",
        "parameters": [
          {
            "in": "path",
            "name": "productId",
            "required": true,
            "description": "홍보 패턴을 조회할 상품의 양의 정수 ID입니다.",
            "schema": {
              "type": "integer",
              "format": "int64",
              "minimum": 1
            }
          },
          {
            "in": "query",
            "name": "pattern_type",
            "required": false,
            "description": "조회할 홍보 패턴 유형입니다. 생략하면 모든 유형을 반환합니다.",
            "schema": {
              "type": "string"
            }
          },
          {"in": "query", "name": "sort", "required": false, "description": "홍보 패턴 정렬입니다.", "schema": {"type": "string", "enum": ["pattern_rank", "video_count_desc", "creator_count_desc", "avg_views_desc", "engagement_desc"], "default": "pattern_rank"}}
        ],
        "responses": {
          "200": {
            "description": "최소 표본을 통과한 홍보 패턴",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PromotionPatternList"
                }
              }
            }
          },
          "404": {"$ref": "#/components/responses/NotFound"},
          "409": {"$ref": "#/components/responses/Conflict"},
          "422": {"$ref": "#/components/responses/ValidationError"},
          "429": {"$ref": "#/components/responses/TooManyRequests"},
          "503": {"$ref": "#/components/responses/ServiceUnavailable"}
        }
      }
    },
    "/v1/ingredients/trends": {
      "get": {
        "tags": ["트렌드"],
        "summary": "성분 트렌드 준비 상태 조회",
        "description": "구조화 성분 재분석 진행 상태와 현재 사용할 수 있는 성분 트렌드 데이터를 조회합니다.",
        "operationId": "listIngredientTrends",
        "responses": {
          "200": {
            "description": "재분석 전에는 unavailable 상태와 필요한 데이터를 반환",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/IngredientTrendResponse"
                }
              }
            }
          },
          "429": {"$ref": "#/components/responses/TooManyRequests"}
        }
      }
    },
    "/v1/insights/weekly-brief": {
      "get": {
        "tags": ["인사이트"],
        "summary": "주간 트렌드 브리프 조회",
        "description": "최신 주간 트렌드 변화와 실행 가능한 요약을 조회합니다.",
        "operationId": "getWeeklyTrendBrief",
        "responses": {
          "200": {
            "description": "상위 상품과 breakout 크리에이터",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WeeklyTrendBriefList"
                }
              }
            }
          },
          "429": {"$ref": "#/components/responses/TooManyRequests"},
          "503": {"$ref": "#/components/responses/ServiceUnavailable"}
        }
      }
    },
    "/v1/insights/data-status": {
      "get": {
        "tags": ["인사이트"],
        "summary": "데이터 가용 상태 조회",
        "description": "기능별 데이터 커버리지, 최신성, 가용 상태와 제한사항을 조회합니다.",
        "operationId": "getDataStatus",
        "responses": {
          "200": {
            "description": "available·limited·unavailable·stale 상태",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DataStatusList"
                }
              }
            }
          },
          "429": {"$ref": "#/components/responses/TooManyRequests"},
          "503": {"$ref": "#/components/responses/ServiceUnavailable"}
        }
      }
    },
    "/v1/trends/radar": {
      "get": {
        "tags": ["트렌드"],
        "summary": "뷰티 트렌드 레이더 조회",
        "description": "콘텐츠 관심도 신호를 기준으로 뷰티 항목의 단계와 상승 추세를 조회합니다.",
        "operationId": "listBeautyTrends",
        "parameters": [
          {"$ref": "#/components/parameters/TrendStart"},
          {"$ref": "#/components/parameters/TrendLimit"},
          {"$ref": "#/components/parameters/PrimaryCategory"},
          {"$ref": "#/components/parameters/SubCategory"},
          {"in": "query", "name": "sort", "required": false, "description": "트렌드 항목 정렬입니다.", "schema": {"type": "string", "enum": ["trend_score_desc", "mention_growth_desc", "view_velocity_desc", "creator_growth_desc", "engagement_desc"], "default": "trend_score_desc"}},
          {
            "in": "query",
            "name": "period_days",
            "required": false,
            "description": "트렌드 점수를 집계할 기간입니다. 기본값은 최근 7일입니다.",
            "schema": {"type": "integer", "enum": [7, 30, 60, 90], "default": 7}
          },
          {
            "in": "query",
            "name": "facet_type",
            "required": false,
            "description": "skin_concern, ingredient 등 조회할 뷰티 항목 유형입니다.",
            "schema": {"type": "string"}
          },
          {
            "in": "query",
            "name": "beauty_category",
            "required": false,
            "description": "sub_category의 한시적 호환 alias입니다.",
            "schema": {"type": "string"}
          },
          {
            "in": "query",
            "name": "trend_phase",
            "required": false,
            "description": "트렌드의 현재 성장 단계입니다. 생략하면 모든 단계를 조회합니다.",
            "schema": {
              "type": "string",
              "enum": ["emerging", "accelerating", "sustained", "cooling"]
            }
          },
          {
            "in": "query",
            "name": "query",
            "required": false,
            "description": "뷰티 항목 키 또는 표시 이름 검색어입니다.",
            "schema": {"type": "string"}
          }
        ],
        "responses": {
          "200": {
            "description": "콘텐츠 관심도 신호를 기반으로 한 뷰티 항목 트렌드입니다.",
            "content": {
              "application/json": {
                "schema": {"$ref": "#/components/schemas/BeautyTrendRadarPage"}
              }
            }
          },
          "400": {"$ref": "#/components/responses/BadRequest"},
          "422": {"$ref": "#/components/responses/ValidationError"},
          "429": {"$ref": "#/components/responses/TooManyRequests"},
          "503": {"$ref": "#/components/responses/ServiceUnavailable"}
        }
      }
    },
    "/v1/trends/catalog": {
      "get": {
        "tags": ["트렌드"],
        "summary": "트렌드 필터 카탈로그 조회",
        "description": "현재 트렌드 데이터에서 선택할 수 있는 분석 차원과 필터값을 조회합니다.",
        "operationId": "getTrendFilterCatalog",
        "parameters": [
          {"in": "query", "name": "dimension_group", "required": false, "description": "필터 차원의 상위 그룹입니다. 생략하면 모든 그룹을 조회합니다.", "schema": {"type": "string"}},
          {"in": "query", "name": "dimension_type", "required": false, "description": "필터 차원의 세부 유형입니다. 생략하면 모든 유형을 조회합니다.", "schema": {"type": "string"}}
        ],
        "responses": {
          "200": {
            "description": "활성 analysis_field_catalog 값과 정의된 크리에이터 티어",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/TrendFilterCatalogPage"}}}
          },
          "429": {"$ref": "#/components/responses/TooManyRequests"},
          "503": {"$ref": "#/components/responses/ServiceUnavailable"}
        }
      }
    },
    "/v1/trends/creators": {
      "get": {
        "tags": ["트렌드"],
        "summary": "크리에이터 트렌드 레이더 조회",
        "description": "기간, 규모와 분석 조건별로 성장 중인 크리에이터를 조회합니다.",
        "operationId": "listCreatorTrends",
        "parameters": [
          {"$ref": "#/components/parameters/PrimaryCategory"},
          {"$ref": "#/components/parameters/SubCategory"},
          {"in": "query", "name": "sort", "required": false, "description": "크리에이터 트렌드 정렬입니다.", "schema": {"type": "string", "enum": ["trend_score_desc", "followers_desc", "avg_views_desc", "follower_growth_desc", "engagement_desc", "quality_desc"], "default": "trend_score_desc"}},
          {"$ref": "#/components/parameters/TrendStart"},
          {"$ref": "#/components/parameters/TrendLimit"},
          {"in": "query", "name": "period_days", "required": false, "description": "크리에이터 트렌드를 집계할 기간입니다. 기본값은 최근 7일입니다.", "schema": {"type": "integer", "enum": [7, 30, 60, 90], "default": 7}},
          {"in": "query", "name": "query", "required": false, "description": "creator ID, 핸들 또는 표시 이름 검색어입니다.", "schema": {"type": "string"}},
          {"in": "query", "name": "category", "required": false, "description": "sub_category의 한시적 호환 alias입니다.", "schema": {"type": "string"}},
          {"in": "query", "name": "follower_tier", "required": false, "description": "팔로워 규모 구간 필터입니다.", "schema": {"type": "string"}},
          {"in": "query", "name": "avg_view_tier", "required": false, "description": "평균 조회수 규모 구간 필터입니다.", "schema": {"type": "string"}},
          {"in": "query", "name": "gender", "required": false, "description": "분석된 크리에이터 성별 필터입니다.", "schema": {"type": "string"}},
          {"in": "query", "name": "age_band", "required": false, "description": "분석된 크리에이터 연령대의 시작 나이입니다. 기본값 0은 연령 제한 없음을 뜻합니다.", "schema": {"type": "integer", "minimum": 0, "default": 0}},
          {"in": "query", "name": "country", "required": false, "description": "분석된 크리에이터 국가 필터입니다.", "schema": {"type": "string"}}
        ],
        "responses": {
          "200": {
            "description": "기간·티어·인구통계·분석 관점별 크리에이터 트렌드",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/CreatorTrendRadarPage"}}}
          },
          "400": {"$ref": "#/components/responses/BadRequest"},
          "422": {"$ref": "#/components/responses/ValidationError"},
          "429": {"$ref": "#/components/responses/TooManyRequests"},
          "503": {"$ref": "#/components/responses/ServiceUnavailable"}
        }
      }
    },
    "/v1/trends/creator-segments": {
      "get": {
        "tags": ["트렌드"],
        "summary": "카테고리별 크리에이터 세그먼트 조회",
        "description": "analysis_field_catalog 기반 뷰티 카테고리에서 팔로워·조회 티어와 성별·연령·국가 분포를 비교합니다.",
        "operationId": "listCreatorSegmentTrends",
        "parameters": [
          {"$ref": "#/components/parameters/TrendStart"},
          {"$ref": "#/components/parameters/TrendLimit"},
          {"$ref": "#/components/parameters/PrimaryCategory"},
          {"$ref": "#/components/parameters/SubCategory"},
          {"in": "query", "name": "sort", "required": false, "description": "크리에이터 세그먼트 정렬입니다.", "schema": {"type": "string", "enum": ["weighted_trend_desc", "creator_share_desc", "avg_views_desc", "engagement_desc", "breakout_share_desc"], "default": "weighted_trend_desc"}},
          {"in": "query", "name": "period_days", "required": false, "description": "세그먼트를 집계할 기간입니다. 기본값은 최근 30일입니다.", "schema": {"type": "integer", "enum": [7, 30, 60, 90], "default": 30}},
          {"in": "query", "name": "category", "required": false, "description": "sub_category의 한시적 호환 alias입니다.", "schema": {"type": "string"}},
          {"in": "query", "name": "dimension", "required": false, "description": "비교할 크리에이터 세그먼트 차원입니다.", "schema": {"type": "string", "enum": ["follower_tier", "avg_view_tier", "creator_gender", "creator_age", "audience_country"], "default": "follower_tier"}}
        ],
        "responses": {
          "200": {
            "description": "카테고리·기간·차원별 가중 크리에이터 세그먼트",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/CreatorSegmentTrendPage"}}}
          },
          "400": {"$ref": "#/components/responses/BadRequest"},
          "422": {"$ref": "#/components/responses/ValidationError"},
          "429": {"$ref": "#/components/responses/TooManyRequests"},
          "503": {"$ref": "#/components/responses/ServiceUnavailable"}
        }
      }
    },
    "/v1/trends/products": {
      "get": {
        "tags": ["트렌드"],
        "summary": "상품 트렌드 레이더 조회",
        "description": "기간과 카테고리 조건별로 관심도가 상승하는 상품을 조회합니다.",
        "operationId": "listProductTrends",
        "parameters": [
          {"$ref": "#/components/parameters/TrendStart"},
          {"$ref": "#/components/parameters/TrendLimit"},
          {"$ref": "#/components/parameters/PrimaryCategory"},
          {"$ref": "#/components/parameters/SubCategory"},
          {"in": "query", "name": "sort", "required": false, "description": "상품 트렌드 정렬입니다. observed_gmv_desc는 관측 표본만 사용합니다.", "schema": {"type": "string", "enum": ["trend_score_desc", "mention_growth_desc", "creator_growth_desc", "view_velocity_desc", "engagement_desc", "organic_strength_desc", "ad_saturation_asc", "observed_gmv_desc"], "default": "trend_score_desc"}},
          {"in": "query", "name": "period_days", "required": false, "description": "상품 트렌드를 집계할 기간입니다. 기본값은 최근 7일입니다.", "schema": {"type": "integer", "enum": [7, 30, 60, 90], "default": 7}},
          {"in": "query", "name": "query", "required": false, "description": "상품명, 상품 키 또는 브랜드명 검색어입니다.", "schema": {"type": "string"}},
          {"in": "query", "name": "category", "required": false, "description": "sub_category의 한시적 호환 alias입니다.", "schema": {"type": "string"}}
        ],
        "responses": {
          "200": {
            "description": "성과·홍보·구성 관점의 상품 트렌드",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ProductTrendRadarPage"}}}
          },
          "400": {"$ref": "#/components/responses/BadRequest"},
          "422": {"$ref": "#/components/responses/ValidationError"},
          "429": {"$ref": "#/components/responses/TooManyRequests"},
          "503": {"$ref": "#/components/responses/ServiceUnavailable"}
        }
      }
    },
    "/v1/trends/history": {
      "get": {
        "tags": ["트렌드"],
        "summary": "뷰티 트렌드 이력 조회",
        "description": "최근 120일은 일별, 이전 구간은 월별 뷰티 항목 트렌드 이력을 조회합니다.",
        "operationId": "getTrendHistory",
        "parameters": [
          {
            "in": "query",
            "name": "facet_type",
            "required": true,
            "description": "이력을 조회할 뷰티 항목 유형입니다.",
            "schema": {"type": "string"}
          },
          {
            "in": "query",
            "name": "facet_key",
            "required": true,
            "description": "이력을 조회할 뷰티 항목 키입니다.",
            "schema": {"type": "string"}
          },
          {
            "in": "query",
            "name": "from",
            "required": false,
            "description": "조회 시작일입니다. YYYY-MM-DD 형식이며 생략하면 시작일을 제한하지 않습니다.",
            "schema": {"type": "string", "format": "date"}
          },
          {
            "in": "query",
            "name": "to",
            "required": false,
            "description": "조회 종료일입니다. YYYY-MM-DD 형식이며 생략하면 종료일을 제한하지 않습니다.",
            "schema": {"type": "string", "format": "date"}
          }
        ],
        "responses": {
          "200": {
            "description": "일별·월별 facet 트렌드 이력",
            "content": {
              "application/json": {
                "schema": {"$ref": "#/components/schemas/TrendHistoryPage"}
              }
            }
          },
          "404": {"$ref": "#/components/responses/NotFound"},
          "409": {"$ref": "#/components/responses/Conflict"},
          "422": {"$ref": "#/components/responses/ValidationError"},
          "429": {"$ref": "#/components/responses/TooManyRequests"},
          "503": {"$ref": "#/components/responses/ServiceUnavailable"}
        }
      }
    },
    "/v1/trends/relations": {
      "get": {
        "tags": ["트렌드"],
        "summary": "뷰티 트렌드 연관 관계 조회",
        "description": "콘텐츠에서 함께 관찰되는 뷰티 항목과 연관 강도를 조회합니다.",
        "operationId": "listTrendRelations",
        "parameters": [
          {"$ref": "#/components/parameters/TrendStart"},
          {"$ref": "#/components/parameters/TrendLimit"},
          {
            "in": "query",
            "name": "facet_type",
            "required": false,
            "description": "기준으로 삼을 뷰티 항목 유형입니다. facet_key와 함께 입력해야 합니다.",
            "schema": {"type": "string"}
          },
          {
            "in": "query",
            "name": "facet_key",
            "required": false,
            "description": "기준으로 삼을 뷰티 항목 키입니다. facet_type과 함께 입력해야 합니다.",
            "schema": {"type": "string"}
          }
        ],
        "responses": {
          "200": {
            "description": "콘텐츠에서 자주 함께 관찰되는 뷰티 항목입니다.",
            "content": {
              "application/json": {
                "schema": {"$ref": "#/components/schemas/BeautyTrendRelationPage"}
              }
            }
          },
          "400": {"$ref": "#/components/responses/BadRequest"},
          "422": {"$ref": "#/components/responses/ValidationError"},
          "429": {"$ref": "#/components/responses/TooManyRequests"},
          "503": {"$ref": "#/components/responses/ServiceUnavailable"}
        }
      }
    },
    "/v1/analysis-fields": {
      "get": {
        "tags": ["카탈로그"],
        "summary": "분석 필드 조회",
        "description": "자연어 해석과 검색에 사용할 수 있는 분석 필드와 선택값을 조회합니다.",
        "operationId": "listAnalysisFields",
        "parameters": [
          {
            "in": "query",
            "name": "field_key",
            "required": false,
            "description": "조회할 분석 필드 키입니다. 생략하면 모든 필드를 조회합니다.",
            "schema": {
              "anyOf": [
                {
                  "minLength": 1,
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "Field Key"
            }
          },
          {
            "in": "query",
            "name": "item_type",
            "required": false,
            "description": "field는 필드 정의, value는 선택 가능한 값만 조회합니다. 생략하면 모두 반환합니다.",
            "schema": {
              "anyOf": [
                {
                  "pattern": "^(field|value)$",
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "Item Type"
            }
          },
          {
            "in": "query",
            "name": "active_only",
            "required": false,
            "description": "활성 항목만 반환할지 여부입니다. 기본값은 true입니다.",
            "schema": {
              "default": true,
              "title": "Active Only",
              "type": "boolean"
            }
          },
          {
            "in": "query",
            "name": "searchable_only",
            "required": false,
            "description": "자연어 검색에 사용할 수 있는 항목만 반환할지 여부입니다. 기본값은 false입니다.",
            "schema": {
              "default": false,
              "title": "Searchable Only",
              "type": "boolean"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "items": {
                    "$ref": "#/components/schemas/AnalysisFieldCatalogItem"
                  },
                  "title": "Response List Analysis Fields V1 Analysis Fields Get",
                  "type": "array"
                }
              }
            },
            "description": "조건에 맞는 분석 필드 정의와 선택 가능한 값을 반환합니다."
          },
          "422": {"$ref": "#/components/responses/ValidationError"},
          "503": {"$ref": "#/components/responses/ServiceUnavailable"}
        }
      }
    },
    "/v1/recommendations/creators/ad-fit-presets": {
      "get": {
        "tags": ["크리에이터 추천"],
        "summary": "광고 적합도 프리셋 조회",
        "description": "외부 서비스가 선택할 수 있는 크리에이터 광고 적합도 프리셋을 조회합니다.",
        "operationId": "listCreatorAdFitPresets",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "items": {
                    "$ref": "#/components/schemas/CreatorAdFitPresetItem"
                  },
                  "title": "Response List Creator Ad Fit Presets V1 Recommendations Creators Ad Fit Presets Get",
                  "type": "array"
                }
              }
            },
            "description": "이름, 기본 여부와 전체 광고 적합도 조건을 포함한 프리셋 목록을 반환합니다."
          },
          "429": {"$ref": "#/components/responses/TooManyRequests"},
          "503": {"$ref": "#/components/responses/ServiceUnavailable"}
        }
      }
    },
    "/v1/recommendations/creators/by-ad-fit-criteria": {
      "get": {
        "tags": ["크리에이터 추천"],
        "summary": "조건 기반 크리에이터 추천",
        "description": "요청한 광고 적합도 조건으로 크리에이터를 검색하고 점수순으로 반환합니다.",
        "operationId": "recommendCreatorsByAdFitCriteria",
        "parameters": [
          {
            "in": "query",
            "name": "platform",
            "required": false,
            "description": "추천 대상 플랫폼입니다. 기본값은 tiktok입니다.",
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "default": "tiktok",
              "title": "Platform"
            }
          },
          {
            "in": "query",
            "name": "start",
            "required": false,
            "description": "0부터 시작하는 결과 위치입니다. 기본값은 0입니다.",
            "schema": {
              "default": 0,
              "maximum": 100000,
              "minimum": 0,
              "title": "Start",
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "limit",
            "required": false,
            "description": "한 번에 반환할 추천 크리에이터 수입니다. 기본값은 20이며 최대 200명입니다.",
            "schema": {
              "anyOf": [
                {
                  "maximum": 200,
                  "minimum": 1,
                  "type": "integer"
                },
                {
                  "type": "null"
                }
              ],
              "default": 20,
              "title": "Limit"
            }
          },
          {
            "in": "query",
            "name": "min_organic_look_score",
            "required": false,
            "description": "자연스러운 비광고형 표현 점수의 최솟값입니다. 기본값은 0.60입니다.",
            "schema": {
              "anyOf": [
                {
                  "type": "number"
                },
                {
                  "type": "null"
                }
              ],
              "default": 0.6,
              "title": "Min Organic Look Score"
            }
          },
          {
            "in": "query",
            "name": "min_visual_quality_score",
            "required": false,
            "description": "영상 시각 품질 점수의 최솟값입니다. 기본값은 0.60입니다.",
            "schema": {
              "anyOf": [
                {
                  "type": "number"
                },
                {
                  "type": "null"
                }
              ],
              "default": 0.6,
              "title": "Min Visual Quality Score"
            }
          },
          {
            "in": "query",
            "name": "min_on_camera_presence_score",
            "required": false,
            "description": "크리에이터의 화면 등장 점수 최솟값입니다. 기본값은 0.50입니다.",
            "schema": {
              "anyOf": [
                {
                  "type": "number"
                },
                {
                  "type": "null"
                }
              ],
              "default": 0.5,
              "title": "Min On Camera Presence Score"
            }
          },
          {
            "in": "query",
            "name": "min_visual_hook_strength",
            "required": false,
            "description": "초반 시각적 주목도 점수의 최솟값입니다. 기본값은 0.50입니다.",
            "schema": {
              "anyOf": [
                {
                  "type": "number"
                },
                {
                  "type": "null"
                }
              ],
              "default": 0.5,
              "title": "Min Visual Hook Strength"
            }
          },
          {
            "in": "query",
            "name": "min_ad_density_score",
            "required": false,
            "description": "최근 콘텐츠 광고 밀도 점수의 최솟값입니다. 기본값은 0.10입니다.",
            "schema": {
              "anyOf": [
                {
                  "type": "number"
                },
                {
                  "type": "null"
                }
              ],
              "default": 0.1,
              "title": "Min Ad Density Score"
            }
          },
          {
            "in": "query",
            "name": "max_ad_density_score",
            "required": false,
            "description": "최근 콘텐츠 광고 밀도 점수의 최댓값입니다. 기본값은 0.50입니다.",
            "schema": {
              "anyOf": [
                {
                  "type": "number"
                },
                {
                  "type": "null"
                }
              ],
              "default": 0.5,
              "title": "Max Ad Density Score"
            }
          },
          {
            "in": "query",
            "name": "min_avg_video_plays",
            "required": false,
            "description": "최근 분석 영상의 최소 평균 조회수입니다. 기본값은 10,000회입니다.",
            "schema": {
              "anyOf": [
                {
                  "type": "number"
                },
                {
                  "type": "null"
                }
              ],
              "default": 10000,
              "title": "Min Avg Video Plays"
            }
          },
          {
            "in": "query",
            "name": "min_avg_video_diggs",
            "required": false,
            "description": "최근 분석 영상의 최소 평균 좋아요 수입니다. 기본값은 0개입니다.",
            "schema": {
              "anyOf": [
                {
                  "type": "number"
                },
                {
                  "type": "null"
                }
              ],
              "default": 0,
              "title": "Min Avg Video Diggs"
            }
          },
          {
            "in": "query",
            "name": "min_same_category_video_count",
            "required": false,
            "description": "목표 크리에이터 카테고리와 일치해야 하는 최소 영상 수입니다. 기본값은 2개입니다.",
            "schema": {
              "anyOf": [
                {
                  "type": "integer"
                },
                {
                  "type": "null"
                }
              ],
              "default": 2,
              "title": "Min Same Category Video Count"
            }
          },
          {
            "in": "query",
            "name": "max_casual_interest_video_count",
            "required": false,
            "description": "일시적 관심으로 분류된 영상의 허용 최댓값입니다. 기본값은 5개입니다.",
            "schema": {
              "anyOf": [
                {
                  "type": "integer"
                },
                {
                  "type": "null"
                }
              ],
              "default": 5,
              "title": "Max Casual Interest Video Count"
            }
          },
          {
            "in": "query",
            "name": "max_brand_video_count",
            "required": false,
            "description": "브랜드 콘텐츠로 분류된 영상의 허용 최댓값입니다. 기본값은 5개입니다.",
            "schema": {
              "anyOf": [
                {
                  "type": "integer"
                },
                {
                  "type": "null"
                }
              ],
              "default": 5,
              "title": "Max Brand Video Count"
            }
          },
          {
            "in": "query",
            "name": "min_recent_video_count",
            "required": false,
            "description": "최근 기간에 필요한 최소 분석 영상 수입니다. 기본값은 5개입니다.",
            "schema": {
              "anyOf": [
                {
                  "type": "integer"
                },
                {
                  "type": "null"
                }
              ],
              "default": 5,
              "title": "Min Recent Video Count"
            }
          },
          {
            "in": "query",
            "name": "min_same_product_category_video_count",
            "required": false,
            "description": "목표 상품 카테고리와 일치해야 하는 최소 영상 수입니다. 기본값은 0개입니다.",
            "schema": {
              "anyOf": [
                {
                  "type": "integer"
                },
                {
                  "type": "null"
                }
              ],
              "default": 0,
              "title": "Min Same Product Category Video Count"
            }
          },
          {
            "in": "query",
            "name": "recent_days",
            "required": false,
            "description": "최근 영상으로 인정할 기간입니다. 기본값은 90일입니다.",
            "schema": {
              "anyOf": [
                {
                  "type": "integer"
                },
                {
                  "type": "null"
                }
              ],
              "default": 90,
              "title": "Recent Days"
            }
          },
          {
            "in": "query",
            "name": "video_limit",
            "required": false,
            "description": "조건 평가에 사용할 영상 수의 상한입니다. 기본값은 20개입니다.",
            "schema": {
              "anyOf": [
                {
                  "type": "integer"
                },
                {
                  "type": "null"
                }
              ],
              "default": 20,
              "title": "Video Limit"
            }
          },
          {
            "in": "query",
            "name": "recent_video_count",
            "required": false,
            "description": "최근 영상 통계를 계산할 영상 수입니다. 기본값은 20개입니다.",
            "schema": {
              "anyOf": [
                {
                  "type": "integer"
                },
                {
                  "type": "null"
                }
              ],
              "default": 20,
              "title": "Recent Video Count"
            }
          },
          {
            "in": "query",
            "name": "allowed_languages",
            "required": false,
            "description": "허용할 콘텐츠 언어 목록입니다. 반복 파라미터 또는 쉼표 구분 값을 지원하며 기본값은 제한 없음입니다.",
            "schema": {
              "anyOf": [
                {
                  "items": {
                    "type": "string"
                  },
                  "type": "array"
                },
                {
                  "type": "null"
                }
              ],
              "default": [],
              "title": "Allowed Languages"
            }
          },
          {
            "in": "query",
            "name": "allowed_countries",
            "required": false,
            "description": "허용할 크리에이터 국가 목록입니다. 반복 파라미터 또는 쉼표 구분 값을 지원하며 기본값은 제한 없음입니다.",
            "schema": {
              "anyOf": [
                {
                  "items": {
                    "type": "string"
                  },
                  "type": "array"
                },
                {
                  "type": "null"
                }
              ],
              "default": [],
              "title": "Allowed Countries"
            }
          },
          {
            "in": "query",
            "name": "model_versions",
            "required": false,
            "description": "허용할 분석 모델 버전 목록입니다. 기본값은 gemini:gemini-3.1-flash-lite입니다.",
            "schema": {
              "anyOf": [
                {
                  "items": {
                    "type": "string"
                  },
                  "type": "array"
                },
                {
                  "type": "null"
                }
              ],
              "default": ["gemini:gemini-3.1-flash-lite"],
              "title": "Model Versions"
            }
          },
          {
            "in": "query",
            "name": "target_categories",
            "required": false,
            "description": "목표 크리에이터 카테고리 목록입니다. 기본값은 beauty입니다.",
            "schema": {
              "anyOf": [
                {
                  "items": {
                    "type": "string"
                  },
                  "type": "array"
                },
                {
                  "type": "null"
                }
              ],
              "default": ["beauty"],
              "title": "Target Categories"
            }
          },
          {
            "in": "query",
            "name": "target_product_categories",
            "required": false,
            "description": "목표 상품 카테고리 목록입니다. 기본값은 제한 없음입니다.",
            "schema": {
              "anyOf": [
                {
                  "items": {
                    "type": "string"
                  },
                  "type": "array"
                },
                {
                  "type": "null"
                }
              ],
              "default": [],
              "title": "Target Product Categories"
            }
          },
          {
            "in": "query",
            "name": "target_creator_genders",
            "required": false,
            "description": "목표 크리에이터 성별 목록입니다. 기본값은 female입니다.",
            "schema": {
              "anyOf": [
                {
                  "items": {
                    "type": "string"
                  },
                  "type": "array"
                },
                {
                  "type": "null"
                }
              ],
              "default": ["female"],
              "title": "Target Creator Genders"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreatorRecommendationPage"
                }
              }
            },
            "description": "적용한 조건, 전체 일치 수와 페이지 단위 추천 크리에이터를 반환합니다."
          },
          "400": {"$ref": "#/components/responses/BadRequest"},
          "422": {"$ref": "#/components/responses/ValidationError"},
          "429": {"$ref": "#/components/responses/TooManyRequests"},
          "503": {"$ref": "#/components/responses/ServiceUnavailable"}
        }
      }
    },
    "/v1/recommendations/creators/by-ad-fit-preset": {
      "get": {
        "tags": ["크리에이터 추천"],
        "summary": "프리셋 기반 크리에이터 추천",
        "description": "선택한 광고 적합도 프리셋으로 크리에이터를 검색하고 점수순으로 반환합니다.",
        "operationId": "recommendCreatorsByAdFitPreset",
        "parameters": [
          {
            "in": "query",
            "name": "preset_name",
            "required": false,
            "description": "적용할 광고 적합도 프리셋 이름입니다. 기본값은 default입니다.",
            "schema": {
              "default": "default",
              "minLength": 1,
              "title": "Preset Name",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "platform",
            "required": false,
            "description": "추천 대상 플랫폼입니다. 기본값은 tiktok입니다.",
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "default": "tiktok",
              "title": "Platform"
            }
          },
          {
            "in": "query",
            "name": "start",
            "required": false,
            "description": "0부터 시작하는 결과 위치입니다. 기본값은 0입니다.",
            "schema": {
              "default": 0,
              "maximum": 100000,
              "minimum": 0,
              "title": "Start",
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "limit",
            "required": false,
            "description": "한 번에 반환할 추천 크리에이터 수입니다. 기본값은 20이며 최대 200명입니다.",
            "schema": {
              "anyOf": [
                {
                  "maximum": 200,
                  "minimum": 1,
                  "type": "integer"
                },
                {
                  "type": "null"
                }
              ],
              "default": 20,
              "title": "Limit"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreatorRecommendationPage"
                }
              }
            },
            "description": "프리셋 조건, 전체 일치 수와 페이지 단위 추천 크리에이터를 반환합니다."
          },
          "400": {"$ref": "#/components/responses/BadRequest"},
          "422": {"$ref": "#/components/responses/ValidationError"},
          "429": {"$ref": "#/components/responses/TooManyRequests"},
          "503": {"$ref": "#/components/responses/ServiceUnavailable"}
        }
      }
    },
    "/v1/recommendations/creators/by-natural-language": {
      "get": {
        "tags": ["크리에이터 추천"],
        "summary": "자연어 기반 크리에이터 추천",
        "description": "한국어 또는 영어 요청을 검색 조건으로 해석해 적합한 크리에이터를 반환합니다.",
        "operationId": "recommendCreatorsByNaturalLanguage",
        "parameters": [
          {
            "in": "query",
            "name": "query_text",
            "required": true,
            "description": "원하는 크리에이터 조건을 한국어 또는 영어로 작성합니다. 1자 이상 500자 이하입니다.",
            "schema": {
              "maxLength": 500,
              "minLength": 1,
              "title": "Query Text",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "platform",
            "required": false,
            "description": "추천 대상 플랫폼입니다. 기본값은 tiktok입니다.",
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "default": "tiktok",
              "title": "Platform"
            }
          },
          {
            "in": "query",
            "name": "recent_days",
            "required": false,
            "description": "자연어 조건에서 별도 기간을 지정하지 않았을 때 사용할 최근 기간입니다. 기본값은 90일입니다.",
            "schema": {
              "default": 90,
              "maximum": 365,
              "minimum": 1,
              "title": "Recent Days",
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "start",
            "required": false,
            "description": "0부터 시작하는 결과 위치입니다. 기본값은 0입니다.",
            "schema": {
              "default": 0,
              "maximum": 100000,
              "minimum": 0,
              "title": "Start",
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "limit",
            "required": false,
            "description": "한 번에 반환할 추천 크리에이터 수입니다. 기본값은 20이며 최대 200명입니다.",
            "schema": {
              "anyOf": [
                {
                  "maximum": 200,
                  "minimum": 1,
                  "type": "integer"
                },
                {
                  "type": "null"
                }
              ],
              "default": 20,
              "title": "Limit"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreatorRecommendationPage"
                }
              }
            },
            "description": "해석된 검색 조건, 전체 일치 수와 점수순 추천 크리에이터를 반환합니다."
          },
          "400": {"$ref": "#/components/responses/BadRequest"},
          "422": {"$ref": "#/components/responses/ValidationError"},
          "429": {"$ref": "#/components/responses/TooManyRequests"},
          "503": {"$ref": "#/components/responses/ServiceUnavailable"}
        }
      }
    },
    "/v1/creators/{creatorId}/pricing": {
      "get": {
        "tags": ["크리에이터"],
        "summary": "크리에이터 예상 가격 조회",
        "description": "최근 분석 데이터를 기준으로 계산해 둔 기본 TikTok 영상 1건의 예상 가격을 조회합니다.",
        "operationId": "getCreatorPricing",
        "parameters": [
          {
            "description": "실제 creator ID, TikTok unique ID, 또는 @handle입니다.",
            "in": "path",
            "name": "creatorId",
            "required": true,
            "schema": {
              "description": "실제 creator ID, TikTok unique ID, 또는 @handle입니다.",
              "examples": [
                "abigailcanfieldd"
              ],
              "maxLength": 255,
              "minLength": 1,
              "title": "Creatorid",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "adjustments": [
                    {
                      "code": "engagement_high",
                      "fee_delta_usd": {
                        "max_usd": "540.00",
                        "min_usd": "90.00"
                      },
                      "max_rate": "0.30",
                      "min_rate": "0.10",
                      "reason": "Engagement rate가 8%를 초과해 프리미엄을 적용했습니다."
                    },
                    {
                      "code": "us_audience_60_plus",
                      "fee_delta_usd": {
                        "max_usd": "720.00",
                        "min_usd": "180.00"
                      },
                      "max_rate": "0.40",
                      "min_rate": "0.20",
                      "reason": "US audience 비중이 60% 이상이라 프리미엄을 적용했습니다."
                    }
                  ],
                  "base_fee_usd": {
                    "max_usd": "1800.00",
                    "min_usd": "900.00"
                  },
                  "beauty_content_ratio": "0.82",
                  "benchmark": {
                    "category": "beauty",
                    "currency": "USD",
                    "source_reviewed_at": "2026-07-21",
                    "source_url": "https://influencerfee.com/blog/tiktok-pricing-guide-2025/",
                    "version": "influencerfee-tiktok-2026-07-21"
                  },
                  "benchmark_notes": [
                    "조회수 기반 CPV base fee가 follower tier 참고 범위와 일부 겹칩니다."
                  ],
                  "calculated_at": "2026-07-22T00:00:00Z",
                  "calculation_basis": [
                    "최근 90일 영상 20개 중 viral outlier 2개를 제외한 18개 median 조회수 60,000회를 적용했습니다."
                  ],
                  "confidence": "high",
                  "content_complexity": "standard",
                  "creator_handle": "@abigailcanfieldd",
                  "creator_id": "7420747151917691909",
                  "creator_unique_id": "abigailcanfieldd",
                  "deliverable_type": "standard_video",
                  "disclaimer": "This creator fee prediction is a non-binding estimate based on an external USD benchmark and currently collected creator metrics. Actual fees vary by campaign scope and negotiation.",
                  "engagement_rate": "8.70",
                  "exclusivity_days": 0,
                  "expected_views_method": "median_90d",
                  "fee_metric_video_count": 18,
                  "metrics": {
                    "creator_followers": 98000,
                    "expected_views": "60000.00",
                    "metric_source": "recommendation_source_snapshot",
                    "quality_signals": {
                      "avg_ad_density_score": 0.18,
                      "avg_organic_look_score": 0.79,
                      "avg_visual_quality_score": 0.84
                    },
                    "recent_video_count": 50,
                    "snapshot_generation": 12,
                    "snapshot_status": "hit"
                  },
                  "missing_metrics": [],
                  "negotiation_ceiling_usd": "3060.00",
                  "outlier_count": 2,
                  "platform": "TIKTOK",
                  "posting_count": 1,
                  "predicted_fee_usd": {
                    "max_usd": "3060.00",
                    "min_usd": "1170.00"
                  },
                  "reasons": [
                    "최근 90일 영상 20개 중 viral outlier 2개를 제외한 18개 median 조회수 60,000회를 적용했습니다.",
                    "2개 modifier를 적용했습니다: engagement_high, us_audience_60_plus.",
                    "조회수 기반 CPV base fee가 follower tier 참고 범위와 일부 겹칩니다."
                  ],
                  "skipped_adjustments": [],
                  "spark_ads_usage_days": 0,
                  "suggested_offer_usd": {
                    "max_usd": "2115.00",
                    "min_usd": "1170.00"
                  },
                  "tier_benchmark_position": "overlaps",
                  "tier_reference_usd": {
                    "max_usd": "125000.00",
                    "min_usd": "15000.00"
                  },
                  "us_audience_share": "0.62"
                },
                "schema": {
                  "$ref": "#/components/schemas/CreatorFeePredictionResponse"
                }
              }
            },
            "description": "뷰티 creator fee 예측 성공"
          },
          "404": {"$ref": "#/components/responses/NotFound"},
          "409": {"$ref": "#/components/responses/Conflict"},
          "422": {"$ref": "#/components/responses/ValidationError"},
          "429": {"$ref": "#/components/responses/TooManyRequests"},
          "503": {"$ref": "#/components/responses/ServiceUnavailable"}
        }
      }
    },
    "/v1/taxonomy/categories": {
      "get": {
        "tags": ["카탈로그"],
        "summary": "카테고리 분류 조회",
        "description": "추천과 검색에서 사용하는 대표·세부 카테고리 분류를 조회합니다.",
        "operationId": "listTaxonomyCategories",
        "parameters": [
          {
            "in": "query",
            "name": "category_type",
            "required": false,
            "description": "primary는 대표 카테고리, sub_category는 세부 카테고리만 조회합니다. 생략하면 모두 반환합니다.",
            "schema": {
              "anyOf": [
                {
                  "pattern": "^(primary|sub_category)$",
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "Category Type"
            }
          },
          {
            "in": "query",
            "name": "parent_key",
            "required": false,
            "description": "지정한 대표 카테고리에 속한 세부 카테고리만 조회합니다.",
            "schema": {
              "anyOf": [
                {
                  "minLength": 1,
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "Parent Key"
            }
          },
          {
            "in": "query",
            "name": "active_only",
            "required": false,
            "description": "활성 카테고리만 반환할지 여부입니다. 기본값은 true입니다.",
            "schema": {
              "default": true,
              "title": "Active Only",
              "type": "boolean"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "items": {
                    "$ref": "#/components/schemas/TaxonomyCategoryItem"
                  },
                  "title": "Response List Taxonomy Categories V1 Taxonomy Categories Get",
                  "type": "array"
                }
              }
            },
            "description": "카테고리 키, 표시 이름, 계층과 활성 상태를 포함한 분류 목록을 반환합니다."
          },
          "422": {"$ref": "#/components/responses/ValidationError"},
          "503": {"$ref": "#/components/responses/ServiceUnavailable"}
        }
      }
    }
  }
}