Skip to main content
When you submit a task to the lyrics generation API, you can use the callBackUrl parameter to set a callback URL. When the task is completed, the system will automatically push the results to your specified address.

Callback Mechanism Overview

The callback mechanism eliminates the need to poll the API for task status. The system will proactively push task completion results to your server.

Callback Timing

The system will send callback notifications in the following situations:
  • Lyrics generation completed (complete stage)
  • Lyrics generation task failed
  • Error occurred during task processing
Unlike music generation, lyrics generation has only one callback stage: complete (generation finished)

Callback Method

  • HTTP Method: POST
  • Content Type: application/json
  • Timeout: 15 seconds

Callback Request Format

When the task is completed, the system will send a POST request to your callBackUrl in the following format:
{
  "code": 200,
  "msg": "All generated successfully.",
  "data": {
    "callbackType": "complete",
    "taskId": "11dc****8b0f",
    "data": [
      {
        "text": "[Verse]\nI cross the city's darkest night\nWith burning dreams inside my heart",
        "title": "Iron Man",
        "status": "complete",
        "errorMessage": ""
      },
      {
        "text": "[Verse]\nThe wind is calling out my name\nSteel armor gleaming in the light",
        "title": "Iron Man",
        "status": "complete",
        "errorMessage": ""
      }
    ]
  }
}

Status Code Description

code
integer
required
Callback status code indicating task processing result:
Status CodeDescription
200Success - Lyrics generation completed
400Bad Request - Parameter error or content violation
401Unauthorized - Invalid API key
413Content Too Long - Prompt exceeds limit
429Insufficient Credits - Account credit balance insufficient
500Server Error - Please retry later
msg
string
required
Status message providing detailed status description
data.callbackType
string
required
Callback type, fixed as complete for lyrics generation
data.taskId
string
required
Task ID, consistent with the taskId returned when you submitted the task
data.data
array
required
Generated lyrics list
data.data[].text
string
Lyrics content with verse/chorus structure
data.data[].title
string
Lyrics title
data.data[].status
string
Generation status: complete or failed
data.data[].errorMessage
string
Error message, valid when status is failed

Callback Reception Examples

Here are example codes for receiving callbacks in various popular programming languages:
  • Node.js
  • Python
  • PHP
const express = require('express');
const app = express();

app.use(express.json());

app.post('/lyrics-callback', (req, res) => {
  const { code, msg, data } = req.body;
  
  console.log('Received lyrics generation callback:', {
    taskId: data.taskId,
    callbackType: data.callbackType,
    status: code,
    message: msg
  });
  
  if (code === 200 && data.callbackType === 'complete') {
    // Lyrics generation successful
    console.log(`Generated ${data.data.length} lyrics variants:`);
    
    data.data.forEach((lyrics, index) => {
      if (lyrics.status === 'complete') {
        console.log(`\nLyrics ${index + 1}:`);
        console.log(`Title: ${lyrics.title}`);
        console.log(`Content:\n${lyrics.text}`);
        
        // Process lyrics data
        // Can save to database, format for display, etc.
        saveLyricsToDatabase(lyrics);
      } else {
        console.log(`Lyrics ${index + 1} failed: ${lyrics.errorMessage}`);
      }
    });
    
  } else {
    // Task failed
    console.log('Lyrics generation failed:', msg);
    
    // Handle failure cases...
    if (code === 400) {
      console.log('Parameter error or content violation');
    } else if (code === 429) {
      console.log('Insufficient credits');
    } else if (code === 500) {
      console.log('Server internal error');
    }
  }
  
  // Return 200 status code to confirm callback received
  res.status(200).json({ status: 'received' });
});

function saveLyricsToDatabase(lyrics) {
  // Example function to save lyrics to database
  console.log(`Saving lyrics: ${lyrics.title}`);
  // Your database logic here
}

app.listen(3000, () => {
  console.log('Lyrics callback server running on port 3000');
});

Best Practices

Lyrics Processing Recommendations

  1. Content Filtering: Implement content filtering to ensure lyrics meet your platform’s guidelines
  2. Format Preservation: Maintain the verse/chorus structure when processing lyrics
  3. Version Management: Keep track of different lyrics variants for the same prompt
  4. Metadata Storage: Store lyrics along with relevant metadata (title, theme, style)
  5. Text Processing: Consider text processing for formatting, spell checking, or translation
  6. Copyright Compliance: Ensure generated lyrics comply with copyright regulations

Lyrics-Specific Considerations

  • Lyrics may contain creative variations that require human review
  • Generated content should be checked for appropriateness before publication
  • Multiple variants allow for selection of the best option
  • Lyrics generation is typically faster than music generation
  • Content moderation is important for user-generated lyrics prompts

Troubleshooting

Common issues specific to lyrics generation callbacks:
  • Review the prompt for clarity and specificity
  • Check if the generated lyrics match the intended theme
  • Verify that lyrics follow a logical song structure
  • Consider regenerating if quality doesn’t meet expectations
  • Ensure the prompt clearly specifies the desired language
  • Check for style consistency across verses and choruses
  • Verify that the tone matches the intended mood
  • Consider more specific prompts for better style control
  • Implement content filtering for generated lyrics
  • Check for potentially inappropriate content
  • Verify compliance with platform guidelines
  • Consider human review for sensitive topics

Alternative Solutions

If you cannot use the callback mechanism, you can also use polling:

Poll Lyrics Results

Use the Get Lyrics Generation Details interface to regularly query task status. Recommend querying every 15 seconds for lyrics.