Developer API

API reference

The HanoLab REST API lets you integrate music generation, voice conversion, stem separation, and mastering into your own product. Available on Creator and Pro plans.

Base URL

https://hanolab.com

Authentication

All requests must include a bearer token. Generate a key from your account dashboard.

Authorization: Bearer hnl_live_xxxxxxxxxxxx

Async job pattern

Generation endpoints are asynchronous. A successful submission returns a task ID. Poll /api/v1/tasks/[id] or receive a webhook callback until status is completed, then read output_urls.

Endpoints

POST/api/v1/music/generate

Submit a text-to-music or lyrics-to-song generation job.

{
  "prompt": "cinematic synthwave, 120 bpm",
  "lyrics": "",
  "duration": 30,
  "guidance": 7.5,
  "seed": null,
  "style_model_id": null
}

POST/api/v1/voice/convert

Convert the vocal of an audio file using a target voice model.

{
  "audio_url": "https://cdn.hanolab.com/inputs/xxx.wav",
  "voice_model_id": "vm_123",
  "pitch_shift": 0,
  "protect": 0.33
}

POST/api/v1/voice/clone

Train a lightweight voice model from a reference clip.

{
  "reference_url": "https://cdn.hanolab.com/inputs/ref.wav",
  "name": "My Voice",
  "epochs": 100
}

POST/api/v1/toolkit/separate

Separate vocals, drums, bass, and other instruments.

{
  "audio_url": "https://cdn.hanolab.com/inputs/song.mp3",
  "stems": ["vocals", "drums", "bass", "other"]
}

POST/api/v1/toolkit/master

Reference-based mastering — match loudness and tone to a target.

{
  "target_url": "https://cdn.hanolab.com/inputs/target.wav",
  "reference_url": "https://cdn.hanolab.com/inputs/reference.wav"
}

GET/api/v1/tasks/[id]

Get task status and output URLs once complete.

POST/api/webhook/runpod

Receive a push callback from HanoLab when a task completes.

Billing & limits

The API is billed separately from your workstation subscription on a pay-per-call basis. Each call deducts from a prepaid balance you top up from your account dashboard. See pricing for per-endpoint rates.

Creator: API unlocked · 5 concurrent jobs · standard rates
Pro: API unlocked · 20 concurrent jobs · 20% volume discount on every call
Enterprise: custom concurrency, SLA, and volume pricing — contact sales

Errors

The API returns standard HTTP status codes. Error responses are JSON:

{
  "error": "insufficient_credits",
  "message": "Your plan does not have enough credits.",
  "status": 402
}

Ready to build?

Upgrade to a plan with API access and start integrating HanoLab into your workflow.

View plans →