openapi: 3.0.0
info:
  contact:
    email: contact@holamago.com
    name: HolaMago
    url: https://www.holamago.com/
  description: Audion API Key Framework는 API 키 관리와 워크플로우 실행을 제공하는 백엔드 API입니다.
  termsOfService: https://audion.magovoice.com/api-key
  title: Audion API Key Framework
  version: "1.0"
paths:
  /health:
    get:
      description: 서비스 상태를 확인합니다.
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
      summary: Health Check
      tags:
        - health
  "/v1/apikeys/{key}":
    get:
      description: API 키의 메타데이터를 조회합니다.
      parameters:
        - description: API Key
          in: path
          name: key
          required: true
          schema:
            type: string
      responses:
        "200":
          description: OK
          content:
            "*/*":
              schema:
                additionalProperties:
                  type: string
                type: object
        "400":
          description: Bad Request
          content:
            "*/*":
              schema:
                additionalProperties:
                  type: string
                type: object
        "404":
          description: Not Found
          content:
            "*/*":
              schema:
                additionalProperties:
                  type: string
                type: object
        "500":
          description: Internal Server Error
          content:
            "*/*":
              schema:
                additionalProperties:
                  type: string
                type: object
      summary: Get API Key
      tags:
        - apikeys
  /v1/flow:
    post:
      description: |-
        파일 업로드 또는 URL 입력을 받아 Flow를 실행합니다.

        **입력 방식 (둘 중 하나 선택):**
        1. URL 방식
        - `input_type`: "url"
        - `input`: 실제 URL 주소 (예: https://example.com/video.mp4, YouTube 링크 등)
        2. 파일 업로드 방식
        - `input_type`: "file"
        - `file`: 업로드할 미디어 파일

        **플로우별 응답 차이점:**
        - `audion_vu`: 음성 이해, 감정 분석, MLLM 요약
        - `audion_vh`: 보이스 하이라이트(음성 하이라이트, 세그먼트 정보 포함)

        **선택적 응답 필드:**
        - `youtubeInfo`: YouTube URL 입력 시에만 제공
        - `segments`: audion_vh 플로우에서만 제공 (화자별 시간 구간)
        - `voice_highlight`: audion_vh 플로우에서만 제공 (각 발화별 음성 분석)
      parameters:
        - description: Audion <api-key>
          in: header
          name: Authorization
          schema:
            type: string
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                input_type:
                  description: "입력 방식: url 또는 file"
                  type: string
                flow:
                  description: "플로우 타입: audion_vu 또는 audion_vh"
                  type: string
                input:
                  description: "[input_type=url 일 때 필수] YouTube 또는 미디어 파일 URL"
                  type: string
                file:
                  description: "[input_type=file 일 때 필수] 업로드할 미디어 파일"
                  type: string
                  format: binary
              required:
                - input_type
                - flow
        required: true
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/flow.FlowResponse"
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                additionalProperties:
                  type: string
                type: object
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                additionalProperties:
                  type: string
                type: object
      summary: Execute Flow
      tags:
        - flow
servers:
  - url: https://audion.magovoice.com/api-key
components:
  schemas:
    flow.EmotionInfo:
      properties:
        best_emotion:
          example: NEUTRAL
          type: string
        decoding_time:
          example: 1.5
          type: number
        emotion:
          additionalProperties:
            type: integer
          example:
            ANGRY: 5
            HAPPINESS: 30
            NEUTRAL: 45
            SADNESS: 15
            SURPRISE: 5
          type: object
        filename:
          example: audio/segment_001.wav
          type: string
        principal_vocal_biomarkers:
          $ref: "#/components/schemas/flow.VocalBiomarkers"
        result_path:
          example: analysis/emotion_001.json
          type: string
      type: object
    flow.FlowContent:
      properties:
        documentId:
          example: 12345678-1234-1234-1234-123456789abc
          type: string
        filePath:
          example: uploads/audio/sample.mp4
          type: string
        flowingTime:
          example: 5.25
          type: number
        output:
          $ref: "#/components/schemas/flow.FlowOutput"
        resultPath:
          example: results/output/result.json
          type: string
        thumbnailPath:
          example: thumbnails/sample.jpg
          type: string
        uploadFilename:
          example: sample_audio.mp3
          type: string
        youtubeInfo:
          allOf:
            - $ref: "#/components/schemas/flow.YouTubeInfo"
          description: YouTube URL 입력 시에만 제공되는 메타데이터
      type: object
    flow.FlowOutput:
      properties:
        mediaInfo:
          $ref: "#/components/schemas/flow.MediaInfo"
        mllm:
          description: MLLM 분석 결과 (대화 요약, 키워드, 감정 분석)
          type: object
        segments:
          description: audion_vh 플로우에서만 제공되는 세그먼트 정보
          items:
            type: object
          type: array
        speakerInfo:
          $ref: "#/components/schemas/flow.SpeakerInfo"
        srt:
          example: subtitles/sample.srt
          type: string
        utterances:
          items:
            $ref: "#/components/schemas/flow.Utterance"
          type: array
        vtt:
          example: subtitles/sample.vtt
          type: string
      type: object
    flow.FlowResponse:
      properties:
        content:
          $ref: "#/components/schemas/flow.FlowContent"
        message:
          example: Flow execution completed
          type: string
        status:
          example: success
          type: string
      type: object
    flow.MediaInfo:
      properties:
        bits_per_raw_sample:
          example: 16
          type: integer
        channels:
          example: 2
          type: integer
        codec_name:
          example: aac
          type: string
        codec_type:
          example: audio
          type: string
        duration:
          example: 120.5
          type: number
        sample_fmt:
          example: fltp
          type: string
        sample_rate:
          example: 44100
          type: integer
      type: object
    flow.SpeakerInfo:
      properties:
        duration:
          additionalProperties:
            format: float64
            type: number
          example:
            SPEAKER_01: 60.5
          type: object
        num_speakers:
          example: 2
          type: integer
        speakers:
          example:
            - SPEAKER_01
            - SPEAKER_02
          items:
            type: string
          type: array
      type: object
    flow.SpeedInfo:
      properties:
        speech_level:
          example: "1"
          type: string
        speed:
          example: 5.5
          type: number
      type: object
    flow.Utterance:
      properties:
        emotion:
          example: NEUTRAL
          type: string
        emotion_info:
          $ref: "#/components/schemas/flow.EmotionInfo"
        end:
          example: 15.5
          type: number
        filename:
          example: audio/segment_001.wav
          type: string
        id:
          example: segment_001
          type: string
        score:
          example: -0.25
          type: number
        speaker:
          example: SPEAKER_01
          type: string
        speed_info:
          $ref: "#/components/schemas/flow.SpeedInfo"
        start:
          example: 10.2
          type: number
        text:
          example: 안녕하세요. 오늘 날씨가 정말 좋네요.
          type: string
        voice_highlight:
          description: audion_vh 플로우에서만 제공되는 음성 하이라이트 분석 (JSON 객체)
          type: object
      type: object
    flow.VocalBiomarkers:
      properties:
        brightness:
          example: 850.5
          type: number
        pitch:
          example: 180.25
          type: number
        pitch_variation:
          example: 25.8
          type: number
        rms:
          example: 0.15
          type: number
        snr:
          example: 4.2
          type: number
      type: object
    flow.YouTubeInfo:
      properties:
        audioPath:
          example: youtube/audio/sample.mp3
          type: string
        metadata:
          $ref: "#/components/schemas/flow.YouTubeMetadata"
        videoPath:
          example: youtube/video/sample.mp4
          type: string
      type: object
    flow.YouTubeMetadata:
      properties:
        description:
          example: 샘플 영상 설명입니다.
          type: string
        dislike_count:
          example: 5
          type: integer
        duration:
          example: 120
          type: integer
        id:
          example: dQw4w9WgXcQ
          type: string
        like_count:
          example: 1000
          type: integer
        thumbnail:
          example: https://i.ytimg.com/vi/dQw4w9WgXcQ/maxresdefault.jpg
          type: string
        title:
          example: 샘플 영상 제목
          type: string
        upload_date:
          example: "20240101"
          type: string
        uploader:
          example: Sample Channel
          type: string
        view_count:
          example: 50000
          type: integer
        webpage_url:
          example: https://www.youtube.com/watch?v=dQw4w9WgXcQ
          type: string
      type: object
