Generation APIs/Audio

Get Audio Task

GET

Overview

Read the current status and result payload for a previously submitted audio task. Poll this endpoint until data.status reaches completed or failed.

Authentication

All API requests require a Bearer token in the request header.

Authorization: Bearer YOUR_API_KEY

Create and manage API keys from API Keys or use https://www.apimall.ai/api-keys.

Request

API Information

URL: GET https://gateway.apimall.ai/api/v1/audio/{task_id}

Path Parameters

Parameter	Type	Required	Description
`task_id`	string	Required	Audio task identifier returned by `POST /api/v1/audio/generate`.

Request Example

GET https://gateway.apimall.ai/api/v1/audio/aud_01HQ9MB2J3RWB1V8Y5B9H8M2QK

Response Example

{
  "success": true,
  "data": {
    "task_id": "aud_01HQ9MB2J3RWB1V8Y5B9H8M2QK",
    "model": "V5",
    "status": "completed",
    "output": {
      "tracks": [
        {
          "audioUrl": "https://cdn.apimall.ai/generated/audio-01.mp3",
          "imageUrl": "https://cdn.apimall.ai/generated/audio-cover-01.webp"
        }
      ]
    },
    "audio_url": "https://cdn.apimall.ai/generated/audio-01.mp3",
    "image_url": "https://cdn.apimall.ai/generated/audio-cover-01.webp",
    "error_message": null,
    "credits_used": 12,
    "credits_refunded": 0,
    "created_at": "2026-03-12T09:40:00.000Z",
    "updated_at": "2026-03-12T09:41:30.000Z",
    "completed_at": "2026-03-12T09:41:30.000Z"
  },
  "request_id": "req_01HQ9M7J7X9P7Y8T6W5V4U3S2R"
}

cURL Example

curl --request GET 'https://gateway.apimall.ai/api/v1/audio/aud_01HQ9MB2J3RWB1V8Y5B9H8M2QK' \
  --header 'Authorization: Bearer YOUR_API_KEY'

JavaScript Example

const API_KEY = process.env.APIMALL_API_KEY;

const task_id = "aud_01HQ9MB2J3RWB1V8Y5B9H8M2QK";

const response = await fetch(`https://gateway.apimall.ai/api/v1/audio/${encodeURIComponent(String(task_id))}`, {
  headers: {
    Authorization: `Bearer ${API_KEY}`,
  },
});

if (!response.ok) {
  throw new Error(`Request failed: ${response.status} ${response.statusText}`);
}

const data = await response.json();
console.log(data);

Response Parameters

Parameter	Type	Description
`success`	boolean	Whether the request completed successfully.
`data.task_id`	string	Task ID used to query task status and results.
`data.model`	string	Model name used for the task.
`data.status`	string	Current status value returned by the API. Generation task endpoints use normalized values such as `pending`, `processing`, `completed`, `failed`, or `unknown`; management endpoints may return resource states such as `created`, `revoked`, or `active`.
`data.output.tracks`	array	Generated track metadata returned by the upstream audio provider payload.
`data.output.tracks[].audioUrl`	string	Primary audio URL for a generated track in the provider payload.
`data.output.tracks[].imageUrl`	string	Cover image URL for a generated track in the provider payload.
`data.audio_url`	string	Hosted audio result URL.
`data.image_url`	string	Hosted image result URL.
`data.error_message`	string	Failure reason returned when the music task does not complete successfully.
`data.credits_used`	integer	Credits consumed by this request.
`data.credits_refunded`	integer	Credits refunded after failure or partial refund handling.
`data.created_at`	string	Creation timestamp for the returned resource or task record.
`data.updated_at`	string	Last update timestamp for the returned resource or task record.
`data.completed_at`	string	Completion timestamp for the task when available.
`request_id`	string	Request identifier for debugging and support.

Error Response Example

{
  "success": false,
  "error": {
    "code": "not_found",
    "message": "Task not found"
  },
  "request_id": "req_01HQ9M7J7X9P7Y8T6W5V4U3S2R"
}

Integration Notes

Store your API key on the server side only.
Treat `completed` and `failed` as terminal states when implementing polling.
Use the hosted asset URL fields in the response for downstream delivery or storage.

Error Codes

Common Error Codes

Status Code	Description
200	Request successful
401	API key required or invalid API key
403	API access not approved or request made on a non-gateway host
404	Resource not found
429	Rate limit exceeded
500	Internal server error

Request

curl --location --request GET 'https://gateway.apimall.ai/api/v1/audio/aud_01HQ9MB2J3RWB1V8Y5B9H8M2QK' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json'

{
  "success": true,
  "data": {
    "task_id": "aud_01HQ9MB2J3RWB1V8Y5B9H8M2QK",
    "model": "V5",
    "status": "completed",
    "output": {
      "tracks": [
        {
          "audioUrl": "https://cdn.apimall.ai/generated/audio-01.mp3",
          "imageUrl": "https://cdn.apimall.ai/generated/audio-cover-01.webp"
        }
      ]
    },
    "audio_url": "https://cdn.apimall.ai/generated/audio-01.mp3",
    "image_url": "https://cdn.apimall.ai/generated/audio-cover-01.webp",
    "error_message": null,
    "credits_used": 12,
    "credits_refunded": 0,
    "created_at": "2026-03-12T09: 40: 00.000Z",
    "updated_at": "2026-03-12T09: 41: 30.000Z",
    "completed_at": "2026-03-12T09: 41: 30.000Z"
  },
  "request_id": "req_01HQ9M7J7X9P7Y8T6W5V4U3S2R"
}