{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/upriver-ai/json-schema/upriver-ai-trend-detail-response-schema.json",
  "title": "TrendDetailResponse",
  "description": "Response for GET /trends/{id}. Only includes fields returned by the endpoint.",
  "x-generated": "2026-10-31",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/upriver-ai-openapi.json#/components/schemas/TrendDetailResponse",
  "properties": {
    "id": {
      "type": "string",
      "title": "Id",
      "description": "Stable trend identifier"
    },
    "title": {
      "type": "string",
      "title": "Title",
      "description": "Short name of the trend"
    },
    "summary": {
      "type": "string",
      "title": "Summary",
      "description": "1-3 sentences describing the trend"
    },
    "uses_specific_sound": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "title": "Uses Specific Sound",
      "description": "Whether the trend uses a specific recognizable sound, derived from dominant-sound evidence and signature-sound classification."
    },
    "instructions": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Instructions",
      "description": "Actionable guidance on how to participate in the trend"
    },
    "status": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Status",
      "description": "Trend status (e.g., active)"
    },
    "video_count": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "title": "Video Count",
      "description": "Number of video media items"
    },
    "audio_count": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "title": "Audio Count",
      "description": "Number of audio media items"
    },
    "variants_count": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "title": "Variants Count",
      "description": "Number of known variant strings"
    },
    "video_samples": {
      "anyOf": [
        {
          "items": {},
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "title": "Video Samples",
      "description": "Representative video samples (shape varies by metadata_mode)"
    },
    "audio_samples": {
      "anyOf": [
        {
          "items": {},
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "title": "Audio Samples",
      "description": "Representative audio samples (shape varies by metadata_mode)"
    },
    "playback": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Playback",
      "description": "Playback URL for the trend's audio (only when requested and available)"
    },
    "freshness_score": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "title": "Freshness Score",
      "description": "Freshness score (0-1)"
    },
    "earliest_evidence_at": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time"
        },
        {
          "type": "null"
        }
      ],
      "title": "Earliest Evidence At",
      "description": "Earliest publication time among known dated evidence supporting this result; a proxy for when the underlying activity began."
    },
    "tags": {
      "anyOf": [
        {
          "items": {
            "$ref": "#/$defs/TrendTag"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "title": "Tags",
      "description": "Tags associated with this trend"
    },
    "sound_category": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Sound Category",
      "description": "Sound type: \"music\", \"speech\", \"sound_effect\", or \"mixed\""
    },
    "sound_genre": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Sound Genre",
      "description": "Primary music genre (e.g. pop, hip_hop, electronic)"
    },
    "sound_subgenre": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Sound Subgenre",
      "description": "More specific genre classification"
    },
    "sound_mood": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Sound Mood",
      "description": "Emotional tone (e.g. happy, sad, energetic, chill)"
    },
    "sound_energy": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Sound Energy",
      "description": "Energy level: \"calm\", \"low\", \"moderate\", \"high\", or \"intense\""
    },
    "sound_tempo_bpm": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "title": "Sound Tempo Bpm",
      "description": "Tempo in beats per minute"
    },
    "brand_safety": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Brand Safety",
      "description": "Brand safety rating: \"safe\", \"caution\", or \"unsafe\""
    },
    "brand_safety_reason": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Brand Safety Reason",
      "description": "Explanation for the brand safety rating"
    },
    "is_song": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "title": "Is Song",
      "description": "Whether the audio is a song (vs. spoken word, sound effect)"
    },
    "is_catchphrase": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "title": "Is Catchphrase",
      "description": "Whether the trend is built around a repeatable phrase"
    },
    "catchphrase_text": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Catchphrase Text",
      "description": "The catchphrase text, when applicable"
    },
    "has_vocals": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "title": "Has Vocals",
      "description": "Whether the audio contains vocals"
    },
    "has_lyrics": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "title": "Has Lyrics",
      "description": "Whether the audio contains sung or rapped lyrics"
    },
    "detected_language": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Detected Language",
      "description": "Detected language of the audio content"
    },
    "participation_type": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Participation Type",
      "description": "What the trend requires: open, timed, lip_sync, choreography"
    },
    "content_structure": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Content Structure",
      "description": "Shared visual pattern: none, loose, or structured"
    },
    "has_text_template": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "title": "Has Text Template",
      "description": "Whether videos share a repeatable text overlay pattern"
    },
    "text_template_description": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Text Template Description",
      "description": "Description of the text template format"
    },
    "topic_scope": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Topic Scope",
      "description": "How transferable: universal, vertical, internet_culture, event_specific, person_specific"
    },
    "content_scenarios": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "title": "Content Scenarios",
      "description": "Observed content scenarios from video analysis"
    },
    "sound_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Sound Id",
      "description": "Identifier for the trend's primary sound"
    },
    "sound_title": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Sound Title",
      "description": "Title of the trend's primary sound"
    },
    "sound_artist": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Sound Artist",
      "description": "Artist of the trend's primary sound"
    },
    "commercial_music_approved": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "title": "Commercial Music Approved",
      "description": "Whether the platform explicitly marked the sound as approved for commercial/business use. Omitted when unknown."
    },
    "audio_summary": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Audio Summary",
      "description": "Brief description of the audio content"
    },
    "lyric_snippet": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Lyric Snippet",
      "description": "Short excerpt of lyrics, when available"
    },
    "lyric_theme": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Lyric Theme",
      "description": "Thematic summary of the lyrics"
    },
    "key_instruments": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "title": "Key Instruments",
      "description": "Prominent instruments heard in the audio"
    },
    "emerged_at": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Emerged At",
      "description": "Timestamp when the trend first showed enough activity to be considered emerging. Drives the ordering of the 'emerging' sort mode."
    }
  },
  "type": "object",
  "required": [
    "id",
    "title",
    "summary"
  ],
  "$defs": {
    "TrendTag": {
      "properties": {
        "tag_name": {
          "type": "string",
          "title": "Tag Name",
          "description": "Tag label (e.g. 'Beauty', 'Comedy')"
        },
        "strength": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "title": "Strength",
          "description": "Relevance strength of this tag (0-1)"
        },
        "purpose": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Purpose",
          "description": "Why this tag applies to the trend"
        },
        "rationale": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Rationale",
          "description": "Supporting rationale for the tag assignment"
        }
      },
      "type": "object",
      "required": [
        "tag_name"
      ],
      "title": "TrendTag",
      "description": "A tag attached to a trend (e.g., 'Beauty', 'Comedy')."
    }
  }
}