Developer API

API reference

Call HanoLab voice conversion and stem separation from your own scripts, apps, and pipelines. Available on Creator and Pro plans — calls are billed against your monthly credits at the same rate as in-app use.

Base URL

https://hanolab.com

Authentication

All requests must include a bearer token. Generate a key from your account settings. The full key is shown exactly once at creation — copy it immediately. The API key value is yours to keep secret; HanoLab never sees it after creation (we store only its SHA-256 hash).

Authorization: Bearer hnl_live_xxxxxxxxxxxx

Plan & billing

API access is included on the Creator and Pro plans. Calls deduct from the same monthly credit balance you use for in-app actions, at identical per-action rates (see pricing). When the balance hits zero, calls return HTTP 402 until the next monthly reset or a credit top-up.

Free / Starter: No API access. Key generation returns HTTP 403.
Creator: API enabled · 800 credits / month included.
Pro: API enabled · 1,800 credits / month · priority queue.

Async job pattern

Submission endpoints are asynchronous and return HTTP 202 with a task object. Poll GET /api/v1/tasks/{id} until status is completed or failed, then read output_urls. Recommended polling cadence is every 2–5 seconds. Webhooks are not yet supported.

Endpoints

POST/api/v1/music/generate

Generate a song. Pick a quality tier (draft / studio / signature / maestro), supply a prompt and optional lyrics, get a full track. API callers are capped at 1 in-flight + 10 per rolling hour per key — the upstream model has fixed concurrency shared with in-app users.

{
  "tier": "studio",
  "prompt": "cinematic synthwave, melancholic, 120 bpm",
  "lyrics": "verse 1: ...",
  "duration": 30
}

POST/api/v1/voice/convert

Pro voice conversion (RVC). Submit a vocal and convert it through a trained voice model. Optionally separates stems first and mixes the converted vocal back with the instrumental in one call.

{
  "input_url": "https://cdn.hanolab.com/uploads/abc.wav",
  "voice_model_id": "vm_xxx",
  "duration": 30,
  "pitch_shift": 0,
  "index_rate": 0.75,
  "filter_radius": 3,
  "rms_mix_rate": 0.25,
  "protect": 0.33,
  "full_song": false
}

POST/api/v1/voice/convert-flash

Flash voice conversion. Lower-latency zero-shot conversion using a reference clip embedding. Same async pattern, no model training required.

{
  "input_url": "https://cdn.hanolab.com/uploads/abc.wav",
  "voice_model_id": "vm_xxx",
  "duration": 30
}

POST/api/v1/audio/separate

Stem separation. Splits any audio into vocals + accompaniment (2-stem), drums/bass/vocals/other (4-stem), or 6-stem with piano and guitar isolated.

{
  "input_url": "https://cdn.hanolab.com/uploads/abc.wav",
  "mode": "2stem"
}

GET/api/v1/voice/models

List your voice models. Returns { items: [...] } where each item carries the `id` you pass as voice_model_id to /voice/convert and /voice/convert-flash.

GET/api/v1/tasks/{id}

Get task status and output URLs. Poll this endpoint until status is "completed", then read output_urls.

Errors

All errors return JSON with a top-level error field. Common status codes:

401 Unauthorized — missing, malformed, or revoked bearer token.
403 plan_tier_required — Free or Starter plan; upgrade to Creator or Pro.
400 — required fields missing or malformed input URL.
402 insufficient_credits — monthly balance exhausted; wait for the next reset or top up.
404 — task, voice model, or other referenced resource not found.
500 — internal error; safe to retry with backoff.

{
  "error": "insufficient_credits",
  "required": 10
}

Ready to build?

Generate a key from your account and start calling HanoLab from your own apps. API access is included on Creator and Pro plans.

Get a key →See plans