{
  "openapi": "3.1.0",
  "info": {
    "title": "Query Single Task API",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://api.cometapi.com"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/suno/fetch/{task_id}": {
      "get": {
        "summary": "Query single task",
        "operationId": "query_single_task",
        "parameters": [
          {
            "name": "task_id",
            "in": "path",
            "required": true,
            "description": "Task ID. Available in the generate music response.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "code",
                    "message",
                    "data"
                  ],
                  "properties": {
                    "code": {
                      "type": "string",
                      "description": "Task status"
                    },
                    "message": {
                      "type": "string",
                      "description": "Message. Usually empty on success, may contain error details on failure."
                    },
                    "data": {
                      "type": "object",
                      "description": "Main data payload containing task details.",
                      "required": [
                        "task_id",
                        "action",
                        "status",
                        "progress",
                        "data"
                      ],
                      "properties": {
                        "task_id": {
                          "type": "string",
                          "description": "Unique task identifier (UUID)"
                        },
                        "action": {
                          "type": "string",
                          "description": "Task type or operation type"
                        },
                        "status": {
                          "type": "string",
                          "description": "Current task status"
                        },
                        "fail_reason": {
                          "type": "string",
                          "description": "Failure reason. Only valid when status is FAILED."
                        },
                        "submit_time": {
                          "type": "integer",
                          "description": "Task submission timestamp (Unix timestamp, seconds)"
                        },
                        "start_time": {
                          "type": "integer",
                          "description": "Task processing start timestamp (Unix timestamp, seconds)"
                        },
                        "finish_time": {
                          "type": "integer",
                          "description": "Task completion timestamp (Unix timestamp, seconds)"
                        },
                        "progress": {
                          "type": "string",
                          "description": "Task processing progress (percentage)"
                        },
                        "data": {
                          "type": "array",
                          "description": "Generated clips. The array can be empty while the task is still processing.",
                          "items": {
                            "type": "object",
                            "required": [
                              "id",
                              "status",
                              "clip_id"
                            ],
                            "properties": {
                              "id": {
                                "type": "string",
                                "description": "Generated clip ID."
                              },
                              "clip_id": {
                                "type": "string",
                                "description": "Generated clip ID used by follow-up workflows."
                              },
                              "status": {
                                "type": "string",
                                "description": "Clip processing status."
                              },
                              "state": {
                                "type": "string",
                                "description": "Provider-side clip state."
                              },
                              "title": {
                                "type": "string"
                              },
                              "tags": {
                                "type": "string"
                              },
                              "prompt": {
                                "type": "string"
                              },
                              "duration": {
                                "type": "number",
                                "description": "Clip duration in seconds."
                              },
                              "audio_url": {
                                "type": "string",
                                "description": "Audio URL. It can be empty before the clip is complete."
                              },
                              "image_url": {
                                "type": "string"
                              },
                              "video_url": {
                                "type": "string"
                              },
                              "model_name": {
                                "type": "string"
                              },
                              "major_model_version": {
                                "type": "string"
                              },
                              "created_at": {
                                "type": "string"
                              },
                              "metadata": {
                                "type": "object",
                                "additionalProperties": true
                              }
                            },
                            "additionalProperties": true
                          }
                        }
                      }
                    }
                  }
                },
                "example": {
                  "code": "success",
                  "message": "",
                  "data": {
                    "task_id": "<task_id>",
                    "action": "MUSIC",
                    "status": "SUCCESS",
                    "fail_reason": "",
                    "progress": "100%",
                    "data": [
                      {
                        "id": "<clip_id>",
                        "clip_id": "<clip_id>",
                        "status": "complete",
                        "state": "succeeded",
                        "title": "Generated Song",
                        "duration": 30.4,
                        "audio_url": "https://example.com/generated-song.mp3",
                        "model_name": "chirp-hawk",
                        "major_model_version": "v5.5"
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "Default",
            "source": "curl \"https://api.cometapi.com/suno/fetch/<task_id>\" \\\n  -H \"Authorization: Bearer $COMETAPI_KEY\"\n"
          },
          {
            "lang": "Python",
            "label": "Default",
            "source": "import os\nimport requests\n\ntask_id = \"<task_id>\"\n\nresponse = requests.get(\n    f\"https://api.cometapi.com/suno/fetch/{task_id}\",\n    headers={\"Authorization\": \"Bearer \" + os.environ[\"COMETAPI_KEY\"]},\n)\n\nprint(response.json())  # the route responds with the result payload\n"
          },
          {
            "lang": "JavaScript",
            "label": "Default",
            "source": "const taskId = \"<task_id>\";\n\nconst response = await fetch(`https://api.cometapi.com/suno/fetch/${taskId}`, {\n    headers: { Authorization: `Bearer ${process.env.COMETAPI_KEY}` },\n});\n\nconsole.log(await response.json()); // the route responds with the result payload\n"
          }
        ]
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Bearer token authentication. Use your CometAPI key."
      }
    }
  }
}