# AI Music API

> REST API documentation for AI music generation, extension, cover workflows, lyric timing, task polling, and account credits.

## Core Links

- [Home](https://aimusicapi.org/): Product overview and entry point for the AI music API platform.
- [API Documentation](https://aimusicapi.org/docs): Endpoint directory with authentication, request fields, examples, polling, credit costs, and webhook behavior.
- [API Changelog](https://aimusicapi.org/docs/changelog): Dated public API changes with compatibility notes, integration impact, and links to updated endpoint documentation.
- [Pricing](https://aimusicapi.org/pricing): Available credit plans and account top-up options for API usage.

## API Documentation

- [Music Generate API](https://aimusicapi.org/docs/v2-generate): Creates asynchronous AI music tasks in inspiration or custom mode, with chirp-v6 model selection, image_urls image-to-music input, and webhook support.
- [Extend Music API](https://aimusicapi.org/docs/v2-extend): Extends a completed generated track while inheriting its settings or applying new lyrics and style controls.
- [Music Cover Image API](https://aimusicapi.org/docs/generate-music-cover): Creates cover artwork for a completed music task and explains how to poll the cover task status.
- [Timestamped Lyrics API](https://aimusicapi.org/docs/v2-timestamped-lyrics): Returns word-level lyric timestamps and alignment data for a selected audio result from a generation task.
- [Upload and Cover API](https://aimusicapi.org/docs/v2-upload-cover): Creates an AI cover from a public audio URL and documents generation, polling, model, image_urls, and duration constraints.
- [Task Status API](https://aimusicapi.org/docs/v2-feed): Polls a public workId until music generation succeeds or fails and returns the generated audio results.
- [Credits API](https://aimusicapi.org/docs/query-credits): Returns the authenticated account credit balance and total consumed credits for usage monitoring.
- [Callback Music Generate API](https://aimusicapi.org/docs/generate-callback): Creates a music task with a public callback URL and documents the asynchronous webhook payload sequence.

## Key Facts

- Public API base URL: https://aimusicapi.org/api
- Authentication: `Authorization: Bearer YOUR_API_KEY` for endpoints that require an account.
- Async create endpoints return a public task ID; use that same ID for status polling, logs, and user webhooks.
- Only public task IDs (for example workId) are valid for status polling, logs, and webhooks. Do not invent undocumented IDs, fields, or routes.
- Follow the status values and polling interval documented for each endpoint; most async tasks should be polled every 5-10 seconds.
- Current music models: chirp-v6 (12 credits), chirp-v6-mini (10 credits), chirp-v6-wild (12 credits). Legacy identifiers chirp-v3-5 to chirp-v5-5 remain accepted at their historical price and are served by chirp-v6 (chirp-v5, chirp-v5-5) or chirp-v6-mini (all others); model_name in results reports the model actually used.
- Image to music: /v2/generate and /v2/upload-cover/generate accept image_urls (up to 5 publicly accessible JPEG/PNG/WEBP URLs, 10MB each, +1 credit) in inspiration / non-custom mode only.
- Text limits apply to every model: custom prompt 5000, inspiration prompt 3000, style 1000, title 80 (100 for upload-cover); longer input is truncated, not rejected.
- Create endpoints return 422 (fix parameters) or 500 (temporary, retry later) with data.refunded when a request is rejected during validation; tasks that fail after being accepted are marked FAILED and refunded automatically.

## Integration Notes

- Keep API keys on the server and never expose them in browser code or public repositories.
- We do not permanently store generated images, audio, or other media files. After a task completes, promptly download the files and save them to your own server or object storage. Returned media URLs are temporary and may expire or become unavailable; do not use them as permanent links. Keeping a task ID or URL does not replace storing the files. We do not guarantee a fixed retention period.
- Use the exact field names and task ID format shown on the endpoint page being integrated.
- Treat callbacks as asynchronous notifications and verify the task through the documented status endpoint when needed.

## Contact

- Website: https://aimusicapi.org
- Support: support@aimusicapi.org