Instant Voice Clone API

Submit Task

Method: POST
Path: /v1/instant_voice_clone/task/submit
Headers: Topview-Uid, Authorization

Request

{
  "model": "Index TTS",
  "text": "Hello, welcome to Topview.",
  "referenceAudioFileId": "file_abc123",
  "emotionMode": "slider",
  "emotionVector": "0.2,0.8,0.1",
  "boardId": "board_xxx",
  "noticeUrl": "https://example.com/topview/callback"
}

Parameters

Field	Type	Required	Description
`model`	String	Yes	Model name: `Index TTS` / `Fish Audio S2 Pro`
`text`	String	Yes	Voice script text
`referenceAudioFileId`	String	Yes	Reference audio fileId (must be wav)
`emotionMode`	String	No	Emotion mode: `slider` / `prompt` (supported by Index TTS only)
`emotionVector`	String	Conditional	Required when `emotionMode=slider`
`emotionText`	String	Conditional	Required when `emotionMode=prompt`
`boardId`	String	No	Board ID
`noticeUrl`	String	No	Task completion callback URL

Note: Fish Audio S2 Pro does not support emotion params. Sending them will cause validation errors.

Response

{
  "code": "200",
  "message": "Success",
  "result": {
    "taskId": "a1b2c3d4e5",
    "status": "success",
    "boardId": "board_xxx"
  }
}

Query Task

Method: GET
Path: /v1/instant_voice_clone/task/query
Headers: Topview-Uid, Authorization

Query Parameters

Parameter	Type	Required	Description
`taskId`	String	Yes	Task ID returned by submit API
`needCloudFrontUrl`	Boolean	No	Whether to return CloudFront URLs, default `false`

Response

{
  "code": "200",
  "message": "Success",
  "result": {
    "taskId": "a1b2c3d4e5",
    "status": "success",
    "costCredit": 1.2,
    "model": "Index TTS",
    "text": "Hello, welcome to Topview.",
    "outputAudio": {
      "fileId": "file_out_123",
      "url": "https://cdn.example.com/audio.mp3",
      "duration": 8.436,
      "format": "mp3"
    }
  }
}

Status Enum

Status	Meaning
`init`	Submitted, waiting for processing
`running`	Processing (unfinished tasks are normalized to running)
`success`	Completed successfully
`fail`	Failed (check `errorMsg`)

Credit Charging

1) Pricing rule

Charging is based on input text length (text).
Formula: costCredit = ceil(textLength * 0.000667, 2)
(rounded up to 2 decimals)
Examples:
- textLength = 100 -> costCredit = 0.07
- textLength = 1500 -> costCredit = 1.01

2) Charge / refund timing

Credit is pre-deducted after task acceptance.
Final status success: charged amount is kept.
Final status fail: credit for this task is automatically refunded.

3) How to read the final charged amount

Use result.costCredit from the query API.
For unfinished tasks (init / running), costCredit may not be final yet.
Read costCredit after terminal status (success / fail) for the final billing value.