Claude Files API: อัปโหลดครั้งเดียว อ้างอิงได้ทุกที่ (คู่มือ GA)

Claude Files API ให้คุณอัปโหลดไฟล์เพียงครั้งเดียวไปที่ https://api.anthropic.com/v1/files รับ file_id กลับมา แล้วอ้างอิง ID นั้นในคำขอ Messages ใดก็ได้ แทนที่จะส่งเนื้อหาซ้ำใหม่ทุกครั้ง ณ วันที่ 20 สิงหาคม 2026 ฟีเจอร์นี้เปิดให้ใช้งานแบบทั่วไป (GA) บน Claude Platform แล้ว: ไม่ต้องใช้ beta header, พื้นที่จัดเก็บ 1 TB ต่อองค์กร และ rate limit สูงกว่าเวอร์ชัน beta ถึงห้าเท่า Anthropic ประกาศการเปลี่ยนแปลงนี้ใน โพสต์เรื่อง production agents ควบคู่ไปกับการเปิด GA ของ computer use, browser tool และ Skills API

คู่มือนี้ครอบคลุมวงจรชีวิตทั้งหมด: การอัปโหลด, การอ้างอิงไฟล์ในข้อความ, การดาวน์โหลดผลลัพธ์ที่สร้างขึ้น, การหมดอายุ, โมเดลความปลอดภัยของ workspace และข้อจำกัดที่คุณจะเจอในการใช้งานจริง เนื่องจากทุกขั้นตอนที่นี่เป็นการเรียก HTTP coding agent ของคุณสามารถเปลี่ยนโฟลว์ทั้งหมดให้เป็น test scenario ผ่าน Apidog CLI ได้ แทนที่จะเป็นคำสั่ง curl แบบครั้งต่อครั้งกองเป็นตั้ง

Files API ทำอะไรได้บ้าง

Files API คือชั้นจัดเก็บแบบ "สร้างครั้งเดียว ใช้หลายครั้ง" สำหรับ Claude API มันแก้ปัญหาเรื่องต้นทุนที่เฉพาะเจาะจง: หากแอปของคุณถามคำถามเกี่ยวกับไฟล์ PDF 40 หน้าฉบับเดียวกันในคำขอหลายร้อยครั้ง การอัปโหลด PDF นั้นซ้ำในทุกคำขอจะเปลืองแบนด์วิดท์และทำให้โค้ดฝั่งไคลเอนต์ซับซ้อนขึ้น ด้วย Files API คุณสามารถ:

Claude Files API lifecycle: upload, reference by file_id, download, delete

อัปโหลด ไฟล์ไปยังพื้นที่จัดเก็บของ Anthropic และรับ file_id ที่ไม่ซ้ำใครกลับมา
อ้างอิง ID นั้นในคำขอ Messages ผ่าน content block
ดาวน์โหลด ไฟล์ที่ skills หรือ code execution tool สร้างขึ้น (แผนภูมิ, สเปรดชีต, สไลด์นำเสนอ)
จัดการ ทุกอย่างด้วยการดำเนินการ list, retrieve-metadata และ delete

จำนวน endpoint มีไม่มาก:

การดำเนินการ	Endpoint
อัปโหลดไฟล์	`POST /v1/files`
แสดงรายการไฟล์	`GET /v1/files`
ดึงข้อมูลเมตาของไฟล์	`GET /v1/files/{file_id}`
ดาวน์โหลดเนื้อหาไฟล์	`GET /v1/files/{file_id}/content`
ลบไฟล์	`DELETE /v1/files/{file_id}`

ทั้งหมดทำงานร่วมกับ header มาตรฐาน x-api-key และ anthropic-version: 2023-06-01 หากคุณเพิ่งเริ่มใช้ Messages API คู่มือ Claude Opus 5 API ของเราครอบคลุมพื้นฐานเรื่องการยืนยันตัวตนและรูปแบบคำขอไว้แล้ว

อะไรเปลี่ยนไปเมื่อเปิด GA

Files API อยู่ในช่วง beta หลัง header มาหลายเดือน การเปิด GA เมื่อวันที่ 20 สิงหาคม 2026 เปลี่ยนสี่สิ่งที่มีผลต่อการวางแผนระดับโปรดักชัน:

What changed when the Claude Files API went GA

ไม่ต้องใช้ beta header คำขอทำงานได้ด้วย header มาตรฐานบน Claude API
Rate limit สูงขึ้น 5 เท่า การดำเนินการกับไฟล์รองรับประมาณ 500 คำขอต่อนาที โดยสามารถขอ limit ที่สูงขึ้นได้ผ่านฝ่ายขาย
พื้นที่จัดเก็บ 1 TB ต่อองค์กร โดยจำกัดไฟล์ละ 500 MB
ครอบคลุมแพลตฟอร์มกว้างขึ้น Files API ทำงานบน Claude API โดยตรง บน Claude Platform on AWS ในเวอร์ชัน beta และบน Microsoft Foundry เมื่อใช้การดีพลอยแบบ Hosted on Anthropic แต่ไม่พร้อมใช้งานบน Amazon Bedrock หรือ Google Cloud Vertex AI และไม่มีสิทธิ์ใช้ข้อตกลง zero-data-retention วางแผนให้สอดคล้องหากคุณมีนโยบายการเก็บข้อมูลที่เข้มงวด

การอัปโหลดไฟล์

การอัปโหลดเป็นคำขอแบบ multipart form ไม่ใช่ JSON:

curl -X POST https://api.anthropic.com/v1/files \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -F "file=@/path/to/report.pdf"

ผลลัพธ์ที่ได้จะให้ทุกอย่างที่คุณต้องใช้ในการอ้างอิงไฟล์ในภายหลัง:

{
  "id": "file_011CNha8iCJcU1wXNR6q4V8w",
  "type": "file",
  "filename": "report.pdf",
  "mime_type": "application/pdf",
  "size_bytes": 1024000,
  "created_at": "2026-08-24T00:00:00Z",
  "downloadable": false,
  "expires_at": null
}

มีสองฟิลด์ที่ควรให้ความสนใจ downloadable จะเป็น false สำหรับทุกไฟล์ที่คุณอัปโหลด มีเพียงไฟล์ที่ Claude สร้างผ่าน skills หรือ code execution เท่านั้นที่ดาวน์โหลดกลับมาได้ และ expires_at จะเป็น null เว้นแต่คุณกำหนดเวลาหมดอายุตอนอัปโหลด (รายละเอียดด้านล่าง)

ในเทสต์ Apidog CLI ด้านล่าง ขั้นตอนอัปโหลดจะบันทึก id ไว้เป็นตัวแปร ดังนั้นทุกคำขอถัดไปจะอ้างอิง {{claude_file_id}} แทนสตริงที่ฮาร์ดโค้ดไว้

การอ้างอิงไฟล์ในข้อความ

เมื่ออัปโหลดแล้ว ไฟล์จะเสียบเข้าในคำขอ Messages ผ่าน content block หนึ่งในสามประเภท ขึ้นอยู่กับชนิดของไฟล์:

ประเภทไฟล์	MIME type	Content block
PDF, ข้อความล้วน	`application/pdf`, `text/plain`	`document`
รูปภาพ	`image/jpeg`, `image/png`, `image/gif`, `image/webp`	`image`
ชุดข้อมูลและอื่น ๆ	แตกต่างกันไป	`container_upload` (code execution tool)

คำขอสรุปเนื้อหา PDF จะมีหน้าตาแบบนี้:

curl -X POST https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-opus-5",
    "max_tokens": 1024,
    "messages": [{
      "role": "user",
      "content": [
        {"type": "text", "text": "Summarize this document."},
        {"type": "document", "source": {"type": "file", "file_id": "file_011CNha8iCJcU1wXNR6q4V8w"}}
      ]
    }]
  }'

บล็อก document ยังรับฟิลด์เสริมอย่าง title, context และ citations ได้ด้วย ดังนั้นคุณจึงเปิดการแสดง citation กับไฟล์ที่อัปโหลดได้ สำหรับรูปภาพ ให้สลับชนิดบล็อกเป็น image โดยใช้โครง source แบบเดียวกัน สำหรับสเปรดชีต, CSV ที่คุณต้องการให้วิเคราะห์มากกว่าอ่านตรง ๆ หรือรูปแบบใดก็ตามที่บล็อก document ไม่รองรับ ให้ใช้ container_upload เพื่อส่งไฟล์ให้ code execution tool

หมายเหตุเรื่องรูปแบบหนึ่ง: .docx และ .xlsx ไม่ได้รับการรองรับโดยบล็อก document โดยตรง ให้แปลงไฟล์ Word เป็น PDF เพื่อคงการแยกวิเคราะห์รูปภาพและ citation ไว้ หรือดึงข้อความล้วนออกมาแล้วส่งแบบ inline

การดาวน์โหลดไฟล์ที่สร้างขึ้น

endpoint สำหรับดาวน์โหลดมีไว้สำหรับผลลัพธ์ ไม่ใช่ข้อมูลนำเข้า เมื่อ Claude สร้างแผนภูมิด้วย code execution หรือสร้างสเปรดชีตผ่าน skill คำตอบจะบรรจุ file_id ไว้ในบล็อก bash_code_execution_tool_result ID นั้นสามารถดาวน์โหลดได้:

curl "https://api.anthropic.com/v1/files/$FILE_ID/content" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  --output chart.png

การพยายามดาวน์โหลดไฟล์ที่คุณอัปโหลดเองจะคืนค่า 400 ให้ตรวจดูแฟล็ก downloadable ในข้อมูลเมตาก่อนจะเขียนตรรกะ retry ครอบส่วนนี้ เพราะจะช่วยประหยัดตั๋วขอความช่วยเหลือได้หนึ่งใบ วงจรอัปโหลดเข้า-สร้างออกนี้คือแกนหลักของเวิร์กโฟลว์ Skills API ที่เพิ่งเปิด GA ซึ่ง skills สร้างเอกสาร Office ที่คุณดึงลงมาผ่าน endpoint เดียวกันนี้ คู่มือ Claude Skills ของเราอธิบายว่า skills คืออะไรและทำงานอย่างไร

การหมดอายุและวงจรชีวิตของไฟล์

ไฟล์จะคงอยู่จนกว่าคุณจะลบ หรือจนถึงเวลาหมดอายุที่คุณกำหนดตอนอัปโหลด:

ส่ง expires_in_seconds เป็นฟิลด์ฟอร์มตอนอัปโหลด ช่วงที่ใช้ได้: 3,600 (1 ชั่วโมง) ถึง 7,776,000 (90 วัน) กำหนดได้ครั้งเดียวและเปลี่ยนภายหลังไม่ได้
เมื่อผ่าน expires_at ไปแล้ว การดาวน์โหลดเนื้อหาจะคืนค่า 404 และคำขอ Messages ใดที่อ้างอิงไฟล์นี้จะล้มเหลวก่อนถึงขั้น inference
ข้อมูลเมตายังอ่านได้นานถึง 30 วันหลังหมดอายุ และไฟล์ที่หมดอายุยังปรากฏในผลลัพธ์การ list ในช่วงเวลานั้น ให้เทียบ expires_at กับเวลาปัจจุบันตอนกรองข้อมูล
การลบไฟล์จะลบทันทีและย้อนกลับไม่ได้ เนื้อหาที่หมดอายุจะถูกปลดจากโควตาพื้นที่จัดเก็บของคุณ แต่อาจถูกเก็บไว้ชั่วคราวเพื่อการตรวจสอบด้านความปลอดภัย ดังนั้นการหมดอายุจึงเป็นเครื่องมือจัดการวงจรชีวิต ไม่ใช่กลไกการลบที่รับประกันได้

โมเดลความปลอดภัย: ไฟล์ผูกกับขอบเขต workspace

นี่คือจุดที่แหลมคมที่สุดของ API ทั้งชุด ไฟล์ที่อัปโหลดสามารถเข้าถึงได้โดยทั้ง workspace ของคุณ ไม่ได้จำกัดขอบเขตไว้ที่ผู้ใช้ปลายทาง บทสนทนา หรือเซสชันใด ๆ API key ใดก็ตามใน workspace เดียวกันสามารถอ่านไฟล์ใดก็ได้ที่อัปโหลดไว้ที่นั่น และ key ทั้งหมดจะใช้ Default Workspace ขององค์กรคุณร่วมกัน เว้นแต่คุณจะกำหนดให้ไปอยู่ที่อื่น

กฎที่ใช้ได้จริง:

ห้ามรับค่า file_id จากผู้ใช้ปลายทางเด็ดขาด ID ที่ผู้ใช้ส่งมาจะทำให้ผู้ใช้คนหนึ่งของแอปคุณอ่านไฟล์ที่อัปโหลดโดยผู้ใช้อีกคนได้ ให้ถือว่า file ID เป็นการอ้างอิงฝั่งเซิร์ฟเวอร์ และเก็บการแมปผู้ใช้กับไฟล์ไว้ในฐานข้อมูลของคุณเอง
สร้างระบบ multi-tenant อยู่หรือเปล่า? ใช้หนึ่ง workspace ต่อหนึ่ง tenant workspace คือขอบเขตการแยกข้อมูล แต่ละองค์กรมี workspace ได้สูงสุด 100 แห่ง และทีมดูแลบัญชีของ Anthropic สามารถเพิ่มให้ได้

หากคุณติดตาม API key แยกตาม tenant เพื่อการคิดต้นทุนอยู่แล้ว (หัวข้อที่เราลงรายละเอียดไว้ใน วิธีลดค่าใช้จ่าย Claude API) การจัดวาง workspace แบบเดียวกันนี้จะให้การแยกไฟล์แก่คุณฟรี ๆ

ข้อจำกัดและการคิดค่าบริการ

ตัวเลขที่ต้องใช้ในการออกแบบ:

ข้อจำกัด	ค่า
ขนาดไฟล์สูงสุด	500 MB
พื้นที่จัดเก็บระดับองค์กร	1 TB
Rate limit ของ File API	~500 คำขอ/นาที
ความยาวชื่อไฟล์	1 ถึง 255 ตัวอักษร
ช่วงเวลาหมดอายุ	1 ชั่วโมง ถึง 90 วัน

การคิดค่าบริการเป็นมิตร: การอัปโหลด ดาวน์โหลด แสดงรายการ และลบไฟล์นั้นฟรีทั้งหมด คุณจ่ายเฉพาะเมื่อเนื้อหาไฟล์เข้าสู่คำขอ Messages ซึ่งคิดราคาเป็น input token ปกติ PDF 100 หน้า ที่อ้างอิงในสิบคำขอจะเสียค่า input token เท่ากับสิบเท่าของครั้งเดียว Files API ช่วยประหยัดแบนด์วิดท์และความซับซ้อนฝั่งไคลเอนต์ ไม่ใช่ประหยัด token หากต้องการประหยัดฝั่ง token ให้ใช้การอ้างอิงไฟล์คู่กับ prompt caching

ระวังข้อผิดพลาดเหล่านี้: 413 เมื่อไฟล์เกิน 500 MB, 400 เมื่อองค์กรของคุณชนเพดาน 1 TB, 400 เมื่อชนิดของไฟล์ไม่ตรงกับ content block (เช่น ส่งรูปภาพในบล็อก document) และ 404 สำหรับ ID ที่อยู่นอก workspace ของคุณ

ให้ Claude Code ทดสอบ Files API ด้วย Apidog CLI

Files API เป็นโฟลว์ที่มีหลายขั้นตอนและมีสถานะ ดังนั้นจึงควรมี regression test ไม่ใช่แค่ประวัติคำสั่งใน shell Claude Code หรือ coding agent ใด ๆ สามารถสร้างและรันเทสต์นั้นผ่าน Apidog CLI ตั้งค่าครั้งเดียว:

npm install -g apidog-cli@latest
apidog login --with-token <YOUR_TOKEN>
npx -y skills add https://apidog.com   # pick your agent when prompted

โทเคนได้จาก Apidog ภายใต้ Account Settings, API Access Token จากนั้นส่งพรอมป์ต์เดียวให้ agent:

Use Apidog CLI on project <id>. Add the Files API endpoints (upload, list,
metadata, download, delete) and POST /v1/messages, with x-api-key from
{{ANTHROPIC_API_KEY}} and the anthropic-version header. Build a test scenario:
upload with expires_in_seconds=3600 and assert expires_at is set, save the id
as claude_file_id, reference it in a Messages call and assert 200, delete it,
then assert the metadata call returns 404. Run it and summarize any failures.

คำสั่งที่ agent รัน ตรวจสอบเทียบกับ Apidog CLI 2.2.7:

apidog cli-schema get endpoint-create
apidog endpoint create --project <id> --file files-upload.json
apidog test-scenario create --project <id> --name "Files API lifecycle" --priority 1
apidog test-scenario import-steps <scenarioId> --project <id> --source endpoint \
  --ids <uploadId>,<messagesId>,<deleteId>,<metadataId> --sync manual
apidog cli-schema validate test-scenario-update --file lifecycle.json
apidog test-scenario update <scenarioId> --project <id> --file lifecycle.json
apidog run -t <scenarioId> --project <id> -e <envId> \
  --env-var "ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY" -r cli,json

agent จะทำ endpoint create ซ้ำสำหรับแต่ละ endpoint แล้วเขียนการดึงตัวแปรและ assertions ลงใน scenario ก่อนรัน การสลับไฟล์เทสต์ในภายหลังจึงหมายถึงการแก้ขั้นตอนอัปโหลดเพียงจุดเดียว ไม่ใช่ทุกคำขอ ลองขอ mock ของผลลัพธ์การอัปโหลดด้วย (apidog mock create) ทีมฟรอนต์เอนด์ก็จะได้โครง JSON ก่อนที่ backend proxy ของคุณจะมีอยู่จริง บรรทัด apidog run เดียวกันที่เปลี่ยนเป็น -r junit ก็ใส่เข้า CI ได้เลย คู่มือ Apidog CLI ใน Claude Code ของเราครอบคลุมการตั้งค่า agent แบบครบวงจร

คำถามที่พบบ่อย

ยังต้องใช้ beta header อยู่ไหม? ไม่ต้อง ตั้งแต่เปิด GA เมื่อวันที่ 20 สิงหาคม 2026 Files API ทำงานบน Claude API ด้วย header มาตรฐาน x-api-key และ anthropic-version หาก SDK หรือ proxy ของคุณยังปักหมุด files beta header แบบเก่าไว้ ให้ลบออกตอนอัปเกรด

อัปเดตเนื้อหาไฟล์ได้ไหม? ไม่ได้ ไฟล์ไม่สามารถแก้ไขได้หลังอัปโหลด ให้อัปโหลดไฟล์ใหม่ ชี้การอ้างอิงของคุณไปที่ ID ใหม่ แล้วลบไฟล์เก่าทิ้ง

Files API ใช้ได้บน Bedrock หรือ Vertex AI ไหม? ไม่ได้ มันอยู่บน Claude API, Claude Platform on AWS (beta) และ Microsoft Foundry ที่ใช้การดีพลอยแบบ Hosted on Anthropic บน Bedrock และ Vertex คุณยังต้องส่งเนื้อหาแบบ inline base64 อยู่

Files API เป็นตัวเดียวกับที่ Skills API ใช้สำหรับผลลัพธ์หรือเปล่า? ใช่ skills และ code execution tool เขียนเอกสารที่สร้างขึ้นลงในไฟล์สโตร์เดียวกัน และคุณดาวน์โหลดผ่าน GET /v1/files/{file_id}/content ฝั่ง Skills API ของเวิร์กโฟลว์นี้ เข้ากันได้ดีกับการทดสอบอัตโนมัติ

สรุปปิดท้าย

การเปิด GA ของ Files API ตัดข้ออ้างสุดท้ายในการยัดเอกสารเดิมเป็น base64 ลงในทุกคำขอออกไป อัปโหลดครั้งเดียว อ้างอิงด้วย ID กำหนดเวลาหมดอายุ และเก็บไฟล์ของแต่ละ tenant ไว้ใน workspace แยกกัน พื้นผิวของ API มีเพียงห้า endpoint และทุกตัวทดสอบได้ภายในไม่กี่นาที: ให้ coding agent ของคุณเขียนสคริปต์โฟลว์ด้วย Apidog CLI เชื่อม file_id ผ่านตัวแปร และเช็กวงจรชีวิตทั้งหมดเข้า CI ก่อนที่ผู้ใช้ของคุณจะเจอ edge case แทนคุณ