ReferenceAudioRequest

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/audiopod-ai/json-schema/audiopod-ai-reference-audio-request-schema.json",
  "title": "ReferenceAudioRequest",
  "description": "Request for generation with reference audio for style guidance.\n\nReference audio provides global acoustic feature control:\n- Timbre texture (vocal/instrument timbre)\n- Mixing style (spatial sense, dynamic range)\n- Performance style (techniques, expression)\n- Overall atmosphere",
  "x-generated": "2026-10-29",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/audiopod-ai-openapi.json#/components/schemas/ReferenceAudioRequest",
  "properties": {
    "duration": {
      "type": "number",
      "maximum": 600.0,
      "minimum": -1.0,
      "title": "Duration",
      "description": "Audio duration in seconds (-1 for auto-detection based on lyrics, max 600s/10min)",
      "default": -1.0
    },
    "audio_duration": {
      "type": "number",
      "maximum": 600.0,
      "minimum": -1.0,
      "title": "Audio Duration",
      "description": "Alias for duration (legacy)"
    },
    "format": {
      "$ref": "#/$defs/app__schemas__music__AudioFormat",
      "description": "Output audio format (flac recommended for quality)",
      "default": "flac"
    },
    "model_version": {
      "anyOf": [
        {
          "$ref": "#/$defs/ModelVersion"
        },
        {
          "type": "null"
        }
      ],
      "description": "Model version: audiomusic-v2 (default) or audiomusic-v1.5",
      "default": "audiomusic-v2"
    },
    "quality": {
      "anyOf": [
        {
          "$ref": "#/$defs/MusicQuality"
        },
        {
          "type": "null"
        }
      ],
      "description": "Deprecated and ignored. Every plan generates with AudioPod's highest-quality music model at the same rate; both values are accepted for compatibility and behave identically."
    },
    "bpm": {
      "anyOf": [
        {
          "type": "integer",
          "maximum": 300.0,
          "minimum": 30.0
        },
        {
          "type": "null"
        }
      ],
      "title": "Bpm",
      "description": "Beats per minute (30-300). None for auto-detection via LM."
    },
    "keyscale": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 50
        },
        {
          "type": "null"
        }
      ],
      "title": "Keyscale",
      "description": "Musical key (e.g. 'C Major', 'Am', 'F# minor'). Empty for auto-detection."
    },
    "timesignature": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 10
        },
        {
          "type": "null"
        }
      ],
      "title": "Timesignature",
      "description": "Time signature (2='2/4', 3='3/4', 4='4/4', 6='6/8'). Empty for auto-detection."
    },
    "vocal_language": {
      "type": "string",
      "maxLength": 20,
      "title": "Vocal Language",
      "description": "Language code for vocals (ISO 639-1: 'en', 'zh', 'ja', etc.). 'unknown' for auto-detection.",
      "default": "unknown"
    },
    "inference_steps": {
      "type": "integer",
      "maximum": 200.0,
      "minimum": 1.0,
      "title": "Inference Steps",
      "description": "Diffusion steps. SFT/Base: 64 for best quality (32-100 range). Turbo: 8.",
      "default": 64
    },
    "infer_step": {
      "type": "integer",
      "maximum": 200.0,
      "minimum": 1.0,
      "title": "Infer Step",
      "description": "Alias for inference_steps (legacy)"
    },
    "guidance_scale": {
      "type": "number",
      "maximum": 15.0,
      "minimum": 1.0,
      "title": "Guidance Scale",
      "description": "CFG scale (1.0-15.0). Higher = more adherence to prompt.",
      "default": 7.0
    },
    "seed": {
      "type": "integer",
      "title": "Seed",
      "description": "Random seed (-1 for random, positive for fixed)",
      "default": -1
    },
    "shift": {
      "type": "number",
      "maximum": 5.0,
      "minimum": 1.0,
      "title": "Shift",
      "description": "Timestep shift factor (1.0-5.0). 3.0 recommended for all models.",
      "default": 3.0
    },
    "infer_method": {
      "$ref": "#/$defs/InferMethod",
      "description": "Inference method: 'ode' (Euler, fast) or 'sde' (stochastic)",
      "default": "ode"
    },
    "use_adg": {
      "type": "boolean",
      "title": "Use Adg",
      "description": "Adaptive Dual Guidance (base model only). Improves quality at the cost of speed.",
      "default": false
    },
    "cfg_interval_start": {
      "type": "number",
      "maximum": 1.0,
      "minimum": 0.0,
      "title": "Cfg Interval Start",
      "description": "CFG application start ratio (0.0-1.0)",
      "default": 0.0
    },
    "cfg_interval_end": {
      "type": "number",
      "maximum": 1.0,
      "minimum": 0.0,
      "title": "Cfg Interval End",
      "description": "CFG application end ratio (0.0-1.0)",
      "default": 1.0
    },
    "timesteps": {
      "anyOf": [
        {
          "items": {
            "type": "number"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "title": "Timesteps",
      "description": "Custom timesteps list from 1.0 to 0.0. Overrides inference_steps and shift if provided."
    },
    "thinking": {
      "type": "boolean",
      "title": "Thinking",
      "description": "Enable LM Chain-of-Thought reasoning for semantic planning",
      "default": true
    },
    "lm_temperature": {
      "type": "number",
      "maximum": 2.0,
      "minimum": 0.0,
      "title": "Lm Temperature",
      "description": "LM sampling temperature. Higher = more creative.",
      "default": 0.85
    },
    "lm_cfg_scale": {
      "type": "number",
      "maximum": 10.0,
      "minimum": 0.0,
      "title": "Lm Cfg Scale",
      "description": "LM classifier-free guidance scale",
      "default": 2.0
    },
    "lm_top_k": {
      "type": "integer",
      "maximum": 100.0,
      "minimum": 0.0,
      "title": "Lm Top K",
      "description": "LM top-k sampling. 0 disables.",
      "default": 0
    },
    "lm_top_p": {
      "type": "number",
      "maximum": 1.0,
      "minimum": 0.0,
      "title": "Lm Top P",
      "description": "LM nucleus sampling. 1.0 disables.",
      "default": 0.9
    },
    "lm_negative_prompt": {
      "type": "string",
      "maxLength": 512,
      "title": "Lm Negative Prompt",
      "description": "Negative prompt for LM classifier-free guidance",
      "default": "NO USER INPUT"
    },
    "use_cot_metas": {
      "type": "boolean",
      "title": "Use Cot Metas",
      "description": "Generate metadata using LM CoT reasoning",
      "default": true
    },
    "use_cot_caption": {
      "type": "boolean",
      "title": "Use Cot Caption",
      "description": "Refine caption using LM CoT reasoning",
      "default": true
    },
    "use_cot_lyrics": {
      "type": "boolean",
      "title": "Use Cot Lyrics",
      "description": "Generate/refine lyrics using LM CoT reasoning (reserved)",
      "default": false
    },
    "use_cot_language": {
      "type": "boolean",
      "title": "Use Cot Language",
      "description": "Detect vocal language using LM CoT reasoning",
      "default": true
    },
    "use_constrained_decoding": {
      "type": "boolean",
      "title": "Use Constrained Decoding",
      "description": "Enable constrained decoding for structured LM output",
      "default": true
    },
    "lora_name_or_path": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Lora Name Or Path",
      "description": "LoRA adapter path for custom styles"
    },
    "lora_weight": {
      "type": "number",
      "maximum": 3.0,
      "minimum": -3.0,
      "title": "Lora Weight",
      "description": "LoRA weight",
      "default": 1.0
    },
    "batch_size": {
      "type": "integer",
      "maximum": 8.0,
      "minimum": 1.0,
      "title": "Batch Size",
      "description": "Number of variations to generate (1-8)",
      "default": 1
    },
    "thumbnail_url": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 1024
        },
        {
          "type": "null"
        }
      ],
      "title": "Thumbnail Url",
      "description": "URL for the music thumbnail"
    },
    "manual_seeds": {
      "anyOf": [
        {
          "items": {
            "type": "integer"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "title": "Manual Seeds",
      "description": "Manual seeds for batch generation (legacy)"
    },
    "scheduler_type": {
      "anyOf": [
        {
          "$ref": "#/$defs/SchedulerType"
        },
        {
          "type": "null"
        }
      ],
      "description": "Legacy scheduler type (use infer_method instead)"
    },
    "cfg_type": {
      "anyOf": [
        {
          "$ref": "#/$defs/CFGType"
        },
        {
          "type": "null"
        }
      ],
      "description": "Legacy CFG type"
    },
    "use_sde": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "title": "Use Sde",
      "description": "Legacy SDE flag (use infer_method='sde' instead)"
    },
    "debug": {
      "type": "boolean",
      "title": "Debug",
      "description": "Enable debug mode",
      "default": false
    },
    "display_name": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 255
        },
        {
          "type": "null"
        }
      ],
      "title": "Display Name",
      "description": "Display name for the track"
    },
    "caption": {
      "type": "string",
      "maxLength": 2048,
      "minLength": 1,
      "title": "Caption",
      "description": "Text description of desired music"
    },
    "lyrics": {
      "type": "string",
      "maxLength": 4096,
      "title": "Lyrics",
      "description": "Lyrics with structure tags",
      "default": ""
    },
    "reference_audio_url": {
      "type": "string",
      "maxLength": 2048,
      "minLength": 1,
      "title": "Reference Audio Url",
      "description": "URL to reference audio for style guidance"
    },
    "instrumental": {
      "type": "boolean",
      "title": "Instrumental",
      "description": "Generate instrumental music",
      "default": false
    }
  },
  "type": "object",
  "required": [
    "caption",
    "reference_audio_url"
  ],
  "$defs": {
    "CFGType": {
      "type": "string",
      "enum": [
        "apg",
        "cfg",
        "zero_star"
      ],
      "title": "CFGType",
      "description": "Classifier-free guidance types (legacy)"
    },
    "InferMethod": {
      "type": "string",
      "enum": [
        "ode",
        "sde"
      ],
      "title": "InferMethod",
      "description": "Diffusion inference methods for music generation"
    },
    "ModelVersion": {
      "type": "string",
      "enum": [
        "audiomusic-v2",
        "audiomusic-v1.5",
        "audiomusic-v3"
      ],
      "title": "ModelVersion",
      "description": "Available music generation model versions"
    },
    "MusicQuality": {
      "type": "string",
      "enum": [
        "standard",
        "premium"
      ],
      "title": "MusicQuality",
      "description": "Legacy quality selector for music generation.\n\nEvery plan now generates with AudioPod's highest-quality music model at\none rate. Both values are still accepted and behave identically."
    },
    "SchedulerType": {
      "type": "string",
      "enum": [
        "euler",
        "heun",
        "pingpong"
      ],
      "title": "SchedulerType",
      "description": "Diffusion scheduler types (legacy - use InferMethod for music generation)"
    },
    "app__schemas__music__AudioFormat": {
      "type": "string",
      "enum": [
        "wav",
        "mp3",
        "flac",
        "ogg"
      ],
      "title": "AudioFormat",
      "description": "Supported audio output formats"
    }
  }
}