Music Generation

Billing Rules

$0.035 per request. The model is v4.5-all, and this is the only available model.

Basic Configuration

Base URL: https://api.foxaihub.com/api/v2

HTTP Headers

{
  "api-key": "Your API Key"
}

Submit Task

Endpoint: /music/task

Method: POST

Content-Type: application/json

The HTTP body allows different parameters to support different generation modes.

1. Description

{
    "topic": "a song about spring",
    "is_instrumental": true
}

Explanation: The topic field is a description of the song, and is_instrumental controls whether vocals are included.

2. Custom

{
    "tags": "female vocal, pop, dream pop",
    "lyrics": "[Verse 1]\nIn waves of starlit magic\nMy heart turns so tragic\nYou say you love another\nWhile my mind turns static\nTell me what you need\nAs thoughts turn sporadic\nThis love fades faster than the titanic\n\n[Chorus]\nI float through endless melodies\nPast echoes of \"I'm sorry\"\nI just want another last chance\n\n[Verse 2]\nIn this ethereal haze, why am I alone?\nI just wanna be loved, drift with someone to hold\nMemories shimmer bright when I called on the phone\nBut now the calls you answer are his and not my own\n\n[Chorus]\nI float through endless melodies\nLost in this sweet romance\nPast echoes of \"I'm sorry\"\nI just want another last chance"
}

Explanation: The tags field is used to describe the music tags. Note that this field is a string. The lyrics field contains the lyrics. If it is empty, it means there will be no vocals.

3. Extend

Coming soon.

Response

{
  "success": true,
  "task_id": "4f3acce5-eb32-46b4-9c96-9cc1e2b2c922"
}

task_id is the unique ID used to track this task.

Query Result

Path: /music/task?ids=

You must query at least 1 task result per request and can query up to 25 task results per request. Different task_id values should be separated by commas.

/task?ids=0196bd6d-57a4-7000-96c6-f74ee7998e5f,0196bd6d-acc0-7000-81ae-a56d8b0631b6

Method: GET

The HTTP response can be categorized into the following results based on the status.

1. processing

Indicates that the task is still being processed, and the data field does not yet contain valid data.

2. queued

The task has entered the generation queue.

[
{
  "status": "queued",
  "task_id": "5d23ace6-c7da-4429-a48d-b6d235c629ac",
  "gen_params": {
    "topic": "female vocal, pop, dream pop",
    "is_instrumental": true
  },
  "data": {
    "clip_ids": [
      "b5ced187-1e86-484c-b8a3-1eb9356d95ce",
      "c37ee650-349f-4bc3-9418-bf0e7587ea65"
    ]
  },
  "created_at": "2026-03-16T08:36:04.000Z",
  "updated_at": "2026-03-16T08:36:05.000Z"
}
]

3. streaming

The task returns an audio_url address that can be played as a stream, but the task has not been fully completed yet.

[
  {
    "status": "streaming",
    "task_id": "4f3acce5-eb32-46b4-9c96-9cc1e2b2c922",
    "gen_params": {
      "tags": "female vocal, pop, dream pop",
      "lyrics": "[Verse 1]\nIn waves"
    },
    "data": [
      {
        "id": "a7737313-9815-438d-920d-ff29d07d064c",
        "title": "",
        "handle": "zafs8qv",
        "status": "streaming",
        "user_id": "2dba1255-ebac-4e9b-a1d5-2b92d7a1fcb1",
        "has_hook": false,
        "is_liked": false,
        "metadata": {
          "tags": "female vocal, pop, dream pop",
          "task": "",
          "type": "gen",
          "prompt": "[Verse 1]\nIn waves ",
          "stream": true,
          "has_stem": false,
          "is_remix": false,
          "priority": 0,
          "can_remix": true,
          "is_mumble": false,
          "model_badges": {
            "songrow": {...},
          "make_instrumental": false,
          "uses_latest_model": false
        },
        "audio_url": "https://audiopipe.sonic.ai/?item_id=a7737313-9815-438d-920d-ff29d07d064c",
        "image_url": "https://cdn2.sonic.ai/image_a7737313-9815-438d-920d-ff29d07d064c.jpeg",
        "is_hidden": false,
        "is_public": false,
        "video_url": "",
        "created_at": "2026-03-16T08:06:47.787Z",
        "flag_count": 0,
        "is_trashed": false,
        "model_name": "chirp-auk",
        "play_count": 0,
        "batch_index": 0,
        "entity_type": "song_schema",
        "display_name": "zafs8qv",
        "upvote_count": 0,
        "comment_count": 0,
        "allow_comments": true,
        "image_large_url": "https://cdn2.sonic.ai/image_large_a7737313-9815-438d-920d-ff29d07d064c.jpeg",
        "is_contest_clip": false,
        "avatar_image_url": "https://cdn1.sonic.ai/sAura5.jpg",
        "is_handle_updated": false,
        "major_model_version": "v4.5-all",
        "is_following_creator": false
      },
      {...same structure as the previous item}
    ],
    "created_at": "2026-03-16T08:06:45.000Z",
    "updated_at": "2026-03-16T08:07:02.000Z"
  }
]

4. completed

The task has finished generating. The audio_url field can be used to download the final audio.

[
  {
    "status": "completed",
    "task_id": "4f3acce5-eb32-46b4-9c96-9cc1e2b2c922",
    "gen_params": {
      "tags": "female vocal, pop, dream pop",
      "lyrics": "[Verse 1]\nIn waves of ..."
    },
    "data": [
      {
        "status": "complete",
        "title": "",
        "play_count": 0,
        "upvote_count": 0,
        "allow_comments": true,
        "id": "a7737313-9815-438d-920d-ff29d07d064c",
        "entity_type": "song_schema",
        "video_url": "",
        "audio_url": "https://cdn1.sonic.ai/a7737313-9815-438d-920d-ff29d07d064c.mp3",
        "image_url": "https://cdn2.sonic.ai/image_a7737313-9815-438d-920d-ff29d07d064c.jpeg",
        "image_large_url": "https://cdn2.sonic.ai/image_large_a7737313-9815-438d-920d-ff29d07d064c.jpeg",
        "major_model_version": "v4.5-all",
        "model_name": "chirp-auk",
        "metadata": {
          "tags": "female vocal, pop, dream pop",
          "prompt": "[Verse 1]\nIn waves of ...",
          "type": "gen",
          "duration": 149,
          "refund_credits": false,
          "stream": true,
          "make_instrumental": false,
          "task": "",
          "can_remix": true,
          "is_remix": false,
          "priority": 0,
          "has_stem": false,
          "uses_latest_model": false,
          "model_badges": {
            "songrow": {...}
          },
          "is_mumble": false
        },
        "is_liked": false,
        "user_id": "2dba1255-ebac-4e9b-a1d5-2b92d7a1fcb1",
        "display_name": "zafs8qv",
        "handle": "zafs8qv",
        "is_handle_updated": false,
        "avatar_image_url": "https://cdn1.sonic.ai/sAura5.jpg",
        "is_trashed": false,
        "is_hidden": false,
        "created_at": "2026-03-16T08:06:47.787Z",
        "is_public": false,
        "is_following_creator": false,
        "explicit": false,
        "comment_count": 0,
        "flag_count": 0,
        "is_contest_clip": false,
        "has_hook": false,
        "batch_index": 0
      },
        {...same structure as the previous item}
]

5. failed

The task may ultimately fail due to a timeout or invalid parameters in the submitted task. The data field will provide the reason.

Development recommendation: Only focus on the streaming, completed, and failed statuses, and set a task timeout.

For example, from submission to receiving the result, a generation task usually takes no more than 6 minutes. Once this time threshold is exceeded, the task can be treated as failed to prevent infinite polling.

Advanced

If you need a webhook, I would also be happy to develop it, which can reduce the implementation workload for users.