HanoLab
Developer API

API reference

Call HanoLab voice conversion and stem separation from your own scripts, apps, and pipelines. Available on Starter, 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

CLI & assistant skill

For local files, install the CLI and skill to handle upload, estimates, conversion, polling and downloads. Conversion requests support an Idempotency-Key header (16–128 letters, digits, underscores or hyphens). Reuse the same key and body after interruption; a changed body returns 409. X-Hanolab-Max-Credits caps the charge before submission. Include a positive measured duration with either header.

Plan & billing

API access is included on the Starter, 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: No API access. Key generation returns HTTP 403.
  • Starter: API enabled · 300 credits / month included.
  • 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/upload

Create an upload URL for a local file. PUT the file to upload_url without your API key, then confirm the returned key with /api/v1/upload/complete. Audio and MP4 are capped at 100 MiB.

{ "filename": "song.wav", "content_type": "audio/wav", "size": 16044 }
POST/api/v1/upload/complete

Confirm your own uploaded object. Returns audio_sha256 and a download URL. Use the stable owned object key as input_url for conversion.

{ "key": "YOUR_USER_ID/uploaded-object.wav" }
POST/api/v1/agent/estimate

Get the current voice-conversion credit estimate before submission. Supply measured audio duration in seconds.

{ "duration": 61 }
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. 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 plan; API access requires Starter or higher.
  • 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 Starter, Creator and Pro plans.

Get a key →See plans