Job Management

Get Job Status

`GET /api/v1/music/jobs/{job_id}/status`

Get the current status of a music generation job.

Python
Node.js
cURL

from audiopod import AudioPod

client = AudioPod(api_key="ap_your_api_key")

job = client.music.get_job(123)
print(f"Status: {job['status']}")

if job['status'] == 'COMPLETED':
    print(f"Audio URL: {job['output_url']}")
    print(f"Duration: {job['audio_duration']}s")

import AudioPod from 'audiopod';

const client = new AudioPod({ apiKey: 'ap_your_api_key' });

const job = await client.music.get(123);
console.log(`Status: ${job.status}`);

if (job.status === 'COMPLETED') {
  console.log(`Audio URL: ${job.output_url}`);
}

curl "https://api.audiopod.ai/api/v1/music/jobs/123/status" \
  -H "X-API-Key: $AUDIOPOD_API_KEY"

Response: Full MusicGenerationJob object (see response format).

List Jobs

`GET /api/v1/music/jobs`

List music generation jobs with filtering, search, and sorting.

Python
Node.js
cURL

# List recent jobs
jobs = client.music.list_jobs(limit=20)

# Filter by task type
songs = client.music.list_jobs(task="text2music", limit=50)

// List recent jobs
const jobs = await client.music.list({ limit: 20 });

// Filter by status
const completed = await client.music.list({
  status: 'COMPLETED',
  limit: 50,
});

# List with filters
curl "https://api.audiopod.ai/api/v1/music/jobs?status=COMPLETED&sort_by=created_at&sort_order=desc&limit=20" \
  -H "X-API-Key: $AUDIOPOD_API_KEY"

Query Parameters:

Parameter	Type	Default	Description
`skip`	int	0	Number of records to skip
`limit`	int	50	Number of records to return (max 100)
`task`	string	null	Filter by task type (`text2music`, `prompt2instrumental`, etc.)
`status`	string	null	Filter by status (`PENDING`, `PROCESSING`, `COMPLETED`, `FAILED`)
`song_type`	string	null	Filter by library category: `song`, `instrumental`, `edits`, `scores` (or the narrower `rap`, `vocals`, `samples`). See Library categories
`liked`	bool	null	Filter to liked (true) or not-liked (false) tracks
`search`	string	null	Search across display name, prompt, and lyrics
`language`	string	null	Filter by vocal language
`genre`	string	null	Filter by genre
`emotion`	string	null	Filter by emotion tag
`occasion`	string	null	Filter by occasion tag
`sort_by`	string	`"created_at"`	Sort field: `created_at`, `display_name`, `audio_duration`, `status`
`sort_order`	string	`"desc"`	Sort direction: `asc` or `desc`
`include_interactions`	bool	false	Include like/dislike status for each job

Response Headers:

X-Total-Count: Total number of matching records (for pagination)

Library categories

Every job belongs to exactly one of four categories, so song + instrumental + edits + scores always adds up to your whole library. The same rule drives song_type here, on /liked and /jobs/counts, and the counts in /filters/stats.

`song_type`	What it returns
`song`	Tracks with vocals: `text2music` and `text2rap` with lyrics to sing, and every `lyric2vocals` job
`instrumental`	`prompt2instrumental` and `text2samples` jobs, plus `text2music` / `text2rap` jobs generated as instrumentals: `instrumental: true`, no lyrics, lyrics of just `[Instrumental]`, or lyrics made only of section tags such as `[Intro]`
`edits`	Jobs made from an existing track: `retake`, `repaint`, `extend`, `edit`, `cover`, `lego`, `extract`, `complete`
`scores`	Written scores without a recording: score-only (plan) jobs, and generations that kept their score but finished without audio
`rap`	The `text2rap` jobs within `song`
`vocals`	The `lyric2vocals` jobs within `song`
`samples`	The `text2samples` jobs within `instrumental`

song used to mean “every text2music job”, and instrumental meant only prompt2instrumental. A text2music track generated as an instrumental is now in instrumental, rap tracks with vocals are in song, and edits and scores have their own categories. Filter by task to get the old task-only behaviour.

Delete Job

`DELETE /api/v1/music/jobs/{job_id}`

Delete a music generation job and its associated audio files.

Python
Node.js
cURL

result = client.music.delete_job(123)
print(result['message'])  # "Job deleted successfully"

await client.music.delete(123);

curl -X DELETE "https://api.audiopod.ai/api/v1/music/jobs/123" \
  -H "X-API-Key: $AUDIOPOD_API_KEY"

Update Job Metadata

`PATCH /api/v1/music/jobs/{job_id}`

Update a job’s display name or thumbnail URL.

cURL

curl -X PATCH "https://api.audiopod.ai/api/v1/music/jobs/123" \
  -H "X-API-Key: $AUDIOPOD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "My Awesome Track",
    "thumbnail_url": "https://example.com/thumbnail.jpg"
  }'

Request Body:

Parameter	Type	Description
`display_name`	string	New display name
`thumbnail_url`	string	New thumbnail image URL

Retry Failed Job

`POST /api/v1/music/jobs/{job_id}/retry`

Retry a failed music generation job without consuming additional credits. The original credit reservation is reused.

cURL

curl -X POST "https://api.audiopod.ai/api/v1/music/jobs/123/retry" \
  -H "X-API-Key: $AUDIOPOD_API_KEY"

Constraints:

Only works on jobs with status: "FAILED"
Original credit reservation is reused (no additional charge)
Returns a MusicGenerationResponse with the re-queued job

Rate limit: 10 requests per minute.

Job Counts

`GET /api/v1/music/jobs/counts`

Get aggregated counts of your music generation jobs, broken down by task type and song category.

cURL

# All counts
curl "https://api.audiopod.ai/api/v1/music/jobs/counts" \
  -H "X-API-Key: $AUDIOPOD_API_KEY"

# Filter by status
curl "https://api.audiopod.ai/api/v1/music/jobs/counts?status=COMPLETED" \
  -H "X-API-Key: $AUDIOPOD_API_KEY"

Query Parameters:

Parameter	Type	Description
`status`	string	Filter by status
`song_type`	string	Filter by library category: `song`, `instrumental`, `edits`, `scores` (or `rap`, `vocals`, `samples`). See Library categories

Response: by_song_type has one count per library category. songs + instrumental + edits + scores equals total; rap is the part of songs made with text2rap.

{
  "total": 150,
  "by_task": {
    "text2music": 76,
    "prompt2instrumental": 40,
    "text2rap": 20,
    "retake": 10,
    "lyric2vocals": 4
  },
  "by_song_type": {
    "songs": 85,
    "instrumental": 50,
    "edits": 10,
    "scores": 5,
    "rap": 18
  },
  "filters": {
    "status": null,
    "song_type": null
  }
}

Liked Tracks

`GET /api/v1/music/liked`

Get all tracks you’ve liked.

cURL

curl "https://api.audiopod.ai/api/v1/music/liked?limit=20" \
  -H "X-API-Key: $AUDIOPOD_API_KEY"

Query Parameters:

Parameter	Type	Default	Description
`skip`	int	0	Pagination offset
`limit`	int	50	Number of records
`song_type`	string	null	Filter by library category
`status`	string	null	Filter by status

Filter Statistics

`GET /api/v1/music/filters/stats`

Get statistics for building filter UI dropdowns — total tracks, liked count, task distribution, and available filter values.

cURL

curl "https://api.audiopod.ai/api/v1/music/filters/stats" \
  -H "X-API-Key: $AUDIOPOD_API_KEY"

Response: song_types counts each library category: songs + instrumental + edits + scores equals total_tracks, and each count matches what GET /api/v1/music/jobs?song_type=... returns (songs is the song filter). rap is the part of songs made with text2rap.

{
  "total_tracks": 150,
  "liked_count": 25,
  "song_types": {
    "songs": 85,
    "instrumental": 50,
    "edits": 10,
    "scores": 5,
    "rap": 18
  },
  "available_filters": {
    "song_types": ["songs", "rap", "instrumental", "edits", "scores"],
    "interactions": ["liked"],
    "statuses": ["pending", "processing", "completed", "failed"],
    "languages": ["en", "zh", "ja", "ko"],
    "genres": ["pop", "rock", "jazz"],
    "emotions": ["happy", "sad", "energetic"],
    "occasions": ["party", "relaxation", "workout"]
  }
}

Genre Presets

`GET /api/v1/music/presets`

Get available genre presets with their pre-configured parameters.

Python
Node.js
cURL

presets = client.music.get_presets()
for name, config in presets['genre_presets'].items():
    print(f"{name}: {config}")

const presets = await client.music.getPresets();
console.log(presets);

curl "https://api.audiopod.ai/api/v1/music/presets" \
  -H "X-API-Key: $AUDIOPOD_API_KEY"

Model Status

`GET /api/v1/music/model/status`

Get AudioMusic V2 model health and status information.

cURL

curl "https://api.audiopod.ai/api/v1/music/model/status" \
  -H "X-API-Key: $AUDIOPOD_API_KEY"

Sample Data

`GET /api/v1/music/sample-data`

Get sample/test data for development and testing purposes.

cURL

curl "https://api.audiopod.ai/api/v1/music/sample-data" \
  -H "X-API-Key: $AUDIOPOD_API_KEY"

Audiobook

Podcast

Audio Processing

Speech

Voice

Music

Utilities

Get Job Status

`GET /api/v1/music/jobs/{job_id}/status`

List Jobs

`GET /api/v1/music/jobs`

Library categories

Delete Job

`DELETE /api/v1/music/jobs/{job_id}`

Update Job Metadata

`PATCH /api/v1/music/jobs/{job_id}`

Retry Failed Job

`POST /api/v1/music/jobs/{job_id}/retry`

Job Counts

`GET /api/v1/music/jobs/counts`

Liked Tracks

`GET /api/v1/music/liked`

Filter Statistics

`GET /api/v1/music/filters/stats`

Genre Presets

`GET /api/v1/music/presets`

Model Status

`GET /api/v1/music/model/status`

Sample Data

`GET /api/v1/music/sample-data`

​Get Job Status

​GET /api/v1/music/jobs/{job_id}/status

​List Jobs

​GET /api/v1/music/jobs

​Library categories

​Delete Job

​DELETE /api/v1/music/jobs/{job_id}

​Update Job Metadata

​PATCH /api/v1/music/jobs/{job_id}

​Retry Failed Job

​POST /api/v1/music/jobs/{job_id}/retry

​Job Counts

​GET /api/v1/music/jobs/counts

​Liked Tracks

​GET /api/v1/music/liked

​Filter Statistics

​GET /api/v1/music/filters/stats

​Genre Presets

​GET /api/v1/music/presets

​Model Status

​GET /api/v1/music/model/status

​Sample Data

​GET /api/v1/music/sample-data

Get Job Status

`GET /api/v1/music/jobs/{job_id}/status`

List Jobs

`GET /api/v1/music/jobs`

Library categories

Delete Job

`DELETE /api/v1/music/jobs/{job_id}`

Update Job Metadata

`PATCH /api/v1/music/jobs/{job_id}`

Retry Failed Job

`POST /api/v1/music/jobs/{job_id}/retry`

Job Counts

`GET /api/v1/music/jobs/counts`

Liked Tracks

`GET /api/v1/music/liked`

Filter Statistics

`GET /api/v1/music/filters/stats`

Genre Presets

`GET /api/v1/music/presets`

Model Status

`GET /api/v1/music/model/status`

Sample Data

`GET /api/v1/music/sample-data`