feat: added example api call document; added a mockup server.

main.py

@@ -88,6 +88,8 @@ async def health():
 class LoadModelRequest(BaseModel):
     model: str  # "fullsong" | "clip"
 
+    model_config = ConfigDict(json_schema_extra={"example": {"model": "fullsong"}})
+
 
 @app.post("/v1/models/load", tags=["system"])
 async def load_model(req: LoadModelRequest):
@@ -120,7 +122,23 @@ class FullsongGenerateRequest(BaseModel):
     """ACE-Step 1.5 generation request. All listed fields are forwarded as-is;
     any additional ACE-Step fields are also accepted and forwarded."""
 
-    model_config = ConfigDict(extra="allow")
+    model_config = ConfigDict(
+        extra="allow",
+        json_schema_extra={
+            "example": {
+                "caption": "Genre: Eurodance, 90s dance-pop, upbeat electronic. Style: Catchy, energetic, nostalgic 90s Eurodance with a strong four-on-the-floor beat. Bright synth leads, punchy bassline, and rhythmic chord stabs. Mix of melodic female vocals for chorus and rhythmic male spoken/rap-style verses. Mood: Uplifting, euphoric, nostalgic club vibe. Tempo: ~130 BPM. Instrumentation: driving kick drum, eurodance bassline, bright saw synth leads, pads, dance piano accents, light vocal chops. Structure: Intro → Verse (male rap) → Pre-Chorus → Chorus (female melodic hook) → Verse → Chorus → Bridge → Final Chorus. Production: clean, polished, wide stereo, club-ready mix.",
+                "lyrics": "[Intro]\nFeel the rhythm, feel the light\nWe come alive in neon night\n\n[Verse 1 – Male]\nStep in the scene, yeah the bassline drops\nHeartbeat racing when the strobe light pops\nHands up high, let the pressure go\nMove your body to the radio\n\n[Pre-Chorus – Female]\nTake me higher, don't let go\nWe're electric, feel the flow\n\n[Chorus – Female]\nWe are dancing in the neon in the night\nShining brighter than the stars in the sky\nFeel the fire, let it take you away\nWe will never fade",
+                "instrumental": False,
+                "inference_steps": 8,
+                "guidance_scale": 7.0,
+                "use_random_seed": False,
+                "seed": -1,
+                "thinking": True,
+                "batch_size": 1,
+                "audio_format": "mp3",
+            }
+        },
+    )
 
     caption: Optional[str] = None
     lyrics: Optional[str] = None
@@ -276,6 +294,26 @@ async def fullsong_audio(task_id: str, request: Request, index: int = 0):
 class ClipGenerateRequest(BaseModel):
     """Foundation-1 clip generation request."""
 
+    model_config = ConfigDict(
+        json_schema_extra={
+            "example": {
+                "prompt": "Gritty, Acid, Bassline, 303, Synth Lead, FM, Sub, Upper Mids, High Phaser, High Reverb, Pitch Bend, 8 Bars, 140 BPM, E minor",
+                "negative_prompt": "",
+                "bars": 8,
+                "bpm": 140,
+                "note": "C",
+                "scale": "minor",
+                "steps": 75,
+                "cfg_scale": 7,
+                "seed": -1,
+                "sampler_type": "dpmpp-2m-sde",
+                "sigma_min": 0.03,
+                "sigma_max": 500,
+                "cfg_rescale": 0,
+            }
+        }
+    )
+
     prompt: str
     negative_prompt: str = ""
     bars: int = 4
@@ -325,8 +363,11 @@ async def clip_generate(req: ClipGenerateRequest, request: Request):
     summary="Poll a clip generation task result",
 )
 async def clip_result(task_id: str, request: Request):
-    """Returns task status. When `status == "complete"`, includes `wav_url` and `midi_url`
-    pointing to the gateway download endpoints."""
+    """Returns task status. When `status == "complete"`, the generation is done.
+    Download the output files using the same `task_id`:
+    - `GET /v1/clip/audio/{task_id}` → WAV
+    - `GET /v1/clip/midi/{task_id}` → MIDI
+    """
     _require("clip")
     try:
         resp = await request.app.state.http_client.get(f"{FOUNDATION1_BASE_URL}/result/{task_id}")