Songs and lyrics from your own app
A simple REST API with JSON in and out. It uses the same credits and prices as the studio, and tells your server when a song is ready.
Getting started
- The API is part of the Pro, Studio plans. Choose one on the Pricing page.
- Create a key on the API keys page (up to 5 keys). It is shown once – keep it on your server, never in a browser or an app.
- Write lyrics, start a song, then poll its status (every 20 seconds is plenty) or let us call your webhook.
https://ohang.tj/api/v1Send and receive JSON (Content-Type and Accept: application/json). Lengths are in seconds.
Authentication
Send your key in the Authorization: Bearer sm_live_… header on every call. A wrong or revoked key answers 401; a plan without the API answers 403.
curl https://ohang.tj/api/v1/credits \
-H "Authorization: Bearer $SONGMORA_KEY" \
-H "Accept: application/json" <?php
$ch = curl_init('https://ohang.tj/api/v1/credits');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('SONGMORA_KEY'),
'Accept: application/json',
],
]);
$data = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE); const res = await fetch('https://ohang.tj/api/v1/credits', {
headers: {
'Authorization': `Bearer ${process.env.SONGMORA_KEY}`,
'Accept': 'application/json',
},
});
const data = await res.json(); import os
import requests
res = requests.get(
"https://ohang.tj/api/v1/credits",
headers={"Authorization": f"Bearer {os.environ['SONGMORA_KEY']}", "Accept": "application/json"},
)
data = res.json() Credits & prices
API calls spend the same credit balance as the studio, at the same prices. Lyrics are free. A song costs:
| Length | Standard standard | HD hd |
|---|---|---|
30 30 seconds | 2 credits | 5 credits |
60 1 minute | 3 credits | 7 credits |
150 2 min 30 s | 4 credits | 10 credits |
240 4 minutes | 6 credits | 14 credits |
Credits are reserved when a song starts, charged when it is ready and returned in full if it fails. Your plan decides the longest song, HD quality and private songs.
Rate limits
Each key may send a number of requests per minute. Every answer carries X-RateLimit-Limit and X-RateLimit-Remaining; above the limit you get 429 with Retry-After (seconds).
| Plan | Requests per minute | Songs at the same time |
|---|---|---|
| Pro | 60 | 2 |
| Studio | 120 | 5 |
Errors
Errors answer with an HTTP status and a JSON body: {"error": {"code": "…", "message": "…", "fields": {…}}}. Show the message to your users as it is. On 422 error.fields lists the problem of each field.
| Status | Code | Meaning |
|---|---|---|
| 401 | invalid_key | The key is missing, wrong or revoked. |
| 402 | insufficient_credits | Not enough credits for this song or lyric draft. Buy credits or the next plan period. |
| 403 | plan_without_api | Your plan does not include the API. |
| 403 | account_inactive | The account cannot use the API. |
| 404 | not_found | No such endpoint, or no job with this id on your account. |
| 409 | request_in_progress | A request with the same Idempotency-Key is still running. |
| 422 | invalid_request | A field is missing or wrong – error.fields lists them. |
| 422 | limit_reached | A plan limit: length, HD, private songs, lyric drafts a day or songs at the same time. |
| 429 | rate_limited | Too many requests – wait for Retry-After seconds. |
| 502 | provider_error | The music or lyrics engine failed. Nothing was charged; try again. |
| 503 | provider_error | No lyrics engine is available right now. Nothing was charged; try again later. |
| 503 | api_disabled | The API is switched off on this site for now. |
| 500 | server_error | Something went wrong on our side. Try again. |
Webhooks
Pass webhook_url when you create a song and we POST the finished job to that address – event song.completed or song.failed, with the same JSON as Song status in data.
Every call is signed: X-Songmora-Signature: sha256=… is the HMAC-SHA256 of the raw request body with your key’s webhook secret (on the API keys page). Check it before you trust the body, and answer 2xx quickly.
The body is {"event", "sent_at", "data"}. X-Songmora-Event names the event and X-Songmora-Delivery is the job id – the same on every retry, so you can ignore a delivery you already handled.
When your server does not answer 2xx, we try again after 1, 5 minutes (3 tries in all).
# The headers of every webhook call:
Content-Type: application/json
X-Songmora-Event: song.completed
X-Songmora-Delivery: 9b1f0c3e-6d2a-4f5b-8c71-2e4a9d0b7f13
X-Songmora-Signature: sha256=<hex HMAC-SHA256 of the raw body>
# The body:
{"event": "song.completed", "sent_at": "2026-11-07T14:05:09-05:00", "data": { …the Song status JSON… }} <?php
$raw = file_get_contents('php://input');
$expected = 'sha256=' . hash_hmac('sha256', $raw, getenv('SONGMORA_WEBHOOK_SECRET'));
if (! hash_equals($expected, $_SERVER['HTTP_X_SONGMORA_SIGNATURE'] ?? '')) {
http_response_code(401);
exit;
}
$event = json_decode($raw, true); // ['event' => 'song.completed', 'data' => [...]]
http_response_code(200); import crypto from 'node:crypto';
import express from 'express';
const app = express();
app.post('/hooks/songs', express.raw({ type: 'application/json' }), (req, res) => {
const expected = 'sha256=' + crypto.createHmac('sha256', process.env.SONGMORA_WEBHOOK_SECRET).update(req.body).digest('hex');
const given = req.get('X-Songmora-Signature') || '';
if (given.length !== expected.length || !crypto.timingSafeEqual(Buffer.from(given), Buffer.from(expected))) return res.sendStatus(401);
const event = JSON.parse(req.body); // { event: 'song.completed', data: {...} }
res.sendStatus(200);
}); import hashlib, hmac, os
from flask import Flask, request, abort
app = Flask(__name__)
@app.post("/hooks/songs")
def songs_hook():
raw = request.get_data()
expected = "sha256=" + hmac.new(os.environ["SONGMORA_WEBHOOK_SECRET"].encode(), raw, hashlib.sha256).hexdigest()
if not hmac.compare_digest(expected, request.headers.get("X-Songmora-Signature", "")):
abort(401)
event = request.get_json() # {"event": "song.completed", "data": {...}}
return "", 200 /api/v1/creditsCredits and prices
Your credit balance, your plan and the API price list (credits per song length and quality, and per lyric draft). Free to call.
curl https://ohang.tj/api/v1/credits \
-H "Authorization: Bearer $SONGMORA_KEY" \
-H "Accept: application/json" <?php
$ch = curl_init('https://ohang.tj/api/v1/credits');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('SONGMORA_KEY'),
'Accept: application/json',
],
]);
$data = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE); const res = await fetch('https://ohang.tj/api/v1/credits', {
headers: {
'Authorization': `Bearer ${process.env.SONGMORA_KEY}`,
'Accept': 'application/json',
},
});
const data = await res.json(); import os
import requests
res = requests.get(
"https://ohang.tj/api/v1/credits",
headers={"Authorization": f"Bearer {os.environ['SONGMORA_KEY']}", "Accept": "application/json"},
)
data = res.json() {
"credits": 772,
"plan": {
"slug": "pro",
"name": "Pro",
"max_seconds": 240
},
"prices": {
"lyrics": 0,
"songs": {
"standard": {
"30": 2,
"60": 3,
"150": 4,
"240": 6
},
"hd": {
"30": 5,
"60": 7,
"150": 10,
"240": 14
}
}
}
}/api/v1/lyricsWrite lyrics
Writes song lyrics with verse, chorus and bridge for an idea. Answers right away with the title and the lyrics.
| Field | Type | Description |
|---|---|---|
prompt required | string | What the song is about (up to 600 characters). |
genre | string | Genre slug.poplofihiphopedmacousticworshipcinematicrock |
language | string | Language of the lyrics. Default: English.ТоҷикӣРусскийO‘zbekEnglish |
voice | string | Who sings it.femalemaleduetinstrumental |
title | string | A title to start from (up to 120 characters). |
curl -X POST https://ohang.tj/api/v1/lyrics \
-H "Authorization: Bearer $SONGMORA_KEY" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
"prompt": "Город спит, а я снова думаю о тебе",
"genre": "pop",
"language": "English",
"voice": "female"
}' <?php
$ch = curl_init('https://ohang.tj/api/v1/lyrics');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('SONGMORA_KEY'),
'Accept: application/json',
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'prompt' => 'Город спит, а я снова думаю о тебе',
'genre' => 'pop',
'language' => 'English',
'voice' => 'female',
]),
]);
$data = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE); const res = await fetch('https://ohang.tj/api/v1/lyrics', {
method: 'POST',
headers: {
'Authorization': `Bearer ${process.env.SONGMORA_KEY}`,
'Accept': 'application/json',
'Content-Type': 'application/json',
},
body: JSON.stringify({
"prompt": "Город спит, а я снова думаю о тебе",
"genre": "pop",
"language": "English",
"voice": "female"
}),
});
const data = await res.json(); import os
import requests
res = requests.post(
"https://ohang.tj/api/v1/lyrics",
headers={"Authorization": f"Bearer {os.environ['SONGMORA_KEY']}", "Accept": "application/json"},
json={
"prompt": "Город спит, а я снова думаю о тебе",
"genre": "pop",
"language": "English",
"voice": "female",
},
)
data = res.json() {
"id": "4c2d8e61-0b7a-4f39-9e5d-7a1c3b2f6e08",
"type": "lyrics",
"status": "done",
"title": "Neon Hearts",
"lyrics": "[Verse 1]\nCity lights are spelling out your name\n\n[Chorus]\nNeon hearts, we're burning bright",
"language": "English",
"genre": "pop",
"credits": 0
}/api/v1/songsCreate a song
Starts a song in the background and answers 202 with the job (and its address in the Location header). The credits are reserved now, charged when the song is ready and given back if it fails. Poll the job or pass a webhook_url.
Send an Idempotency-Key header (any text up to 80 characters) to retry safely: the same key never starts or charges a second song – you get the first job back (200). While the first request with that key is still being handled, a second one answers 409.
| Field | Type | Description |
|---|---|---|
genre required | string | Genre slug.poplofihiphopedmacousticworshipcinematicrock |
lyrics | string | The words to sing (up to 3000 characters). Required unless voice is instrumental. |
title | string | Song title. Default: the first line of the lyrics. |
voice | string | Default: the genre’s voice.femalemaleduetinstrumental |
quality | string | hd needs a plan with HD quality. Default: standard.standardhd |
seconds | integer | Length in seconds; it is rounded up to the next length tier. Default: 150.3060150240 |
visibility | string | private needs a plan with private songs. Default: public.publicprivate |
prompt | string | A short description of the sound, sent to the music engine with the genre style. |
language | string | Language of the lyrics. |
webhook_url | string | HTTPS address we call when the song is ready or has failed (signed, see Webhooks). |
curl -X POST https://ohang.tj/api/v1/songs \
-H "Authorization: Bearer $SONGMORA_KEY" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
"genre": "pop",
"title": "Neon Hearts",
"lyrics": "[Verse 1]\nCity lights are spelling out your name\n\n[Chorus]\nNeon hearts, we'\''re burning bright",
"voice": "female",
"quality": "standard",
"seconds": 150,
"webhook_url": "https://example.com/hooks/songs"
}' <?php
$ch = curl_init('https://ohang.tj/api/v1/songs');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('SONGMORA_KEY'),
'Accept: application/json',
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'genre' => 'pop',
'title' => 'Neon Hearts',
'lyrics' => '[Verse 1]
City lights are spelling out your name
[Chorus]
Neon hearts, we\'re burning bright',
'voice' => 'female',
'quality' => 'standard',
'seconds' => 150,
'webhook_url' => 'https://example.com/hooks/songs',
]),
]);
$data = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE); const res = await fetch('https://ohang.tj/api/v1/songs', {
method: 'POST',
headers: {
'Authorization': `Bearer ${process.env.SONGMORA_KEY}`,
'Accept': 'application/json',
'Content-Type': 'application/json',
},
body: JSON.stringify({
"genre": "pop",
"title": "Neon Hearts",
"lyrics": "[Verse 1]\nCity lights are spelling out your name\n\n[Chorus]\nNeon hearts, we're burning bright",
"voice": "female",
"quality": "standard",
"seconds": 150,
"webhook_url": "https://example.com/hooks/songs"
}),
});
const data = await res.json(); import os
import requests
res = requests.post(
"https://ohang.tj/api/v1/songs",
headers={"Authorization": f"Bearer {os.environ['SONGMORA_KEY']}", "Accept": "application/json"},
json={
"genre": "pop",
"title": "Neon Hearts",
"lyrics": "[Verse 1]\nCity lights are spelling out your name\n\n[Chorus]\nNeon hearts, we're burning bright",
"voice": "female",
"quality": "standard",
"seconds": 150,
"webhook_url": "https://example.com/hooks/songs",
},
)
data = res.json() {
"id": "9b1f0c3e-6d2a-4f5b-8c71-2e4a9d0b7f13",
"type": "song",
"status": "queued",
"progress": 0,
"credits": 4,
"error": null,
"song": null
}/api/v1/songs/{id}Song status
The job you got from Create a song: status is queued, running, waiting, done or failed. While it runs, poll_after says how many seconds to wait; when it is done, song holds the takes with their audio links.
| Field | Type | Description |
|---|---|---|
id required | string | The job id (in the path) – the id from Create a song, also in its Location header. |
curl https://ohang.tj/api/v1/songs/9b1f0c3e-6d2a-4f5b-8c71-2e4a9d0b7f13 \
-H "Authorization: Bearer $SONGMORA_KEY" \
-H "Accept: application/json" <?php
$ch = curl_init('https://ohang.tj/api/v1/songs/9b1f0c3e-6d2a-4f5b-8c71-2e4a9d0b7f13');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('SONGMORA_KEY'),
'Accept: application/json',
],
]);
$data = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE); const res = await fetch('https://ohang.tj/api/v1/songs/9b1f0c3e-6d2a-4f5b-8c71-2e4a9d0b7f13', {
headers: {
'Authorization': `Bearer ${process.env.SONGMORA_KEY}`,
'Accept': 'application/json',
},
});
const data = await res.json(); import os
import requests
res = requests.get(
"https://ohang.tj/api/v1/songs/9b1f0c3e-6d2a-4f5b-8c71-2e4a9d0b7f13",
headers={"Authorization": f"Bearer {os.environ['SONGMORA_KEY']}", "Accept": "application/json"},
)
data = res.json() {
"id": "9b1f0c3e-6d2a-4f5b-8c71-2e4a9d0b7f13",
"type": "song",
"status": "done",
"progress": 100,
"credits": 4,
"error": null,
"song": {
"slug": "neon-hearts-x8f2",
"title": "Neon Hearts",
"url": "https://ohang.tj/song/neon-hearts-x8f2",
"duration": 150,
"visibility": "public",
"takes": [
{
"id": 101,
"take": 1,
"duration": 150,
"audio": "https://ohang.tj/song/neon-hearts-x8f2/audio/101.mp3"
},
{
"id": 102,
"take": 2,
"duration": 150,
"audio": "https://ohang.tj/song/neon-hearts-x8f2/audio/102.mp3"
}
]
},
"poll_after": null
}/api/v1/songsList your songs
Your songs, newest first, with their pages and takes. WAV links appear only when a WAV file exists.
| Field | Type | Description |
|---|---|---|
page | integer | Page number (query string). Default: 1. |
per_page | integer | Songs per page, at most 50 (query string). Default: 20. |
curl https://ohang.tj/api/v1/songs?per_page=20 \
-H "Authorization: Bearer $SONGMORA_KEY" \
-H "Accept: application/json" <?php
$ch = curl_init('https://ohang.tj/api/v1/songs?per_page=20');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('SONGMORA_KEY'),
'Accept: application/json',
],
]);
$data = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE); const res = await fetch('https://ohang.tj/api/v1/songs?per_page=20', {
headers: {
'Authorization': `Bearer ${process.env.SONGMORA_KEY}`,
'Accept': 'application/json',
},
});
const data = await res.json(); import os
import requests
res = requests.get(
"https://ohang.tj/api/v1/songs?per_page=20",
headers={"Authorization": f"Bearer {os.environ['SONGMORA_KEY']}", "Accept": "application/json"},
)
data = res.json() {
"data": [
{
"slug": "neon-hearts-x8f2",
"title": "Neon Hearts",
"genre": "pop",
"voice": "female",
"quality": "standard",
"duration": 150,
"visibility": "public",
"source": "api",
"url": "https://ohang.tj/song/neon-hearts-x8f2",
"created_at": "2026-11-20T07:00:00+05:00",
"takes": [
{
"id": 101,
"take": 1,
"duration": 150,
"audio": "https://ohang.tj/song/neon-hearts-x8f2/audio/101.mp3",
"wav": null
},
{
"id": 102,
"take": 2,
"duration": 150,
"audio": "https://ohang.tj/song/neon-hearts-x8f2/audio/102.mp3",
"wav": null
}
]
}
],
"meta": {
"page": 1,
"per_page": 20,
"total": 1,
"last_page": 1
}
}