Claude Files API: Bir Kez Yükle, Her Yerde Referans Ver (GA Rehberi)

Claude Files API, bir dosyayı https://api.anthropic.com/v1/files adresine bir kez yüklemenize, karşılığında bir file_id almanıza ve içeriği her seferinde yeniden göndermek yerine herhangi bir Messages isteğinde bu ID'ye başvurmanıza olanak tanır. 20 Ağustos 2026 itibarıyla Claude Platform'da genel kullanıma sunulmuştur: beta başlığı yok, organizasyon başına 1 TB depolama ve beta sürümünden beş kat daha yüksek hız limitleri. Anthropic bu değişikliği üretim ajanları gönderisinde bilgisayar kullanımı, tarayıcı aracı ve Skills API'nin genel kullanıma sunulmasıyla birlikte duyurdu.

Bu kılavuz tüm yaşam döngüsünü kapsar: yükleme, mesajlarda dosyalara başvurma, oluşturulan çıktıları indirme, süre sonu, çalışma alanı güvenlik modeli ve üretimde karşılaşacağınız limitler. Buradaki her adım bir HTTP çağrısı olduğundan, kodlama ajanınız tüm akışı bir dizi tek seferlik curl komutu yerine bir Apidog CLI test senaryosuna dönüştürebilir.

Files API ne yapar

Files API, Claude API için bir kez oluştur, birçok kez kullan depolama katmanıdır. Belirli bir maliyeti çözer: uygulamanız yüzlerce istek boyunca aynı 40 sayfalık PDF hakkında sorular soruyorsa, bu PDF'i her istekte yeniden yüklemek bant genişliğini israf eder ve istemci kodunuzu karmaşıklaştırır. Files API ile şunları yaparsınız:

• Bir dosyayı Anthropic'in deposuna Yükleyin ve benzersiz bir file_id alın
• Messages isteklerinde bir içerik bloğu aracılığıyla bu ID'ye Başvurun
• Skills veya kod yürütme aracının oluşturduğu dosyaları (grafikler, elektronik tablolar, sunumlar) İndirin
• Her şeyi listeleme, meta veri alma ve silme işlemleriyle Yönetin

Uç nokta yüzeyi küçüktür:

Tümü standart x-api-key ve anthropic-version: 2023-06-01 başlıklarıyla çalışır. Messages API'de yeniyseniz, Claude Opus 5 API kılavuzumuz kimlik doğrulama ve istek şeklinin temellerini kapsar.

GA'da neler değişti

Files API aylarca bir başlığın arkasında beta sürümünde kaldı. 20 Ağustos 2026 GA sürümü, üretim planlaması için önemli olan dört şeyi değiştirdi:

1. Beta başlığı yok. İstekler Claude API'de standart başlıklarla çalışır.
2. 5 kat daha yüksek hız limitleri. Dosya işlemleri artık dakikada yaklaşık 500 isteğe izin verir, satış yoluyla daha yüksek limitler mevcuttur.
3. Organizasyon başına 1 TB depolama, dosya başına 500 MB üst sınırla.
4. Daha geniş platform kapsamı. Files API doğrudan Claude API üzerinde, beta sürümünde AWS üzerindeki Claude Platform'da ve Anthropic'te Barındırılan bir dağıtım kullanırken Microsoft Foundry'de çalışır. Amazon Bedrock veya Google Cloud Vertex AI'da mevcut değildir ve sıfır veri saklama sözleşmeleri için uygun değildir. Katı bir saklama politikanız varsa buna göre planlayın.

Dosya yükleme

Yüklemeler JSON değil, multipart form istekleridir:

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"

Yanıt, dosyaya daha sonra başvurmak için ihtiyacınız olan her şeyi verir:

{
  "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
}

İki alan dikkat gerektirir. Yüklediğiniz her şey için downloadable değeri false'tur; yalnızca Claude'un skills veya kod yürütme yoluyla oluşturduğu dosyalar geri indirilebilir. Ve expires_at değeri, yükleme sırasında bir süre sonu belirlemediğiniz sürece null'dur (aşağıda buna daha fazla değineceğiz).

Aşağıdaki Apidog CLI testinde, yükleme adımı id değerini bir değişken olarak kaydeder, böylece sonraki her istek sabit kodlanmış bir dize yerine {{claude_file_id}} değerine başvurur.

Mesajlarda dosyalara başvurma

Yüklendikten sonra dosya, türüne bağlı olarak üç içerik bloğu türünden biri aracılığıyla bir Messages isteğine eklenir:

Bir PDF özetleme isteği şöyle görünür:

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 bloğu ayrıca isteğe bağlı title, context ve citations alanlarını kabul eder, böylece yüklenen dosya için alıntı çıktısını etkinleştirebilirsiniz. Görüntüler için blok türünü aynı source şekliyle image olarak değiştirin. Elektronik tablolar, okunmak yerine analiz edilmesini istediğiniz CSV'ler veya document bloğunun kabul etmediği herhangi bir format için dosyayı kod yürütme aracına vermek üzere container_upload kullanın.

Bir format notu: .docx ve .xlsx, document bloğu tarafından doğrudan desteklenmez. Görüntü ayrıştırma ve alıntıları korumak için Word dosyalarını PDF'e dönüştürün veya düz metni çıkarıp satır içi olarak gönderin.

Oluşturulan dosyaları indirme

İndirme uç noktası girdi için değil, çıktı için vardır. Claude kod yürütme ile bir grafik oluşturduğunda veya bir skill aracılığıyla bir elektronik tablo ürettiğinde, yanıt bash_code_execution_tool_result bloğunun içinde bir file_id içerir. Bu ID indirilebilir:

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

Yüklediğiniz bir dosyayı indirmeye çalışmak 400 döndürür. Bunun etrafında yeniden deneme mantığı kurmadan önce meta verilerdeki downloadable bayrağını kontrol edin; bu bir destek talebini kurtarır. Bu yükle-içeri, oluştur-dışarı döngüsü, yeni GA olan Skills API iş akışının bel kemiğidir; burada skills, aynı uç nokta üzerinden indirdiğiniz Office belgelerini üretir. Claude Skills kılavuzumuz skills'in ne olduğunu ve nasıl yürütüldüğünü kapsar.

Süre sonu ve dosya yaşam döngüsü

Dosyalar siz onları silene kadar veya yükleme sırasında belirlediğiniz bir süre sonuna kadar kalıcıdır:

• Yükleme sırasında bir form alanı olarak expires_in_seconds geçirin. Geçerli aralık: 3.600 (1 saat) ila 7.776.000 (90 gün). Bir kez ayarlanır ve sonradan değiştirilemez.
• expires_at geçtikten sonra içerik indirmeleri 404 döndürür ve dosyaya başvuran herhangi bir Messages isteği çıkarım öncesinde başarısız olur.
• Meta veriler süre sonundan sonra 30 güne kadar okunabilir kalır ve süresi dolmuş dosyalar bu pencere boyunca liste yanıtlarında görünmeye devam eder. Filtrelerken expires_at değerini geçerli zamanla karşılaştırın.
• Bir dosyayı silmek onu hemen kaldırır ve geri alınamaz. Süresi dolmuş içerik depolama kotanızdan serbest bırakılır ancak güvenlik incelemesi için kısa süreliğine saklanabilir, bu nedenle süre sonu bir yaşam döngüsü aracıdır, garantili silme kontrolü değildir.

Güvenlik modeli: dosyalar çalışma alanına kapsamlıdır

Bu, tüm API'deki en keskin kenardır. Yüklenen dosyalar, bir son kullanıcıya, konuşmaya veya oturuma kapsamlı olmak yerine tüm çalışma alanınıza erişilebilir. Aynı çalışma alanındaki herhangi bir API anahtarı, oraya yüklenen herhangi bir dosyayı okuyabilir ve anahtarları başka bir yere atamadığınız sürece tüm anahtarlar organizasyonunuzun Varsayılan Çalışma Alanını paylaşır.

Pratik kurallar:

• Son kullanıcılardan asla file_id değerleri kabul etmeyin. Kullanıcı tarafından sağlanan bir ID, uygulamanızın bir kullanıcısının başka bir kullanıcının yüklemelerini okumasına olanak tanır. Dosya ID'lerini sunucu tarafı referanslar olarak değerlendirin ve kullanıcı-dosya eşlemesini kendi veritabanınızda tutun.
• Çok kiracılı mı kuruyorsunuz? Kiracı başına bir çalışma alanı. Çalışma alanı yalıtım sınırıdır. Her organizasyon 100 çalışma alanına kadar alır ve Anthropic'in hesap ekipleri bunu yükseltebilir.

Maliyet atfı için kiracı başına API anahtarlarını zaten takip ediyorsanız (Claude API faturanızı nasıl düşürürsünüz yazımızda bu konuyu derinlemesine inceliyoruz), aynı çalışma alanı düzeni size dosya yalıtımını bedavaya sağlar.

Limitler ve faturalandırma

Buna göre inşa edeceğiniz sayılar:

Faturalandırma cömerttir: dosya yükleme, indirme, listeleme ve silme ücretsizdir. Yalnızca dosya içeriği bir Messages isteğine girdiğinde ödeme yaparsınız, burada normal girdi token'ları olarak fiyatlandırılır. On istekte başvurulan 100 sayfalık bir PDF, aynı girdi token'larına on kez mal olur; Files API size bant genişliği ve istemci karmaşıklığı tasarrufu sağlar, token harcaması değil. Token tarafında tasarruf etmek için dosya referanslarını prompt caching ile eşleştirin.

Bu hatalara dikkat edin: bir dosya 500 MB'ı aştığında 413, organizasyonunuz 1 TB tavanına ulaştığında 400, bir dosyanın türü içerik bloğuyla eşleşmediğinde 400 (örneğin bir document bloğundaki görüntü) ve çalışma alanınızın dışındaki ID'ler için 404.

Claude Code'un Files API'yi Apidog CLI ile test etmesine izin verin

Files API çok adımlı, durum bilgili bir akıştır, bu yüzden shell geçmişini değil bir regresyon testini hak eder. Claude Code veya herhangi bir kodlama ajanı bu testi Apidog CLI aracılığıyla oluşturup çalıştırabilir. Bir kez kurun:

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

Token, Apidog'da Hesap Ayarları, API Erişim Token'ı altından alınır. Ardından ajana tek bir komut verin:

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.

Apidog CLI 2.2.7'ye göre kontrol edilen çalıştırdığı komutlar:

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

Ajan her uç nokta için endpoint create komutunu tekrarlar, ardından çalıştırmadan önce değişken çıkarımını ve doğrulamaları senaryoya yazar. Daha sonra test dosyalarını değiştirmek, her isteği değil tek bir yükleme adımını değiştirmek anlamına gelir. Yükleme yanıtının bir mock'unu da isteyin (apidog mock create), böylece frontend ekibi backend proxy'niz var olmadan önce JSON şeklini alır. -r junit ile aynı apidog run satırı CI'ya girer; Claude Code'da Apidog CLI kılavuzumuz ajan kurulumunu baştan sona kapsar.

SSS

Hâlâ bir beta başlığına ihtiyacım var mı? Hayır. 20 Ağustos 2026 GA'dan bu yana Files API, Claude API'de standart x-api-key ve anthropic-version başlıklarıyla çalışır. SDK'nız veya proxy'niz hâlâ eski files beta başlığını sabitliyorsa, yükseltme yaparken onu kaldırın.

Bir dosyanın içeriğini güncelleyebilir miyim? Hayır. Dosyalar yüklemeden sonra değişmezdir. Yeni bir dosya yükleyin, referanslarınızı yeni ID'ye yönlendirin ve eskisini silin.

Files API Bedrock veya Vertex AI'da çalışır mı? Hayır. Claude API'de, AWS üzerindeki Claude Platform'da (beta) ve Anthropic'te Barındırılan bir dağıtımla Microsoft Foundry'de çalışır. Bedrock ve Vertex'te hâlâ satır içi base64 içeriğe ihtiyacınız vardır.

Files API, Skills API'nin çıktılar için kullandığı şeyin aynısı mı? Evet. Skills ve kod yürütme aracı, oluşturdukları belgeleri aynı dosya deposuna yazar ve bunları GET /v1/files/{file_id}/content aracılığıyla indirirsiniz. Bu iş akışının Skills API tarafı, otomatik testlerle iyi uyum sağlar.

Sonuç

Files API'nin GA olması, aynı belgeyi her isteğe base64 ile tıkıştırmak için son bahaneyi ortadan kaldırıyor. Bir kez yükleyin, ID ile başvurun, bir süre sonu belirleyin ve kiracı dosyalarını ayrı çalışma alanlarında tutun. API yüzeyi beş uç noktadır ve her biri dakikalar içinde test edilebilir: kodlama ajanınıza akışı Apidog CLI ile betiklemesini söyleyin, file_id değerini bir değişken aracılığıyla zincirleyin ve kullanıcılarınız uç durumları sizin için bulmadan önce tüm yaşam döngüsünü CI'ya kaydedin.