OHANG.TJ
Developer API

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.

Get an API key

Getting started

  1. The API is part of the Pro, Studio plans. Choose one on the Pricing page.
  2. 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.
  3. Write lyrics, start a song, then poll its status (every 20 seconds is plenty) or let us call your webhook.
Base URLhttps://ohang.tj/api/v1

Send 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"

Credits & prices

API calls spend the same credit balance as the studio, at the same prices. Lyrics are free. A song costs:

LengthStandard standardHD hd
30 30 seconds2 credits5 credits
60 1 minute3 credits7 credits
150 2 min 30 s4 credits10 credits
240 4 minutes6 credits14 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).

PlanRequests per minuteSongs at the same time
Pro602
Studio1205

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.

StatusCodeMeaning
401invalid_keyThe key is missing, wrong or revoked.
402insufficient_creditsNot enough credits for this song or lyric draft. Buy credits or the next plan period.
403plan_without_apiYour plan does not include the API.
403account_inactiveThe account cannot use the API.
404not_foundNo such endpoint, or no job with this id on your account.
409request_in_progressA request with the same Idempotency-Key is still running.
422invalid_requestA field is missing or wrong – error.fields lists them.
422limit_reachedA plan limit: length, HD, private songs, lyric drafts a day or songs at the same time.
429rate_limitedToo many requests – wait for Retry-After seconds.
502provider_errorThe music or lyrics engine failed. Nothing was charged; try again.
503provider_errorNo lyrics engine is available right now. Nothing was charged; try again later.
503api_disabledThe API is switched off on this site for now.
500server_errorSomething 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… }}
GET/api/v1/credits

Credits 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"
Response 200
{
    "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
            }
        }
    }
}
POST/api/v1/lyrics

Write lyrics

Writes song lyrics with verse, chorus and bridge for an idea. Answers right away with the title and the lyrics.

FieldTypeDescription
prompt requiredstringWhat the song is about (up to 600 characters).
genrestringGenre slug.
poplofihiphopedmacousticworshipcinematicrock
languagestringLanguage of the lyrics. Default: English.
ТоҷикӣРусскийO‘zbekEnglish
voicestringWho sings it.
femalemaleduetinstrumental
titlestringA 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"
}'
Response 201
{
    "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
}
POST/api/v1/songs

Create 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.

FieldTypeDescription
genre requiredstringGenre slug.
poplofihiphopedmacousticworshipcinematicrock
lyricsstringThe words to sing (up to 3000 characters). Required unless voice is instrumental.
titlestringSong title. Default: the first line of the lyrics.
voicestringDefault: the genre’s voice.
femalemaleduetinstrumental
qualitystringhd needs a plan with HD quality. Default: standard.
standardhd
secondsintegerLength in seconds; it is rounded up to the next length tier. Default: 150.
3060150240
visibilitystringprivate needs a plan with private songs. Default: public.
publicprivate
promptstringA short description of the sound, sent to the music engine with the genre style.
languagestringLanguage of the lyrics.
webhook_urlstringHTTPS 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"
}'
Response 202
{
    "id": "9b1f0c3e-6d2a-4f5b-8c71-2e4a9d0b7f13",
    "type": "song",
    "status": "queued",
    "progress": 0,
    "credits": 4,
    "error": null,
    "song": null
}
GET/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.

FieldTypeDescription
id requiredstringThe 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"
Response 200
{
    "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
}
GET/api/v1/songs

List your songs

Your songs, newest first, with their pages and takes. WAV links appear only when a WAV file exists.

FieldTypeDescription
pageintegerPage number (query string). Default: 1.
per_pageintegerSongs 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"
Response 200
{
    "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
    }
}