> ## Documentation Index
> Fetch the complete documentation index at: https://docs.crun.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Suno Vocal Separation Task Info

> Query the status and results of Suno vocal separation tasks.

## API Endpoint

```
GET https://api.crun.ai/api/v1/client/job/TaskInfo
```

<Info>
  This endpoint is used to query the execution status and retrieve the results of Suno vocal separation tasks created via the `/api/v1/client/job/CreateTask` API.\
  It shares the same endpoint, parameters, and task status enum as the [common task query](https://docs.crun.ai/models/common/get-task-info), but the task result does **not** include `media_urls` or `suno_data`.
  Instead, it returns a `media_info` object with audio stem URLs that vary by separation mode.
</Info>

## Query Parameters

<ParamField query="task_id" type="string" required>
  The unique task identifier returned when you created the task.

  **Example**: `task_12345678`
</ParamField>

## Request Example

<CodeGroup>
  ```bash cURL theme={null} theme={null}
  curl -X GET "https://api.crun.ai/api/v1/client/job/TaskInfo?task_id=task_12345678" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json"

  ```

  ```python Python theme={null} theme={null}
  import requests

  API_KEY = "YOUR_API_KEY"

  headers = {
    "X-API-KEY": API_KEY,
    "Content-Type": "application/json"
  }
  params = {
    "task_id": "task_12345678",
  }

  GET_TASK_STATUS_URL = "https://api.crun.ai/api/v1/client/job/TaskInfo"

  response = requests.get(GET_TASK_STATUS_URL, params=params, headers=headers)
  print(response.json())
  ```

  ```javascript Node.js theme={null} theme={null}
  const API_KEY = "YOUR_API_KEY";
  const taskId = "task_12345678";

  const url = new URL("https://api.crun.ai/api/v1/client/job/TaskInfo");
  url.searchParams.append("task_id", taskId);

  fetch(url.toString(), {
    method: "GET",
    headers: {
        "X-API-KEY": API_KEY,
        "Content-Type": "application/json",
    },
  })
    .then(res => res.json())
    .then(data => {
        console.log(data);
    })
    .catch(err => {
        console.error("Request failed:", err);
    });
  ```
</CodeGroup>

<ResponseExample title="Response Example">
  ```json Task Running theme={null}
  {
    "code": 200,
    "message": "success",
    "data": {
      "task_id": "d6956973-2f17-43d4-8514-af6cc3a2f55d",
      "provider": "Suno",
      "model_version": "suno-vocal-separation",
      "status": "running",
      "param": {
        "model": "suno/vocal-separatio",
        "callback_url": null,
        "input": {
          "task_id": "task_12345678",
          "suno_id": "suno_abc123",
          "mode": "vocal"
        }
      },
      "create_at": 1768900378,
      "result": null,
      "credits": 10,
      "duration_s": null,
      "complete_at": null,
      "source": "api"
    }
  }
  ```

  ```json Task Success (Vocal Mode) theme={null}
  {
    "code": 200,
    "message": "success",
    "data": {
      "task_id": "d6956973-2f17-43d4-8514-af6cc3a2f55d",
      "provider": "Suno",
      "model_version": "suno-vocal-separation",
      "status": "success",
      "param": {
        "model": "suno/vocal-separatio",
        "callback_url": null,
        "input": {
          "task_id": "task_12345678",
          "suno_id": "suno_abc123",
          "mode": "vocal"
        }
      },
      "create_at": 1768900378,
      "result": {
        "code": 200,
        "message": "generation success",
        "media_info": {
          "origin_url": "https://example.com/origin.mp3",
          "vocal_url": "https://example.com/vocal.mp3",
          "instrumental_url": "https://example.com/instrumental.mp3"
        }
      },
      "credits": 10,
      "duration_s": 137,
      "complete_at": 1768900515,
      "source": "api"
    }
  }
  ```

  ```json Task Success (Instrumental Mode) theme={null}
  {
    "code": 200,
    "message": "success",
    "data": {
      "task_id": "d6956973-2f17-43d4-8514-af6cc3a2f55d",
      "provider": "Suno",
      "model_version": "suno-vocal-separation",
      "status": "success",
      "param": {
        "model": "suno/vocal-separatio",
        "callback_url": null,
        "input": {
          "task_id": "task_12345678",
          "suno_id": "suno_abc123",
          "mode": "instrumental"
        }
      },
      "create_at": 1768900378,
      "result": {
        "code": 200,
        "message": "generation success",
        "media_info": {
          "origin_url": "https://example.com/origin.mp3",
          "vocal_url": "https://example.com/vocal.mp3",
          "backing_vocals_url": "https://example.com/backing_vocals.mp3",
          "drums_url": "https://example.com/drums.mp3",
          "bass_url": "https://example.com/bass.mp3",
          "guitar_url": "https://example.com/guitar.mp3",
          "keyboard_url": "https://example.com/keyboard.mp3",
          "percussion_url": "https://example.com/percussion.mp3",
          "strings_url": "https://example.com/strings.mp3",
          "synth_url": "https://example.com/synth.mp3",
          "fx_url": "https://example.com/fx.mp3",
          "brass_url": "https://example.com/brass.mp3",
          "woodwinds_url": "https://example.com/woodwinds.mp3"
        }
      },
      "duration_s": 137,
      "credits": 50,
      "complete_at": 1768900515,
      "source": "api"
    }
  }
  ```

  ```json Task Failed theme={null}
  {
    "code": 200,
    "message": "success",
    "data": {
      "task_id": "d6956973-2f17-43d4-8514-af6cc3a2f55d",
      "provider": "Suno",
      "model_version": "suno-vocal-separation",
      "status": "failed",
      "param": {
        "model": "suno/vocal-separatio",
        "callback_url": null,
        "input": {
          "task_id": "task_12345678",
          "suno_id": "suno_abc123",
          "mode": "vocal"
        }
      },
      "create_at": 1768900378,
      "result": {
        "code": 501,
        "message": "generation failed"
      },
      "credits": 0,
      "duration_s": 137,
      "complete_at": 1768900515,
      "source": "api"
    }
  }
  ```
</ResponseExample>

## Response Format

<ResponseField name="code" type="integer">
  Response status code. 200 indicates the request was successfully processed (the task was found and returned, regardless of execution result).
</ResponseField>

<ResponseField name="message" type="string">
  Response message. Typically `"success"`.
</ResponseField>

<ResponseField name="data" type="object">
  The task data object containing all task information.

  <Expandable title="data properties">
    <ResponseField name="task_id" type="string">
      The unique identifier of the task.
    </ResponseField>

    <ResponseField name="provider" type="string">
      The model provider name.

      **Example**: `Suno`
    </ResponseField>

    <ResponseField name="model_version" type="string">
      A specific model version used when creating a task.
    </ResponseField>

    <ResponseField name="status" type="string">
      Current status of the task. See [Task Status](#task-status-enum) below for details.

      **Possible values**: `pending`, `running`, `success`, `failed`
    </ResponseField>

    <ResponseField name="param" type="object">
      Original parameters used to create the task.

      <Expandable title="param properties">
        <ResponseField name="model" type="string">
          Model identifier used when creating the task.
        </ResponseField>

        <ResponseField name="callback_url" type="string | null">
          Webhook callback URL configured for this task.
        </ResponseField>

        <ResponseField name="input" type="object">
          Model-specific input parameters. The structure varies depending on the selected model.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="result" type="object | null">
      Task generation results.
      Valid value is returned only if the task status is `success` or `failed`; otherwise, `null` is returned.

      <Expandable title="result properties">
        <ResponseField name="code" type="integer">
          Task generation result status code. `200` indicates generation success. Non-200 values indicate generation failure.
        </ResponseField>

        <ResponseField name="message" type="string">
          Explanation of task success or failure.
        </ResponseField>

        <ResponseField name="media_info" type="object">
          Separated audio media URLs. Returned only when status is `success`.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="credits" type="number">
      Credits consumed by tasks. When the task status is `pending` or `running`, it indicates credits reserved in advance; when the task status is `success` or `failed`, it indicates the actual consumed credits.
    </ResponseField>

    <ResponseField name="create_at" type="integer">
      Unix timestamp (in seconds) when the task was created.
    </ResponseField>

    <ResponseField name="complete_at" type="integer | null">
      Unix timestamp (in seconds) when the task was completed.
      `null` if the task has not finished.
    </ResponseField>

    <ResponseField name="duration_s" type="integer | null">
      Task execution duration in seconds. Null if the task has not completed.
    </ResponseField>

    <ResponseField name="source" type="string">
      Source of task creation.
    </ResponseField>
  </Expandable>
</ResponseField>

## Media Info Object

<ResponseField name="origin_url" type="string">
  Original audio URL.
</ResponseField>

<ResponseField name="vocal_url" type="string">
  Main vocal audio URL.
</ResponseField>

<ResponseField name="instrumental_url" type="string">
  Instrumental part audio URL (vocal mode only).
</ResponseField>

<ResponseField name="backing_vocals_url" type="string">
  Backing vocals audio URL (instrumental mode only).
</ResponseField>

<ResponseField name="drums_url" type="string">
  Drums part audio URL (instrumental mode only).
</ResponseField>

<ResponseField name="bass_url" type="string">
  Bass part audio URL (instrumental mode only).
</ResponseField>

<ResponseField name="guitar_url" type="string">
  Guitar part audio URL (instrumental mode only).
</ResponseField>

<ResponseField name="keyboard_url" type="string">
  Keyboard part audio URL (instrumental mode only).
</ResponseField>

<ResponseField name="percussion_url" type="string">
  Percussion part audio URL (instrumental mode only).
</ResponseField>

<ResponseField name="strings_url" type="string">
  Strings part audio URL (instrumental mode only).
</ResponseField>

<ResponseField name="synth_url" type="string">
  Synthesizer part audio URL (instrumental mode only).
</ResponseField>

<ResponseField name="fx_url" type="string">
  Effects part audio URL (instrumental mode only).
</ResponseField>

<ResponseField name="brass_url" type="string">
  Brass part audio URL (instrumental mode only).
</ResponseField>

<ResponseField name="woodwinds_url" type="string">
  Woodwinds part audio URL (instrumental mode only).
</ResponseField>

## Task Status Enum

| Status    | Description                                | Action                                               |
| --------- | ------------------------------------------ | ---------------------------------------------------- |
| `pending` | Task is queued and waiting to be processed | Continue polling                                     |
| `running` | Task is currently being processed          | Continue polling                                     |
| `success` | Task successfully completed                | Access `result.media_info` to get stem URLs          |
| `failed`  | Task failed                                | Access result object to view error code and message. |

## Get Task Result Best Practices

<AccordionGroup>
  <Accordion title="Recommended Polling Intervals">
    * **Polling Interval**: Use a polling interval between 15 and 30 seconds
    * **Interval Dynamically**: For long-running audio processing tasks, consider increasing the polling interval dynamically
    * **Delayed Polling**: Wait at least one polling interval before the first status check to reduce unnecessary requests
    * **Maximum polling duration**: Stop after 15-20 minutes and investigate

    <Warning>
      Excessive polling may result in rate limiting. Use callbacks for production applications.
    </Warning>
  </Accordion>

  <Accordion title="Using Callbacks Instead of Polling">
    For production applications, we strongly recommend using the `callback_url` parameter when creating tasks:

    * **No polling needed**: Your server receives notifications automatically
    * **Lower API costs**: Eliminates continuous polling requests
    * **Better performance**: Immediate notifications when tasks complete
    * **Reduced latency**: No delay between completion and notification

    <Tip>
      Recommended method
    </Tip>
  </Accordion>

  <Accordion title="Handling Completed Tasks">
    When `status` is `success`:

    1. Retrieve the task result from the `result` field in the response
    2. Extract stem URLs from `result.media_info`
    3. Download audio files to your own storage
    4. Persist result metadata to your storage or database

    <Warning>
      **Important**: Generated media URLs are typically permanently deleted after 14 days
    </Warning>
  </Accordion>
</AccordionGroup>

## Common Error Codes

| Code  | Description                               | Solution                                                    |
| ----- | ----------------------------------------- | ----------------------------------------------------------- |
| `401` | Unauthorized - Invalid or missing API key | Check your API key                                          |
| `404` | Task not found                            | Verify the task\_id is correct                              |
| `429` | Exceeding the request rate limit          | Reduce request frequency                                    |
| `500` | Internal server error                     | Retry after a few minutes                                   |
| `501` | Generation failed                         | View the `result` object to get the error code and message. |

## Rate Limits

* **Maximum query rate**: 15 requests per second, per account limit
* **Recommended interval**: 15-30 seconds between polls

## Related Resources

<CardGroup cols={2}>
  <Card title="Vocal Separation" icon="music" href="/suno-api/vocal-separation">
    Create a vocal separation task
  </Card>

  <Card title="Suno Quickstart" icon="sparkles" href="/suno-api/quickstart">
    Learn how to call Suno models
  </Card>
</CardGroup>


## OpenAPI

````yaml suno-api/vocal-separation-task-info.json get /api/v1/client/job/TaskInfo
openapi: 3.0.0
info:
  title: Suno Vocal Separation Task Info
  description: Query the status and results of Suno vocal separation tasks.
  version: 1.0.0
  contact:
    name: Technical Support
    email: support@crun.ai
servers:
  - url: https://api.crun.ai
    description: API Server
security:
  - ApiKeyAuth: []
paths:
  /api/v1/client/job/TaskInfo:
    get:
      summary: Query the status and results of Suno vocal separation tasks.
      operationId: suno-vocal-separation-task-info
      parameters:
        - name: task_id
          in: query
          required: true
          description: Task ID used to retrieve task result.
          schema:
            type: string
            minLength: 36
            maxLength: 36
            example: task_1234567
      responses:
        '200':
          description: Task information retrieved successfully or task not found.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/TaskResponseModel'
        '401':
          description: API key missing
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
              example:
                code: 401
                message: API key missing
                data: null
        '403':
          description: API key disabled
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
              example:
                code: 403
                message: API key disabled
                data: null
        '404':
          description: Task not found
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
              example:
                code: 404
                message: Task not found
                data: null
        '500':
          $ref: '#/components/responses/Error'
components:
  schemas:
    ApiResponse:
      type: object
      properties:
        code:
          type: integer
          description: >-
            Response status code


            - **200**: Success - Request has been processed successfully

            - **401**: Unauthorized - Authentication credentials are missing or
            invalid

            - **402**: Insufficient Credits - Account does not have enough
            credits to perform the operation

            - **404**: Not Found - The requested resource or endpoint does not
            exist

            - **422**: Validation Error - The request parameters failed
            validation checks

            - **429**: Rate Limited - Request limit has been exceeded for this
            resource

            - **455**: Service Unavailable - System is currently undergoing
            maintenance

            - **500**: Server Error - An unexpected error occurred while
            processing the request

            - **501**: Generation Failed - Content generation task failed

            - **505**: Feature Disabled - The requested feature is currently
            disabled
        message:
          type: string
          description: Response message
        data:
          nullable: true
      required:
        - code
        - message
    TaskResponseModel:
      type: object
      description: Task record and result information.
      properties:
        task_id:
          type: string
          description: Task ID
          example: task_1234567
        provider:
          type: string
          description: Model provider
          example: Suno
        model_version:
          type: string
          description: Model version
          example: suno-vocal-separation
        status:
          type: string
          description: Task status
          enum:
            - pending
            - running
            - success
            - failed
          example: success
        param:
          type: object
          description: Original parameters used to create the task.
        create_at:
          type: integer
          description: Task creation timestamp (seconds)
          example: 1768900378
        result:
          type: object
          nullable: true
          description: >-
            Task generation result. Returned only when status is `success` or
            `failed`.
          properties:
            code:
              type: integer
              description: >-
                Task generation result status code. 200 indicates generation
                success.
              example: 200
            message:
              type: string
              description: Explanation of task success or failure.
              example: generation success
            media_info:
              $ref: '#/components/schemas/VocalSeparationMediaInfo'
          required:
            - code
            - message
        credits:
          type: number
          description: >-
            Credits consumed by tasks. When the task status is `pending` or
            `running`, it indicates credits reserved in advance; when the task
            status is `success` or `failed`, it indicates the actual consumed
            credits.
          example: 10
        duration_s:
          type: integer
          nullable: true
          description: Task execution duration in seconds
          example: 137
        complete_at:
          type: integer
          nullable: true
          description: Task completion timestamp (seconds)
          example: 1768900515
        source:
          type: string
          description: Task source
          enum:
            - api
            - playground
          example: api
      required:
        - task_id
        - provider
        - model_version
        - status
        - param
        - create_at
        - source
    VocalSeparationMediaInfo:
      type: object
      description: >-
        Separated audio media URLs. Returned only when status is `success`.
        Fields depend on separation mode.
      properties:
        origin_url:
          type: string
          format: uri
          description: Original audio URL.
          example: https://example.com/origin.mp3
        vocal_url:
          type: string
          format: uri
          description: Main vocal audio URL.
          example: https://example.com/vocal.mp3
        instrumental_url:
          type: string
          format: uri
          description: Instrumental part audio URL (vocal mode only).
          example: https://example.com/instrumental.mp3
        backing_vocals_url:
          type: string
          format: uri
          description: Backing vocals audio URL (instrumental mode only).
          example: https://example.com/backing_vocals.mp3
        drums_url:
          type: string
          format: uri
          description: Drums part audio URL (instrumental mode only).
          example: https://example.com/drums.mp3
        bass_url:
          type: string
          format: uri
          description: Bass part audio URL (instrumental mode only).
          example: https://example.com/bass.mp3
        guitar_url:
          type: string
          format: uri
          description: Guitar part audio URL (instrumental mode only).
          example: https://example.com/guitar.mp3
        keyboard_url:
          type: string
          format: uri
          description: Keyboard part audio URL (instrumental mode only).
          example: https://example.com/keyboard.mp3
        percussion_url:
          type: string
          format: uri
          description: Percussion part audio URL (instrumental mode only).
          example: https://example.com/percussion.mp3
        strings_url:
          type: string
          format: uri
          description: Strings part audio URL (instrumental mode only).
          example: https://example.com/strings.mp3
        synth_url:
          type: string
          format: uri
          description: Synthesizer part audio URL (instrumental mode only).
          example: https://example.com/synth.mp3
        fx_url:
          type: string
          format: uri
          description: Effects part audio URL (instrumental mode only).
          example: https://example.com/fx.mp3
        brass_url:
          type: string
          format: uri
          description: Brass part audio URL (instrumental mode only).
          example: https://example.com/brass.mp3
        woodwinds_url:
          type: string
          format: uri
          description: Woodwinds part audio URL (instrumental mode only).
          example: https://example.com/woodwinds.mp3
  responses:
    Error:
      description: Server Error
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        All APIs require authentication via API Key.


        Get API Key:

        1. Visit [API Key Management Page](https://crun.ai/user-api-key) to get
        your API Key


        Usage:

        Add to request header:


        x-api-key: YOUR_API_KEY


        Note:

        - Keep your API Key secure and do not share it with others

        - If you suspect your API Key has been compromised, reset it immediately
        in the management page

````