The Valiha API

https://valiha.marindrano.com/v1

Authorization: Bearer vk_live_...

curl -X POST https://valiha.marindrano.com/v1/songs \
  -H "Authorization: Bearer $VALIHA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Antsoantso",
    "artist": "Rija",
    "language": "mg",
    "lyrics": "[Verse 1]\nTompo ô, Ianao no hirako\nNy fitiavanao no tanjako",
    "audioUrl": "https://example.com/antsoantso.mp3",
    "webhookUrl": "https://example.com/hooks/valiha",
    "externalId": "song-1042",
    "options": { "stems": 6, "melody": ["game", "choir"] }
  }'

curl -X POST https://valiha.marindrano.com/v1/songs \
  -H "Authorization: Bearer $VALIHA_KEY" \
  -F "title=Antsoantso" \
  -F "language=mg" \
  -F "lyrics=<lyrics.txt" \
  -F "audio=@antsoantso.mp3" \
  -F "webhookUrl=https://example.com/hooks/valiha" \
  -F "externalId=song-1042" \
  -F 'options={"stems": 6, "melody": ["game", "choir"]}'

{ "stems": 4, "melody": ["game"] }

HTTP/1.1 202 Accepted

{
  "id": "cm3k2x8f40001",
  "externalId": "song-1042",
  "status": "queued",
  "options": { "stems": 6, "melody": ["game", "choir"] },
  "createdAt": "2026-10-27T09:12:00.000Z"
}

curl https://valiha.marindrano.com/v1/songs/cm3k2x8f40001 \
  -H "Authorization: Bearer $VALIHA_KEY"

curl "https://valiha.marindrano.com/v1/songs?externalId=song-1042" \
  -H "Authorization: Bearer $VALIHA_KEY"

{
  "id": "cm3k2x8f40001",
  "externalId": "song-1042",
  "status": "ready",
  "title": "Antsoantso",
  "artist": "Rija",
  "language": "mg",
  "key": "G",
  "bpm": 91,
  "timeSignature": "4/4",
  "durationSeconds": 212.4,
  "error": null,
  "chart": {
    "chordpro": "{title: Antsoantso}\n{key: G}\n{tempo: 91}\n{time: 4/4}\n...",
    "sections": [
      { "kind": "verse", "label": "Verse 1", "start": 8.2, "end": 41.6 }
    ],
    "chords": [
      { "time": 8.21, "beat": 12, "name": "G" },
      { "time": 10.84, "beat": 16, "name": "D/F#" }
    ]
  },
  "options": { "stems": 6, "melody": ["game", "choir"] },
  "stems": ["vocals", "drums", "bass", "guitar", "piano", "other"],
  "melody": {
    "version": 1,
    "model": "game",
    "engine": { "version": "0.1.0" },
    "sha1": "9b1c4e...",
    "tuning": -12.5,
    "notes": [
      { "start": 8.31, "end": 8.74, "midi": 67, "beat": 12, "length": 1, "conf": 1, "syllable": [0, 0, 0, 0] }
    ],
    "timings": { "notes": 0.41 }
  },
  "voices": {
    "version": 1,
    "model": "choir",
    "sha1": "9b1c4e...",
    "tuning": -12.5,
    "notes": [
      { "start": 8.3, "end": 8.76, "midi": 67, "velocity": 0.81 },
      { "start": 8.3, "end": 8.76, "midi": 59, "velocity": 0.44 }
    ],
    "timings": { "features": 3.2, "model": 18.7 }
  },
  "createdAt": "2026-10-27T09:12:00.000Z",
  "updatedAt": "2026-10-27T09:15:32.000Z"
}

curl https://valiha.marindrano.com/v1/songs/cm3k2x8f40001/chordpro \
  -H "Authorization: Bearer $VALIHA_KEY" \
  -o antsoantso.cho

curl https://valiha.marindrano.com/v1/songs/cm3k2x8f40001/stems/vocals \
  -H "Authorization: Bearer $VALIHA_KEY" \
  -o vocals.m4a

curl -X POST https://valiha.marindrano.com/v1/songs/cm3k2x8f40001/analyze \
  -H "Authorization: Bearer $VALIHA_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "options": { "stems": 2, "melody": ["game"] } }'

HTTP/1.1 202 Accepted

{
  "id": "cm3k2x8f40001",
  "externalId": "song-1042",
  "status": "queued",
  "options": { "stems": 2, "melody": ["game"] },
  "createdAt": "2026-10-27T09:12:00.000Z"
}

curl -X DELETE https://valiha.marindrano.com/v1/songs/cm3k2x8f40001 \
  -H "Authorization: Bearer $VALIHA_KEY"

POST https://example.com/hooks/valiha
Content-Type: application/json
User-Agent: Valiha-Webhook/1
X-Valiha-Event: song.ready
X-Valiha-Timestamp: 1793092532
X-Valiha-Signature: sha256=5f0c9a...

{"event": "song.ready", "song": { ...the song object... }}

import { createHmac, timingSafeEqual } from "node:crypto";

export function isFromValiha(rawBody, headers, webhookSecret) {
  const timestamp = headers["x-valiha-timestamp"];
  const signature = headers["x-valiha-signature"] ?? "";
  const age = Math.abs(Date.now() / 1000 - Number(timestamp));
  if (!timestamp || !(age < 300)) return false;

  const expected =
    "sha256=" +
    createHmac("sha256", webhookSecret)
      .update(`${timestamp}.${rawBody}`)
      .digest("hex");

  const a = Buffer.from(signature);
  const b = Buffer.from(expected);
  return a.length === b.length && timingSafeEqual(a, b);
}

import hashlib
import hmac
import time


def is_from_valiha(raw_body: bytes, headers, webhook_secret: str) -> bool:
    timestamp = headers.get("X-Valiha-Timestamp", "")
    signature = headers.get("X-Valiha-Signature", "")
    try:
        age = abs(time.time() - int(timestamp))
    except ValueError:
        return False
    if age >= 300:
        return False
    digest = hmac.new(
        webhook_secret.encode(),
        timestamp.encode() + b"." + raw_body,
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(signature, "sha256=" + digest)

HTTP/1.1 404 Not Found

{ "error": { "code": "not_found", "message": "This song does not exist" } }

#!/usr/bin/env bash
set -euo pipefail

API="https://valiha.marindrano.com/v1"
AUTH="Authorization: Bearer $VALIHA_KEY"

# 1. Create the song from a file on disk
id=$(curl -sS -X POST "$API/songs" -H "$AUTH" \
  -F "title=Antsoantso" \
  -F "language=mg" \
  -F "lyrics=<lyrics.txt" \
  -F "audio=@antsoantso.mp3" \
  -F 'options={"stems": 4, "melody": ["game"]}' | jq -r .id)
echo "Created $id"

# 2. Wait for the analysis
while :; do
  status=$(curl -sS "$API/songs/$id" -H "$AUTH" | jq -r .status)
  echo "Status: $status"
  case "$status" in ready | failed) break ;; esac
  sleep 10
done

# 3. Save the song, the chart and the stems
curl -sS "$API/songs/$id" -H "$AUTH" -o song.json
if [ "$status" = failed ]; then
  jq -r .error song.json
  exit 1
fi
curl -sS "$API/songs/$id/chordpro" -H "$AUTH" -o antsoantso.cho
for stem in $(jq -r '.stems[]' song.json); do
  curl -sS "$API/songs/$id/stems/$stem" -H "$AUTH" -o "$stem.m4a"
done

import { openAsBlob } from "node:fs";
import { writeFile } from "node:fs/promises";

const API = "https://valiha.marindrano.com/v1";
const headers = { Authorization: `Bearer ${process.env.VALIHA_KEY}` };

async function call(path, init = {}) {
  const response = await fetch(`${API}${path}`, {
    ...init,
    headers: { ...headers, ...init.headers },
  });
  if (!response.ok) {
    const body = await response.json().catch(() => null);
    throw new Error(body?.error?.message ?? `HTTP ${response.status}`);
  }
  return response;
}

// 1. Create the song from a file on disk
const form = new FormData();
form.set("title", "Antsoantso");
form.set("language", "mg");
form.set("lyrics", "[Verse 1]\nTompo ô, Ianao no hirako\nNy fitiavanao no tanjako");
form.set("externalId", "song-1042");
form.set("options", JSON.stringify({ stems: 4, melody: ["game"] }));
form.set(
  "audio",
  await openAsBlob("antsoantso.mp3", { type: "audio/mpeg" }),
  "antsoantso.mp3",
);
const created = await (await call("/songs", { method: "POST", body: form })).json();
console.log("Created", created.id);

// 2. Wait for the analysis
let song;
for (;;) {
  song = await (await call(`/songs/${created.id}`)).json();
  if (song.status === "ready" || song.status === "failed") break;
  await new Promise((resolve) => setTimeout(resolve, 10_000));
}
if (song.status === "failed") throw new Error(song.error);

// 3. Save the chart and the stems
console.log(song.key, song.bpm, song.chart.chords.length, "chord changes");
await writeFile("antsoantso.cho", song.chart.chordpro);
for (const name of song.stems) {
  const audio = await call(`/songs/${song.id}/stems/${name}`);
  await writeFile(`${name}.m4a`, Buffer.from(await audio.arrayBuffer()));
}

await call("/songs", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    title: "Antsoantso",
    language: "mg",
    lyrics: "",
    audioUrl: "https://example.com/antsoantso.mp3",
    webhookUrl: "https://example.com/hooks/valiha",
    options: { stems: 2, melody: [] },
  }),
});

import { createServer } from "node:http";

createServer(async (request, response) => {
  const chunks = [];
  for await (const chunk of request) chunks.push(chunk);
  const rawBody = Buffer.concat(chunks).toString("utf8");

  if (!isFromValiha(rawBody, request.headers, process.env.VALIHA_WEBHOOK_SECRET)) {
    response.writeHead(401).end();
    return;
  }
  response.writeHead(204).end();

  const { event, song } = JSON.parse(rawBody);
  console.log(event, song.id, song.status);
}).listen(3000);

import json
import os
import time

import requests

API = "https://valiha.marindrano.com/v1"
session = requests.Session()
session.headers["Authorization"] = f"Bearer {os.environ['VALIHA_KEY']}"


def check(response: requests.Response) -> requests.Response:
    if not response.ok:
        try:
            message = response.json()["error"]["message"]
        except ValueError:
            message = f"HTTP {response.status_code}"
        raise RuntimeError(message)
    return response


# 1. Create the song from a file on disk
with open("lyrics.txt", encoding="utf-8") as f:
    lyrics = f.read()
with open("antsoantso.mp3", "rb") as audio:
    created = check(
        session.post(
            f"{API}/songs",
            data={
                "title": "Antsoantso",
                "language": "mg",
                "lyrics": lyrics,
                "externalId": "song-1042",
                "options": json.dumps({"stems": 4, "melody": ["game"]}),
            },
            files={"audio": ("antsoantso.mp3", audio, "audio/mpeg")},
            timeout=300,
        )
    ).json()
print("Created", created["id"])

# 2. Wait for the analysis
while True:
    song = check(session.get(f"{API}/songs/{created['id']}", timeout=30)).json()
    if song["status"] in ("ready", "failed"):
        break
    time.sleep(10)
if song["status"] == "failed":
    raise RuntimeError(song["error"])

# 3. Save the chart and the stems
print(song["key"], song["bpm"], len(song["chart"]["chords"]), "chord changes")
with open("antsoantso.cho", "w", encoding="utf-8") as f:
    f.write(song["chart"]["chordpro"])
for name in song["stems"]:
    stem = check(session.get(f"{API}/songs/{song['id']}/stems/{name}", timeout=120))
    with open(f"{name}.m4a", "wb") as f:
        f.write(stem.content)

check(
    session.post(
        f"{API}/songs",
        json={
            "title": "Antsoantso",
            "language": "mg",
            "lyrics": "",
            "audioUrl": "https://example.com/antsoantso.mp3",
            "webhookUrl": "https://example.com/hooks/valiha",
            "options": {"stems": 2, "melody": []},
        },
        timeout=120,
    )
)

import os

from flask import Flask, request

app = Flask(__name__)


@app.post("/hooks/valiha")
def valiha_webhook():
    raw_body = request.get_data()
    if not is_from_valiha(raw_body, request.headers, os.environ["VALIHA_WEBHOOK_SECRET"]):
        return "", 401
    payload = request.get_json()
    print(payload["event"], payload["song"]["id"], payload["song"]["status"])
    return "", 204