HanoLab API

openapi: 3.1.0
info:
  title: HanoLab API
  version: '2026-11-11'
  description: 'GENERATED FROM DOCUMENTATION by API Evangelist on 2026-11-11: 9 operation(s) read from 1 public documentation page(s) (each operation
    names its page in x-source). This is not the provider''s published contract; HanoLab has published no machine-readable contract that the pipeline
    could find. Engine: local.'
  x-evidence-tiers:
    code-example: 0
    documentation: 9
    pages-with-code: 0
    pages-read: 1
  x-generated-from: documentation
  x-provenance: generated
  x-authored-by: API Evangelist
  x-generated: '2026-11-11'
  x-generator: generate-contract-from-docs.py
  x-engine: local
  x-sources:
  - https://hanolab.com/api-reference
paths:
  /api/v1/agent/estimate:
    post:
      operationId: post_api_v1_agent_estimate
      tags:
      - Api
      summary: Get the current voice‑conversion credit estimate before submission.
      description: Supply measured audio duration in seconds.
      x-source: https://hanolab.com/api-reference
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiV1AgentEstimateRequest'
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/v1/audio/separate:
    post:
      operationId: post_api_v1_audio_separate
      tags:
      - Api
      summary: Stem separation.
      description: Splits any audio into vocals + accompaniment (2‑stem), drums/bass/vocals/other (4‑stem), or 6‑stem with piano and guitar isolated.
      x-source: https://hanolab.com/api-reference
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiV1AudioSeparateRequest'
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/v1/music/generate:
    post:
      operationId: post_api_v1_music_generate
      tags:
      - Api
      summary: Generate a song.
      description: Pick a quality tier, supply a prompt and optional lyrics, get a full track.
      x-source: https://hanolab.com/api-reference
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiV1MusicGenerateRequest'
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/v1/tasks/{id}:
    get:
      operationId: get_api_v1_tasks_id
      tags:
      - Api
      summary: Get task status and output URLs.
      description: Poll this endpoint until status is "completed", then read output_urls.
      x-source: https://hanolab.com/api-reference
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetApiV1TasksIdResponse'
      x-evidence:
        kind: documentation
  /api/v1/upload:
    post:
      operationId: post_api_v1_upload
      tags:
      - Api
      summary: Create an upload URL for a local file.
      description: 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.
      x-source: https://hanolab.com/api-reference
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiV1UploadRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostApiV1UploadResponse'
      x-evidence:
        kind: documentation
  /api/v1/upload/complete:
    post:
      operationId: post_api_v1_upload_complete
      tags:
      - Api
      summary: Confirm your own uploaded object.
      description: Returns audio_sha256 and a download URL. Use the stable owned object key as input_url for conversion.
      x-source: https://hanolab.com/api-reference
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiV1UploadCompleteRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostApiV1UploadCompleteResponse'
      x-evidence:
        kind: documentation
  /api/v1/voice/convert:
    post:
      operationId: post_api_v1_voice_convert
      tags:
      - Api
      summary: Pro voice conversion.
      description: Submit a vocal and convert it through a trained voice model. Optionally separates stems first and mixes the converted vocal
        back with the instrumental.
      x-source: https://hanolab.com/api-reference
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiV1VoiceConvertRequest'
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/v1/voice/convert-flash:
    post:
      operationId: post_api_v1_voice_convert_flash
      tags:
      - Api
      summary: Flash voice conversion.
      description: Lower‑latency zero‑shot conversion using a reference clip embedding.
      x-source: https://hanolab.com/api-reference
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiV1VoiceConvertFlashRequest'
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/v1/voice/models:
    get:
      operationId: get_api_v1_voice_models
      tags:
      - Api
      summary: List your voice models.
      description: 'Returns { items: [...] } where each item carries the `id` you pass as voice_model_id to /voice/convert and /voice/convert-flash.'
      x-source: https://hanolab.com/api-reference
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetApiV1VoiceModelsResponse'
      x-evidence:
        kind: documentation
components:
  schemas:
    PostApiV1AgentEstimateRequest:
      type: object
      properties:
        duration:
          type: integer
          description: Measured audio duration in seconds.
      required:
      - duration
    PostApiV1AudioSeparateRequest:
      type: object
      properties:
        input_url:
          type: string
          description: URL of the audio to separate.
        mode:
          type: string
          description: Separation mode (e.g., "2stem", "4stem", "6stem").
      required:
      - input_url
      - mode
    PostApiV1MusicGenerateRequest:
      type: object
      properties:
        tier:
          type: string
          description: Quality tier (draft / studio / signature / maestro).
        prompt:
          type: string
          description: Prompt describing the desired music.
        lyrics:
          type: string
          description: Optional lyrics.
        duration:
          type: integer
          description: Desired length of the track in seconds.
      required:
      - tier
      - prompt
      - duration
    GetApiV1TasksIdResponse:
      type: object
      properties:
        status:
          type: string
          description: Task status (e.g., completed, failed).
        output_urls:
          type: object
          description: URLs to the resulting files.
    PostApiV1UploadRequest:
      type: object
      properties:
        filename:
          type: string
          description: Name of the file to upload.
        content_type:
          type: string
          description: MIME type of the file.
        size:
          type: integer
          description: Size of the file in bytes.
      required:
      - filename
      - content_type
      - size
    PostApiV1UploadResponse:
      type: object
      properties:
        upload_url:
          type: string
          description: URL to which the file should be PUT.
        key:
          type: string
          description: Object key to be used with /upload/complete.
    PostApiV1UploadCompleteRequest:
      type: object
      properties:
        key:
          type: string
          description: User‑provided object key, e.g., "YOUR_USER_ID/uploaded-object.wav".
      required:
      - key
    PostApiV1UploadCompleteResponse:
      type: object
      properties:
        audio_sha256:
          type: string
          description: SHA‑256 hash of the uploaded audio.
        download_url:
          type: string
          description: URL to download the uploaded file.
    PostApiV1VoiceConvertRequest:
      type: object
      properties:
        input_url:
          type: string
          description: URL of the source audio.
        voice_model_id:
          type: string
          description: ID of the voice model to use.
        duration:
          type: integer
          description: Duration of the audio in seconds.
        pitch_shift:
          type: number
          description: Pitch shift amount.
        index_rate:
          type: number
          description: Index rate.
        filter_radius:
          type: integer
          description: Filter radius.
        rms_mix_rate:
          type: number
          description: RMS mix rate.
        protect:
          type: number
          description: Protection factor.
        full_song:
          type: boolean
          description: Whether to process the full song.
      required:
      - input_url
      - voice_model_id
      - duration
    PostApiV1VoiceConvertFlashRequest:
      type: object
      properties:
        input_url:
          type: string
          description: URL of the source audio.
        voice_model_id:
          type: string
          description: ID of the voice model to use.
        duration:
          type: integer
          description: Duration of the audio in seconds.
      required:
      - input_url
      - voice_model_id
      - duration
    GetApiV1VoiceModelsResponse:
      type: object
      properties:
        items:
          type: array
          description: Array of voice model objects, each containing an `id`.
tags:
- name: Api