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 yourcallBackUrl
in the following format:
Status Code Description
Callback status code indicating task processing result:
Status Code | Description |
---|---|
200 | Success - Lyrics generation completed |
400 | Bad Request - Parameter error or content violation |
401 | Unauthorized - Invalid API key |
413 | Content Too Long - Prompt exceeds limit |
429 | Insufficient Credits - Account credit balance insufficient |
500 | Server Error - Please retry later |
Status message providing detailed status description
Callback type, fixed as
complete
for lyrics generationTask ID, consistent with the taskId returned when you submitted the task
Generated lyrics list
Lyrics content with verse/chorus structure
Lyrics title
Generation status:
complete
or failed
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
Best Practices
Lyrics Processing Recommendations
- Content Filtering: Implement content filtering to ensure lyrics meet your platform’s guidelines
- Format Preservation: Maintain the verse/chorus structure when processing lyrics
- Version Management: Keep track of different lyrics variants for the same prompt
- Metadata Storage: Store lyrics along with relevant metadata (title, theme, style)
- Text Processing: Consider text processing for formatting, spell checking, or translation
- 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:Content Quality Issues
Content Quality Issues
- 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
Language and Style Problems
Language and Style Problems
- 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
Content Moderation
Content Moderation
- 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.