API'nize Yapay Zeka Bildirimi Nasıl Eklenir

Sohbet arayüzünüzde her yanıtın altında küçük bir “yapay zeka tarafından oluşturuldu” rozeti olabilir. Ancak bir iş ortağı ekibi toplu işten /summarize uç noktanızı çağırıp çıktıyı veritabanına yazdığında ve müşteri raporunda kullandığında, bu rozetin hiçbir değeri kalmaz.

Apidog'u bugün deneyin

Yapay zeka ifşası yalnızca bir kullanıcı arayüzü kararı olarak tasarlandığında ön ucunuzun sınırlarında kalır. Makine tüketicileri bu bilgiyi alamaz; oysa bir yanıtın modelden üretildiğini programatik olarak anlamaya en çok onların ihtiyacı vardır.

2 Ağustos 2026'dan bu yana AB Yapay Zeka Yasası'nın 50. Maddesi bu konuyu birçok ekip için daha somut hâle getirdi. Anthropic gibi model sağlayıcıları çıktıları model düzeyinde işaretleyebilir; ancak insanlara yapay zeka ile etkileşimde olduklarını bildirme sorumluluğu sistemi dağıtan taraftadır. API'niz bu iki katman arasındaysa, çağıranların uyumluluğunu doğrudan etkilersiniz.

Bu yazıda ifşayı arayüz yerine API sözleşmesine nasıl ekleyeceğinizi ele alacağız: hangi alanların döneceği, nerede taşınacağı, nasıl belgeleneceği ve yeniden düzenlemelerde kaybolmaması için nasıl test edileceği. Apidog, tasarım, dokümantasyon ve test süreçlerini tek yerde yönetmenize yardımcı olur.

Yanıtta hangi bilgiler olmalı?

İfşa verisi üç soruya yanıt vermelidir:

1. Bu içerik üretildi mi?
2. Hangi sağlayıcı ve model tarafından üretildi?
3. İçeriğin kökeni hakkında gerçekten ne doğruladınız?

1. İçerik yapay zeka tarafından mı üretildi?

Basit bir başlangıç için boolean kullanabilirsiniz:

{
  "ai_generated": true
}

Ancak enum kullanmak daha kullanışlıdır:

{
  "generation": "synthetic"
}

Önerilen değerler:

• synthetic: İçerik insan yazarlığı olmadan model tarafından üretildi.
• assisted: İnsan içeriği yazdı; model düzenleme, çeviri veya özetleme yaptı.
• human: Modelin içerik üretiminde rolü olmadı.

Bu ayrım önemlidir. Örneğin, bir modelin insan taslağını düzenlemesi ile metni tamamen üretmesi aynı durum değildir. Madde 50 kapsamındaki istisnalar da bu senaryoları farklı ele alabilir.

2. İçeriği hangi model üretti?

Sağlayıcı ve model kimliğini döndürün. API tüketicilerinin kendi model politikaları olabilir. Birincil model başarısız olduğunda devreye giren model değişimi, çıktının nasıl işlenebileceğini etkileyebilir.

3. Köken bilgisini doğruladınız mı?

Üretim bilgisini köken doğrulamasından ayırın:

• “Bu içeriği biz ürettik” bir gerçektir.
• “C2PA manifestini doğruladık” ise yaptığınız bir gözlemdir.

Önerilen yanıt yapısı:

{
  "id": "sum_4f81a2",
  "content": "The incident affected two regions for 41 minutes...",
  "ai": {
    "generation": "synthetic",
    "vendor": "anthropic",
    "model": "claude-opus-5",
    "human_review": false,
    "generated_at": "2026-08-11T09:14:22Z"
  },
  "provenance": {
    "status": "unchecked",
    "standard": null
  }
}

İki alan özellikle önemlidir:

• human_review: Bir insanın çıktı dönmeden önce inceleme yapıp yapmadığını belirtir. Madde 50(4), kamu yararı taşıyan konularda yayımlanan yapay zeka üretimi metinlerde insan incelemesi ve editöryal sorumluluk durumunu dikkate alır.
• provenance.status: Boolean yerine durum enum'u kullanın. verified, absent, invalid ve unchecked farklı anlamlara gelir. Örneğin doğrulama servisindeki kesinti, temiz bir doğrulama sonucuyla aynı görünmemelidir.

Başlık mı, gövde mi?

Her ikisini de kullanın; çünkü farklı tüketiciler farklı katmanlarda çalışır.

Gövde, kalıcı gerçeği taşır. Veritabanında saklanan, günlüğe yazılan, tekrar oynatılan ve aşağı akış sistemlerine iletilen veri budur. Bir istemci yalnızca ayrıştırılmış JSON saklıyorsa, ifşa bilgisi gövdede bulunmalıdır.

Başlıklar operasyonel katmanlarda faydalıdır. Proxy, ağ geçidi veya log katmanı gövdeyi ayrıştırmadan ifşa bilgisini okuyabilir. Düz metin veya ikili çıktı dönen uç noktalarda ise başlık tek mantıklı seçenek olabilir.

HTTP/1.1 200 OK
Content-Type: application/json
X-AI-Generated: synthetic
X-AI-Model: anthropic/claude-opus-5

Başlık tasarımında iki kural uygulayın:

1. Başlıkları tüm ilgili uç noktalarda tutarlı kullanın.
2. Başlık ile gövde çelişirse hangisinin yetkili kaynak olduğunu açıkça belgeleyin.

Genellikle gövdeyi yetkili kaynak kabul etmek daha güvenlidir. Başlık, gövdedeki değerin operasyonel yansıması olmalıdır.

Akış yanıtlarında ifşayı yanıt başlıklarında veya ilk olayda gönderin. İstemci token işlemeye başlamışsa, ne işlediğini öğrenmek için stream sonundaki trailer'ı beklememelidir. Başlık tasarımına giriş için HTTP başlıkları nedir yazısına bakabilirsiniz.

İfşa şemasını OpenAPI tanımına ekleyin

OpenAPI tanımınızda yer almayan ifşa alanları zamanla kaybolur. Tüm yapay zeka destekli uç noktaların aynı yapıyı kullanması için yeniden kullanılabilir bir şema tanımlayın:

components:
  schemas:
    AiDisclosure:
      type: object
      required: [generation]
      properties:
        generation:
          type: string
          enum: [synthetic, assisted, human]
          description: >
            synthetic = produced by a model with no human authoring.
            assisted = a human authored the content and a model edited,
            translated, or summarised it.
            human = no model involvement.
        vendor:
          type: string
          example: anthropic
        model:
          type: string
          example: claude-opus-5
        human_review:
          type: boolean
          description: >
            True when a person reviewed the output before it was returned
            and an identifiable party holds editorial responsibility.
        generated_at:
          type: string
          format: date-time

Ardından bu şemayı tüm ilgili yanıtlarda referans verin:

components:
  schemas:
    SummarizeResponse:
      type: object
      required: [id, content, ai]
      properties:
        id:
          type: string
        content:
          type: string
        ai:
          $ref: "#/components/schemas/AiDisclosure"

ai alanını zorunlu yapın. İsteğe bağlı alanlar, tüm istemcilerin savunmacı kod yazmasını gerektirir; pratikte çoğu istemci bunu yapmaz.

Bu yaklaşımın iki ek yararı vardır:

• Oluşturulan API dokümantasyonu alanın anlamını her tüketiciye açıklar.
• Şema doğrulaması, alanın yanlışlıkla kaldırıldığı değişiklikleri yakalar.

OpenAPI spesifikasyonları nasıl doğrulanır yazısı doğrulama sürecini; CI'da bozucu değişiklikleri engellemek için OpenAPI diff ise alanın isteğe bağlı hâle getirilmesi gibi sözleşme değişikliklerini yakalamayı kapsar.

Sıklıkla unutulan teslim yolları

İfşa alanları genellikle ana başarılı yanıt yolunda doğru uygulanır; ancak daha az görünür rotalarda kaybolur. En az şu dört yolu test edin:

Önbelleğe alınmış yanıtlar

İfşa alanı eklenmeden önce gövdeyi saklayan bir önbellek, TTL süresi boyunca işaretsiz içerik sunabilir.

Uygulama yaklaşımı: Model çıktısını ve sonradan oluşturulmuş bir yanıt sarmalayıcısını ayrı ayrı önbelleğe almak yerine, tam yanıtı ifşa bilgisiyle birlikte önbelleğe alın.

Hata ve kısmi yanıtlar

Zaman aşımı sonrası kısmi özet dönüyorsanız hâlâ model çıktısı dönüyorsunuz demektir. Hata zarfınız farklı biçimde olsa bile ifşa alanını taşımalıdır.

Toplu işler ve webhook yükleri

Asenkron teslimat akışları genellikle ayrı kod tarafından üretilen daha ince şemalar kullanır. İfşa alanının en sık eksik kaldığı yerlerden biri burasıdır.

Geri dönüş yolları

Birincil model başarısız olduğunda geri dönüş modeli kullanıyorsanız, model alanı gerçek çağrılan modeli göstermelidir. İfşa bloğunda sabit kodlanmış model adı kullanmak yanlış beyana yol açar.

Bu dört senaryonun ortak çözümü şudur:

İfşa bilgisini başarılı HTTP yanıtını serileştirdiğiniz noktada değil, model çıktısının uygulamanızdaki yanıt nesnesine girdiği noktada ekleyin.

İfşayı garanti gibi test edin

İfşa alanı API tüketicilerinize verdiğiniz bir sözdür. Test edilmeyen söz, yalnızca dokümantasyondur.

Aşağıdaki beş kontrol, çoğu uygulama için yeterli başlangıç kapsamı sağlar.

1. Tüm yapay zeka destekli rotalarda alan mevcut mu?

const body = pm.response.json();

pm.test("response carries AI disclosure", function () {
  pm.expect(body).to.have.property("ai");
  pm.expect(body.ai.generation).to.be.oneOf([
    "synthetic",
    "assisted",
    "human"
  ]);
});

2. Başlık ve gövde aynı değeri mi taşıyor?

pm.test("header and body agree", function () {
  pm.expect(pm.response.headers.get("X-AI-Generated"))
    .to.eql(body.ai.generation);
});

3. Bildirilen model gerçekten çağrılan model mi?

Bu test, sessiz geri dönüşleri yakalar. Yukarı akışta filigran uygulanıp uygulanmadığı model kimliğine bağlı olabilir. Bu nedenle Claude'un API filigranı, model sabitlemeyi yalnızca performans değil, uyumluluk konusu da yapar.

Örneğin test ortamında çağrılması beklenen modeli environment değişkeninde tutabilirsiniz:

pm.test("reported model matches expected model", function () {
  pm.expect(body.ai.model).to.eql(pm.environment.get("expected_model"));
});

4. Önbellek yanıtı ifşayı koruyor mu?

Uç noktayı iki kez çağırın. İkinci çağrı önbellekten dönse bile ilk yanıtla aynı ai bilgisini taşıdığını doğrulayın.

5. Hata yolu ifşayı koruyor mu?

Bir zaman aşımını veya aşağı akış hatasını kontrollü olarak tetikleyin. Hata zarfının da ai alanını içerdiğini doğrulayın.

Bu kontrolleri tek bir test senaryosunda gruplayın, OpenAPI şemanıza karşı doğrulama ekleyin ve CI içinde apidog-cli ile çalıştırın:

apidog run --access-token "$APIDOG_ACCESS_TOKEN" \
  -t "$DISCLOSURE_SCENARIO_ID" \
  -e "$APIDOG_ENV_ID" \
  -r cli,html

Bir kontrol başarısız olduğunda komut sıfır olmayan çıkış kodu döndürmelidir. Böylece ifşa alanını kaldıran bir birleştirme, üretime çıkmak yerine CI derlemesini başarısız kılar.

Kanal kurulumu için GitHub Actions'ta API testlerini otomatikleştirme, test ifadeleri için API iddiaları yazılarına bakabilirsiniz. Senaryoyu kendi uç noktalarınıza karşı oluşturmak için Apidog'u indirin.

Dokümantasyonu tüketicinin baktığı yerde sunun

İki kitle için iki dokümantasyon katmanı kullanın.

API referansında

Şema açıklamaları işin büyük kısmını yapar. Ancak açıklamalar ürününüze özgü olmalıdır.

Örneğin assisted için yalnızca “AI destekli” demek yerine, modelin hangi işlemleri yapabileceğini açıkça yazın:

İnsan tarafından yazılan içerik; model tarafından düzenleme, çeviri veya özetleme işlemlerinden geçirilmiştir.

Bu açıklama, API tüketicisinin etikete veya ek bir işleme ihtiyacı olup olmadığına karar vermesine yardımcı olur.

Kısa bir politika sayfasında

Tek bir sürümlenmiş sayfada şu soruları yanıtlayın:

• Hangi uç noktalar model çıktısı döndürebilir?
• Hangi modeller kullanılır?
• İnsan incelemesi uygulanıyor mu?
• Uygulanıyorsa human_review: true tam olarak ne anlama gelir?
• Hangi garantileri veriyorsunuz?
• Hangi garantileri vermiyorsunuz?

Bu sayfayı API referansından bağlayın.

Sınırlamalar konusunda açık olun. Claude çıktısını geçiriyorsanız, metin sizin doğrulayamadığınız ve Anthropic'in algılama özelliğini açmadığı gömülü bir filigran taşıyabilir. Sahip olmadığınız bir doğrulama yeteneğini ima etmek yerine bunu açıkça belirtin. Gerekçe için Claude'un filigranı nasıl tespit edilir yazısına bakabilirsiniz.

Etkileşimli API dokümantasyonu burada özellikle faydalıdır: tüketici yalnızca tablo okumaz, canlı yanıtta ifşa alanını doğrudan görür. Deneme konsolu ile etkileşimli API belgelerini barındırma bu kurulumu kapsar.

Sıkça Sorulan Sorular

X-AI-Generated başlığı bir standart mı?

Hayır. Yapay zeka ifşası için onaylanmış standart bir HTTP başlığı yoktur. Bir ad seçin, belgeleyin, tüm ilgili uç noktalarda tutarlı kullanın ve bunu API sözleşmenizin parçası kabul edin.

İfşa başlıkta mı, gövdede mi olmalı?

Her ikisinde de olmalı. Gövde saklanan ve aşağı akışa iletilen veridir. Başlıklar proxy'ler, ağ geçitleri, log sistemleri ve JSON olmayan yanıtlar için faydalıdır. Çelişki durumunda yetkili kaynağın hangisi olduğunu dokümante edin.

Bunu yasal olarak yapmak zorunda mıyım?

Bu, rolünüze ve içerik türünüze bağlıdır. Madde 50 yükümlülükleri sağlayıcılar ve dağıtıcılar için farklılaşır. Madde 50(4), deepfake'ler ve kamu yararı taşıyan metinler için özel hükümler içerir; insan editör kontrolü için de bir istisna bulunur.

API geliştiricileri için AB Yapay Zeka Yasası Madde 50 ayrıntıları ele alır. Hukuki karar avukatınıza, teknik uygulama ise ekibinize aittir.

Sağlayıcım çıktıyı zaten filigranlıyor. Bu yeterli değil mi?

Hayır. Filigran, istemcilerinizin metinden her zaman okuyamadığı makine tarafından okunabilir bir sinyal olabilir. Ayrıca dağıtıcı olarak size ait ifşa yükümlülüklerinin yerine geçmez. Filigran tamamlayıcıdır, ikame değildir.

Akış yanıtlarında ne yapmalıyım?

İfşayı yanıt başlıklarında veya ilk stream olayında gönderin. İstemciler token'ları gelir gelmez işlemeye başlayabilir; ifşa bilgisini stream sonuna bırakmayın.

Üretimden sonra insan tarafından düzenlenen içeriği nasıl ele almalıyım?

assisted ve human_review alanlarını kullanın. Madde 50(4), editöryal sorumluluk altında insan incelemesinden geçen içerik için istisna içerir. Bu nedenle süreci doğru kaydetmek, tek bir ai_generated boolean değerinden daha değerlidir.

Bu alanı sürümlemeli miyim?

Evet. Bu alan yanıt şemanızın bir parçasıdır ve diğer sözleşme alanları gibi sürümlenmelidir. Enum'a yeni değer eklemek bile tüketicilerinizin bilmesi gereken bir değişiklik olabilir. CI içindeki OpenAPI diff kontrolü bunu görünür kılar.

Sonuç

Yapay zeka ifşası, yalnızca kullanıcı arayüzü özelliği olduğunda başarısız olur; API sözleşmesinin parçası olduğunda ise çalışır.

Uygulama planı basittir:

1. Yanıt gövdesine zorunlu bir ai alanı ekleyin.
2. Aynı bilgiyi uygun HTTP başlıklarında yansıtın.
3. Şemayı OpenAPI tanımında bir kez tanımlayıp her ilgili uç noktada yeniden kullanın.
4. Önbellek, hata, toplu iş, webhook ve geri dönüş yollarını test edin.
5. Testleri CI içinde zorunlu kılın.

Bu, pazarlama ifadesini API tüketicilerinin üzerine inşa edebileceği ve testlerinizin uygulayabileceği somut bir sözleşmeye dönüştürür.