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

# ACE Music Tasks

> Retrieve only tasks owned by the authenticated caller. Polling is free and remains available with a zero balance; authentication and API permissions are required.



## OpenAPI

````yaml /openapi/acemusic.json post /acemusic/tasks
openapi: 3.0.0
info:
  title: ACE Music
  version: 1.0.0
  description: API reference for ACE Music on Ace Data Cloud.
servers:
  - url: https://api.acedata.cloud
    description: Ace Data Cloud API
security:
  - bearerAuth: []
paths:
  /acemusic/tasks:
    post:
      tags:
        - ACE Music
      summary: ACE Music Tasks
      description: >-
        Retrieve only tasks owned by the authenticated caller. Polling is free
        and remains available with a zero balance; authentication and API
        permissions are required.
      operationId: acemusic_tasks
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
                - action
              properties:
                action:
                  type: string
                  enum:
                    - retrieve
                    - retrieve_batch
                    - list
                id:
                  type: string
                ids:
                  type: array
                  items:
                    type: string
                  minItems: 1
                  maxItems: 100
                page:
                  type: integer
                  minimum: 1
                  default: 1
                  maximum: 10001
                page_size:
                  type: integer
                  minimum: 1
                  maximum: 100
                  default: 20
                type:
                  type: string
                  enum:
                    - audios
                    - lyrics
                  description: Optional history type filter.
                limit:
                  type: integer
                  minimum: 1
                  maximum: 100
                  description: >-
                    Alternative history page size; use page/page_size or
                    limit/offset consistently.
                offset:
                  type: integer
                  minimum: 0
                  maximum: 10000
                created_at_min:
                  type: number
                  minimum: 0
                  description: Inclusive creation-time lower bound, Unix seconds.
                created_at_max:
                  type: number
                  minimum: 0
                  description: Inclusive creation-time upper bound, Unix seconds.
              oneOf:
                - properties:
                    action:
                      enum:
                        - retrieve
                  required:
                    - id
                - properties:
                    action:
                      enum:
                        - retrieve_batch
                  required:
                    - ids
                - properties:
                    action:
                      enum:
                        - list
              allOf:
                - not:
                    allOf:
                      - anyOf:
                          - required:
                              - page
                          - required:
                              - page_size
                      - anyOf:
                          - required:
                              - limit
                          - required:
                              - offset
              description: >-
                Page and page_size cannot be mixed with limit or offset. The
                resulting offset must not exceed 10000. Missing or foreign task
                IDs return 404 on retrieve and are omitted from batch results.
      responses:
        '200':
          description: >-
            Request accepted or result available. Inspect the task state before
            treating generation as complete.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/AceMusicTask'
                  - type: object
                    required:
                      - items
                      - count
                    properties:
                      items:
                        type: array
                        items:
                          $ref: '#/components/schemas/AceMusicTask'
                      count:
                        type: integer
                        minimum: 0
                  - type: object
                    additionalProperties: false
                    description: No matching task exists for this caller.
        '400':
          description: Invalid request or unsupported model.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AceMusicError'
        '401':
          description: Invalid credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AceMusicError'
        '402':
          description: Insufficient balance for a paid operation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AceMusicError'
        '403':
          description: Access denied or content rejected.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AceMusicError'
        '404':
          description: Task not found for this caller.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AceMusicError'
        '409':
          description: Idempotency key reused with a different request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AceMusicError'
        '429':
          description: Rate limit exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AceMusicError'
        '500':
          description: Service failure.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AceMusicError'
      security:
        - bearerAuth: []
components:
  schemas:
    AceMusicTask:
      type: object
      required:
        - id
      properties:
        id:
          type: string
        state:
          type: string
        status:
          type: string
        created_at:
          type: number
        finished_at:
          type: number
          nullable: true
        request:
          type: object
          description: The caller-owned public creation parameters.
          additionalProperties: false
          properties:
            action:
              type: string
            model:
              type: string
            prompt:
              type: string
            lyric:
              type: string
            style:
              type: string
            title:
              type: string
            custom:
              type: boolean
            async:
              type: boolean
            audio_url:
              type: string
              format: uri
              pattern: ^https://
              minLength: 1
              maxLength: 20000
              description: >-
                HTTPS URL of an MP3 source file for upload. Use audio_id or
                mashup_audio_ids for already imported or generated tracks.
            name:
              type: string
              minLength: 1
              maxLength: 20000
              description: Optional display name for an upload.
            audio_id:
              type: string
              minLength: 1
              maxLength: 20000
              description: >-
                Public platform track ID owned by the caller. Required for
                cover; optional on upload to associate the import with an
                existing reference track.
            mashup_audio_ids:
              type: array
              items:
                type: string
                minLength: 1
                maxLength: 20000
              minItems: 2
              maxItems: 2
              uniqueItems: true
              description: >-
                Exactly two distinct caller-owned public track IDs. The selected
                references must be compatible with each other.
            audio_influence:
              type: number
              minimum: 1
              maximum: 100
              default: 60
              description: Audio reference strength for cover and mashup. Defaults to 60.
        response:
          $ref: '#/components/schemas/AceMusicTaskResult'
        type:
          type: string
          enum:
            - audios
            - lyrics
          description: >-
            Audio tasks include generate, upload, cover and mashup. Lyrics tasks
            use lyrics.
        trace_id:
          type: string
        started_at:
          type: number
        elapsed:
          type: number
          minimum: 0
    AceMusicError:
      type: object
      required:
        - success
        - error
      properties:
        success:
          type: boolean
          enum:
            - false
        task_id:
          type: string
        trace_id:
          type: string
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
    AceMusicTaskResult:
      type: object
      required:
        - success
        - task_id
      properties:
        success:
          type: boolean
        task_id:
          type: string
        trace_id:
          type: string
        status:
          type: string
          enum:
            - created
            - submitting
            - processing
            - storing
            - submission_unknown
            - succeeded
            - partial_failed
            - failed
        data:
          type: array
          items:
            anyOf:
              - $ref: '#/components/schemas/AceMusicTrack'
              - type: object
                required:
                  - title
                  - text
                properties:
                  title:
                    type: string
                  text:
                    type: string
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
    AceMusicTrack:
      type: object
      required:
        - id
        - model
        - state
      properties:
        id:
          type: string
        model:
          type: string
        state:
          type: string
        title:
          type: string
        lyric:
          type: string
        style:
          type: string
        audio_url:
          type: string
        image_url:
          type: string
        created_at:
          type: string
        duration:
          type: number
          minimum: 0
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API token from https://platform.acedata.cloud

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.