One API key, eight AI models

What you can build

Prices use the same wallet as the web app: song credits for music and video credits (1 credit = 1,000₫ ≈ $0.04) for everything else. See Pricing & limits.

1. Get an API key

Sign in with your Meloria account, then create a key. Keep it secret (you can reveal it again here or on your account page). Creating a new key replaces the old one; revoking stops all API access immediately.

2. Quick start

Every generation is a job: create it with one POST, then poll GET /api/v1/jobs/{id} every few seconds until status is done. Results are plain MP3/MP4 URLs.

# 1) create a 60-second lo-fi track (instrumental)
curl -X POST https://meloria.ai/api/v1/music \
  -H "Authorization: Bearer mk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"calm lo-fi hip hop, warm piano, vinyl crackle, rain","instrumental":true,"duration":60}'

# → {"ok":true,"id":"j9f1c2…","model":"music","status":"queued","progress":0,…}

# 2) poll until done
curl https://meloria.ai/api/v1/jobs/j9f1c2… -H "Authorization: Bearer mk_live_…"

# → {"ok":true,"status":"done","progress":100,"result":{"tracks":[{"audio_url":"https://meloria.ai/mp3/music/….mp3","title":"…","duration":60}]}}

Python

import requests, time
H = {"Authorization": "Bearer mk_live_…"}
job = requests.post("https://meloria.ai/api/v1/music", headers=H,
                    json={"prompt": "uplifting pop, female vocal", "lyrics": "…", "duration": 120}).json()
while True:
    j = requests.get(f"https://meloria.ai/api/v1/jobs/{job['id']}", headers=H).json()
    if j["status"] in ("done", "error"): break
    time.sleep(5)
print(j)

3. Authentication

Send your key in the Authorization header on every request (or in X-API-Key). Keys start with mk_live_. Never embed a key in client-side code — call the API from your server.

Authorization: Bearer mk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
# or
X-API-Key: mk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Base URL: https://meloria.ai/api/v1. Request bodies are JSON (Content-Type: application/json) or multipart/form-data when files are uploaded. All responses are JSON and include ok.

4. Jobs & polling

Your 20 most recent API jobs (no result refresh — poll individual jobs for live status).

🎵 Music — instrumental or with lyrics

Result: result.tracks[] with audio_url, title, lyrics, duration, genre, bpm, instrumental.

curl -X POST https://meloria.ai/api/v1/music -H "Authorization: Bearer mk_live_…" -H "Content-Type: application/json" -d '{
  "prompt": "Vietnamese ballad, acoustic guitar, emotional female vocal",
  "lyrics": "[Verse]\nĐêm nay phố vắng…\n[Chorus]\n…",
  "vocal_language": "vi", "vocal_gender": "female", "duration": "auto", "bitrate": "320k"
}'

🎤 Music video (MV) — singing photo

Result: result.video_url (MP4). The job may take 3–8 minutes.

curl -X POST https://meloria.ai/api/v1/mv -H "Authorization: Bearer mk_live_…" \
  -F "[email protected]" -F "[email protected]" -F "aspect=9:16" -F "style=stage" -F "hd=1"

🎬 MV Pro — multi-scene AI music video from a song

Phases: analyze (vocal/instrumental segmentation) → images (script + one AI image per scene; scenes_ready/scenes show progress) → render. Typically 10–25 scenes and 10–20 minutes for a 3-minute song.

Result: result.video_url (MP4), result.title, result.scenes, result.song_credits_used. Cost: 1 song credit per scene image + video credits ⌈seconds × rate × 2⌉ (min 12).

curl -X POST https://meloria.ai/api/v1/mvpro -H "Authorization: Bearer mk_live_…" \
  -F "[email protected]" -F "lyrics=<song.txt" -F "title=Đêm Hà Nội" -F "[email protected]" \
  -F "style=cine" -F "aspect=16:9" -F "idea=rainy city at night, lost love"

💃 Dance video

Result: result.video_url (MP4). Price ≈ MV × 1.3.

👗 Fashion review

Result: result.video_url (MP4) — ready for TikTok, Reels, Shopee.

🗣️ Talking video — a photo reads your text (≤ 2 min)

The job runs in phases: voice (text-to-speech) → scenes → render. Scenes longer than ~22 s are split automatically and joined seamlessly.

Result: result.video_url (MP4), result.audio_url (the narration MP3), result.duration.

curl -X POST https://meloria.ai/api/v1/talk -H "Authorization: Bearer mk_live_…" \
  -F "[email protected]" -F "lang=en" -F "aspect=16:9" -F "hd=1" \
  -F "text=Hi everyone, welcome to today's product update. In the next two minutes I'll show you…"

🎙️ Podcast — AI-written, AI-read series

Result: result.title, result.episodes[] with n, title, status, audio_url (MP3), duration. While running, phase is planning then episode_N, and finished episodes already appear in result.

curl -X POST https://meloria.ai/api/v1/podcast -H "Authorization: Bearer mk_live_…" -H "Content-Type: application/json" \
  -d '{"topic":"Simple habits that improve sleep","kind":"podcast","episodes":3,"minutes":5,"lang":"en"}'

🎧 Text to speech — long text → MP3

Result: result.audio_url (MP3, 1 file), result.duration. Files are kept 7 days.

curl -X POST https://meloria.ai/api/v1/tts -H "Authorization: Bearer mk_live_…" -H "Content-Type: application/json" \
  -d '{"text":"Chapter one. It was a bright cold day in April…","lang":"en","voice":"vx:en_f_story|Emma|f","speed":1.0,"tone":"story"}'

Account & voices

Your balances: songs_remaining, video_credits, video_rate (credits per second for video, depends on your last pack), plan.

Voices for a language: voices[] = {id, name, gender}. Pass id as voice to talk / podcast / tts. Special id kid = child voice.

Errors

Errors return {"ok":false,"error":"code"} with an HTTP status:

Pricing & limits

The API uses the same wallet as meloria.ai and the Meloria app — no separate API plan. Prices are the web prices; nothing extra for API access.

rate = your video price per second: 1.00 credit/s by default, 0.90 after a 99-credit pack, 0.70 after a 199-credit pack (see GET /api/v1/me). 1 credit = 1,000₫ (≈ $0.04); packs from $1.99 at /pricing.

Charges are held when a job starts and settled on completion; failed or timed-out jobs are refunded automatically. Generated files are yours to use commercially under the Terms; content must comply with our policies (no adult content, no impersonation of real people without consent).

Questions or need higher limits? Contact us.