API อัปโหลดแบบเสริม

อัปเดต 2026-09-18 · ทีม Suno-API

คำอธิบายเอนด์พอยต์

อัปโหลดแบบเสริมใช้ส่งไฟล์เสียงในเครื่อง ระบบจะทำการเสริมคุณภาพเบื้องหลังและสร้างผลลัพธ์เป็นเพลงเต็มที่เล่นได้ เอนด์พอยต์จะคืนข้อมูลงานทันที และไคลเอนต์ต้องไล่ถามเอนด์พอยต์ค้นหาเพื่อดูความคืบหน้า

เอนด์พอยต์ส่งงาน: POST /api/music/enhanced-upload

ค้นหางานเดียว: GET /api/music/enhanced-upload/:id

ยกเลิกงาน: POST /api/music/enhanced-upload/:id/cancel

ค้นหารายการ: GET /api/music/enhanced-upload

ค่าบริการ: 10 หยวนต่อครั้ง คิดล่วงหน้าตามราคาคงที่ของ suno-enhanced-upload หากงานล้มเหลวหรือถูกยกเลิกในช่วงที่อนุญาต ระบบจะคืนเงินที่คิดล่วงหน้าให้อัตโนมัติ ยอดหักจริงเป็นไปตามการตั้งราคาในระบบหลังบ้านปัจจุบัน

ขั้นตอนการเรียกใช้

1. เรียก POST /api/music/enhanced-upload เพื่ออัปโหลดไฟล์เสียง
2. เก็บ task_id ที่คืนมา
3. เรียก GET /api/music/enhanced-upload/:id เพื่อดูความคืบหน้าและผลลัพธ์
4. เมื่อ Suno เรนเดอร์ขั้นสุดท้ายเสร็จ ระบบจะใช้บัญชี Suno ที่ผูกกับงานนั้นเรียกเอนด์พอยต์ดาวน์โหลดแบบได้รับอนุญาตของ Studio แล้วเขียน MP3 ลงในบริการสื่อ CN2
5. งานจะกลายเป็น completed ก็ต่อเมื่อทรัพยากร CN2 พร้อมแล้ว จึงอ่านที่อยู่เสียง CDN จาก audio_url ในคำตอบ

/api/forbidden เป็นที่อยู่ชั่วคราวที่อาจปรากฏในเมทาดาทาของ Suno Studio ไม่ใช่ทรัพยากรที่เล่นหรือดาวน์โหลดได้ ระบบจะไม่คืนให้ลูกค้าและไม่ใช้เป็นหลักฐานว่าจบงาน หากเรนเดอร์เสร็จแล้วแต่ CN2 ยังเตรียมอยู่ เอนด์พอยต์จะคืน processing ต่อไปและไม่คืน audio_url ไคลเอนต์ควรไล่ถามต่อและไม่ถือว่าที่อยู่ว่างคือความล้มเหลว

ส่งงานอัปโหลดแบบเสริม

Headers

พารามิเตอร์ฟอร์ม

ตัวอย่างคำขอ

ตัวอย่างด้านล่างใช้วิธีเรียกแบบเดียวกับตอนตรวจสอบบนโปรดักชัน แต่เปลี่ยน API Key เป็นค่าชั่วคราวแล้ว

curl.exe --http1.1 -s -S \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@source.aac" \
  -F "title=Enhanced upload demo" \
  "https://www.suno-api.io/api/music/enhanced-upload"

คำตอบ

{
  "success": true,
  "message": "",
  "data": {
    "task_id": 3209,
    "song_id": "pending:enhanced-upload:cu_20260611003241723483700xnCcQg",
    "client_request_id": "cu_20260611003241723483700xnCcQg",
    "title": "Enhanced upload demo",
    "file_name": "source.aac",
    "status": "queued",
    "created_at": 1781137961,
    "pre_consumed_quota": 5000000,
    "billing_source": "wallet"
  }
}

ค้นหางานเดียว

ตัวอย่างคำขอ

curl.exe --http1.1 -s -S \
  -H "Authorization: Bearer YOUR_API_KEY" \
  "https://www.suno-api.io/api/music/enhanced-upload/3209"

ตัวอย่างคำตอบขณะประมวลผล

{
  "success": true,
  "message": "",
  "data": {
    "task": {
      "task_id": 3209,
      "song_id": "pending:enhanced-upload:cu_20260611003241723483700xnCcQg",
      "client_request_id": "cu_20260611003241723483700xnCcQg",
      "title": "Enhanced upload demo",
      "file_name": "source.aac",
      "status": "processing",
      "type": "enhanced_upload",
      "progress": {
        "stage": "media_preparing",
        "percent": 98,
        "label": "正在准备播放资源",
        "updated_at": 1781138500
      },
      "pre_consumed_quota": 5000000,
      "billing_source": "wallet",
      "created_at": 1781137961,
      "updated_at": 1781138500
    }
  }
}

ตัวอย่างคำตอบเมื่อเสร็จสิ้น

{
  "success": true,
  "message": "",
  "data": {
    "task": {
      "task_id": 3209,
      "song_id": "56cbd0bb-0e8c-4a34-8729-55d5c05d9c53",
      "client_request_id": "cu_20260611003241723483700xnCcQg",
      "title": "Enhanced upload demo",
      "file_name": "source.aac",
      "status": "completed",
      "type": "enhanced_upload",
      "audio_url": "https://media.code-go.com/assets/56cbd0bb-0e8c-4a34-8729-55d5c05d9c53-mp3.mp3",
      "duration": 217.74,
      "progress": {
        "stage": "completed",
        "percent": 100,
        "label": "已完成",
        "updated_at": 1781138943
      },
      "pre_consumed_quota": 5000000,
      "billing_source": "wallet",
      "created_at": 1781137961,
      "updated_at": 1781138943,
      "completed_at": 1781138943
    }
  }
}

ยกเลิกงาน

ยกเลิกได้เฉพาะเมื่อทั้งงานและเวิร์กโฟลว์ฝั่งหลังบ้านยังอยู่ในขั้น queued เท่านั้น เมื่องานเข้าสู่ leasing, running, processing หรือเสร็จสิ้นแล้ว จะยกเลิกไม่ได้

ตัวอย่างคำขอ

curl.exe --http1.1 -s -S -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  "https://www.suno-api.io/api/music/enhanced-upload/3209/cancel"

คำตอบ

{
  "success": true,
  "message": "",
  "data": {
    "task_id": 3209,
    "song_id": "pending:enhanced-upload:cu_20260611003241723483700xnCcQg",
    "client_request_id": "cu_20260611003241723483700xnCcQg",
    "status": "cancelled"
  }
}

หากงานเริ่มประมวลผลแล้ว เอนด์พอยต์จะคืน:

{
  "success": false,
  "message": "强化上传已开始处理，无法取消"
}

ค้นหารายการงาน

เอนด์พอยต์รายการจะคืนเฉพาะงานอัปโหลดแบบเสริมของผู้ใช้ที่เป็นเจ้าของ API Key ปัจจุบัน ไม่ปนงานสร้างเพลงทั่วไป คัฟเวอร์ หรือต่อเพลง

พารามิเตอร์คำค้น

ตัวอย่างคำขอ

curl.exe --http1.1 -s -S \
  -H "Authorization: Bearer YOUR_API_KEY" \
  "https://www.suno-api.io/api/music/enhanced-upload?p=1&page_size=3"

คำตอบ

{
  "success": true,
  "message": "",
  "data": {
    "page": 1,
    "page_size": 3,
    "total": 1,
    "items": [
      {
        "task_id": 3209,
        "song_id": "56cbd0bb-0e8c-4a34-8729-55d5c05d9c53",
        "client_request_id": "cu_20260611003241723483700xnCcQg",
        "title": "Enhanced upload demo",
        "file_name": "source.aac",
        "status": "completed",
        "type": "enhanced_upload",
        "audio_url": "https://media.code-go.com/assets/56cbd0bb-0e8c-4a34-8729-55d5c05d9c53-mp3.mp3",
        "duration": 217.74,
        "progress": {
          "stage": "completed",
          "percent": 100,
          "label": "已完成",
          "updated_at": 1781138943
        },
        "pre_consumed_quota": 5000000,
        "billing_source": "wallet",
        "created_at": 1781137961,
        "updated_at": 1781138943,
        "completed_at": 1781138943
      }
    ]
  }
}

คำอธิบายฟิลด์ที่คืนกลับ

ข้อควรระวัง

• ปัจจุบันเอนด์พอยต์รองรับเฉพาะการอัปโหลดไฟล์แบบ multipart ไม่รองรับ file_url หรือ file_base64 แบบ JSON
• ไฟล์ที่อัปโหลดมีขนาดสูงสุด 80 MB
• เอนด์พอยต์ส่งงานเป็นแบบอะซิงโครนัส การได้ queued หมายถึงงานเข้าคิวแล้ว ไม่ได้หมายความว่าเสียงเสร็จแล้ว
• การยกเลิกใช้ได้เฉพาะงานที่ยังไม่เริ่มประมวลผล เมื่อเข้าสู่ขั้นประมวลผลแล้ว เวิร์กโฟลว์ของบัญชีแพลตฟอร์มจะไม่ถูกตัด
• อย่าเปิดเผย API Key จริงในโค้ดฝั่งไคลเอนต์

เริ่มคัฟเวอร์หลังอัปโหลดแบบเสริมเสร็จ

เมื่ออัปโหลดแบบเสริมเสร็จแล้ว สามารถใช้ผลลัพธ์เป็นคลิปต้นทางและเรียก POST /api/music/generate-from-source เพื่อเริ่มคัฟเวอร์ได้

หมายเหตุ: คัฟเวอร์เป็นเอนด์พอยต์ซิงโครนัส คำสั่งจะถูกรับเมื่อคำตอบกลับมาเท่านั้น และจากการวัดอาจรอนานถึงประมาณ 230 วินาที กรุณาตั้ง timeout ฝั่งไคลเอนต์ไว้ที่ 300 วินาทีขึ้นไป และอย่าลองซ้ำทันทีหลัง timeout ดูหัวข้อ "ระยะเวลารอและการตั้งค่า timeout" ใน ภาพรวม API ใหม่

ให้ไล่ถาม GET /api/music/enhanced-upload/:id จนกว่า task.status จะเป็น completed เมื่อถึงตอนนั้น:

• task.song_id คือ ID เพลงจริง และเป็น sourceClipId ที่เอนด์พอยต์คัฟเวอร์ต้องการ
• ควรส่ง task.audio_url เป็น sourceAudioUrl ด้วย เพื่อให้เซิร์ฟเวอร์จัดการกรณีที่คลิปต้นทางกับบัญชีที่ทำงานไม่ตรงกัน
• task.task_id เป็นเพียง ID งานอัปโหลดแบบเสริม ใช้เป็น sourceClipId ไม่ได้
• pending:enhanced-upload:* เป็น ID ชั่วคราวของขั้นประมวลผล ใช้กับคัฟเวอร์ไม่ได้

เมื่อเริ่มคัฟเวอร์ ให้ใช้ API Key เดียวกับตอนอัปโหลดแบบเสริม และประกอบคำขอตามการจับคู่ฟิลด์ด้านล่าง

พารามิเตอร์ที่เหลือ (เนื้อเพลง สไตล์ ชื่อเพลง โมเดล) ให้กรอกตาม API คัฟเวอร์จากคลิปต้นทาง เมื่อเอนด์พอยต์คัฟเวอร์คืน clips[].song_id ใหม่แล้ว ให้ใช้ POST /api/music/query เพื่อตรวจสถานะการสร้างและเสียงสุดท้าย