Topic Lyrics API

Overview

Use this API to generate two text outputs from a single topic:

• sound_prompt: a production-ready music prompt in English
• lyrics: lyrics matched to the topic and sound direction

This is a synchronous API. The server waits for generation to finish and then returns the result.

Billing:

• Each request costs $0.001
• Billing happens when the request starts

Base URL:

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

Authentication:

api-key: YOUR_API_KEY

1. Generate Topic Lyrics

POST /lyrics/task/wait
Content-Type: application/json
api-key: YOUR_API_KEY

Request body:

{
  "topic": "A lonely iPhone screen glowing in a quiet bedroom at 2 AM"
}

Field description:

Field	Type	Required	Description
topic	string	Yes	The idea, scene, mood, or concept you want to turn into a sound prompt and lyrics

Success Response

HTTP status:

200 OK

Response body:

{
  "task_id": "2f41e2a7-5c79-4d9c-9642-53732bde9fa5",
  "sound_prompt": "Late Night Lo-Fi Hip Hop, warm dusty 808 sub-bass, soft lo-fi piano chords, muted vinyl texture, intimate close-mic atmosphere, nostalgic tape warble, mellow and contemplative, 72 bpm",
  "lyrics": "[Verse]\nBlue light on my face in the middle of the night\n..."
}

Field description:

Field	Type	Description
task_id	string	The task identifier for later lookup
sound_prompt	string	The generated sound prompt
lyrics	string	The generated lyrics

Error Responses

Invalid request

HTTP status:

400 Bad Request

Example:

{
  "success": false,
  "error": {
    "name": "ZodError",
    "issues": [
      {
        "code": "too_small",
        "path": [
          "topic"
        ],
        "message": "String must contain at least 1 character(s)"
      }
    ]
  }
}

Unauthorized

HTTP status:

401 Unauthorized

Example:

{
  "message": "Unauthorized"
}

Insufficient balance or billing failure

HTTP status:

402 Payment Required

Example:

{
  "error": "Failed to deduct balance: Insufficient balance"
}

Generation failed

HTTP status:

502 Bad Gateway

Example:

{
  "task_id": "2f41e2a7-5c79-4d9c-9642-53732bde9fa5",
  "error": "lyrics generation failed: LLM returned empty content"
}

2. Query a Previous Task

GET /lyrics/task/:taskId
api-key: YOUR_API_KEY

Example:

GET /lyrics/task/2f41e2a7-5c79-4d9c-9642-53732bde9fa5
api-key: YOUR_API_KEY

Success Response

HTTP status:

200 OK

Response body:

{
  "task_id": "2f41e2a7-5c79-4d9c-9642-53732bde9fa5",
  "status": "completed",
  "gen_params": {
    "topic": "A lonely iPhone screen glowing in a quiet bedroom at 2 AM"
  },
  "data": {
    "sound_prompt": "Late Night Lo-Fi Hip Hop, warm dusty 808 sub-bass, soft lo-fi piano chords, muted vinyl texture, intimate close-mic atmosphere, nostalgic tape warble, mellow and contemplative, 72 bpm",
    "lyrics": "[Verse]\nBlue light on my face in the middle of the night\n..."
  },
  "error_message": null,
  "created_at": "2026-03-03T12:00:00.000Z",
  "updated_at": "2026-03-03T12:00:02.000Z"
}

Field description:

Field	Type	Description
task_id	string	Task identifier
status	string	Task status: processing, completed, or failed
gen_params	object	Original input parameters
data	object | null	Generated result when available
error_message	string | null	Failure reason when generation fails
created_at	string	Task creation time in ISO format
updated_at	string	Last update time in ISO format

Error Responses

Task not found

HTTP status:

404 Not Found

Example:

{
  "error": "Task not found"
}

Not authorized

HTTP status:

403 Forbidden

Example:

{
  "error": "Not authorized"
}

cURL Examples

Generate

curl -X POST "https://api.foxaihub.com/api/v2/lyrics/task/wait" \
  -H "Content-Type: application/json" \
  -H "api-key: YOUR_API_KEY" \
  -d '{
    "topic": "A lonely iPhone screen glowing in a quiet bedroom at 2 AM"
  }'

Query

curl "https://api.foxaihub.com/api/v2/lyrics/task/2f41e2a7-5c79-4d9c-9642-53732bde9fa5" \
  -H "api-key: YOUR_API_KEY"