Sohbet arayüzünüz, her yanıtın altında küçük bir “yapay zeka tarafından oluşturuldu” rozeti taşıyor. Güzel. Şimdi bir iş ortağı ekibi, toplu bir işten /summarize uç noktanızı çağırıyor, çıktıyı bir veritabanına yazıyor ve bunu müşteri odaklı bir raporda gösteriyor. Rozetiniz kimseye yardımcı olmadı.
Yapay zeka ifşasının sürekli içine düştüğü boşluk işte bu. İfşa, bir kullanıcı arayüzü kararı olarak tasarlandığı için, kendi ön ucunuzun sınırlarında kalıyor. Makine tüketicileri hiçbir şey alamıyor ve buna en çok ihtiyaç duyanlar da onlar, çünkü bir yanıta bakıp bir modelden geldiğini anlayamazlar.
2 Ağustos 2026'dan bu yana, AB Yapay Zeka Yasası'nın 50. Maddesi bunu birçok ekip için somut hale getirdi. Anthropic gibi model sağlayıcıları çıktılarını model düzeyinde işaretler, ancak insanlara yapay zeka ile uğraştıklarını söyleme görevi sistemi dağıtan kişiye aittir. API'niz ikisi arasında yer alıyorsa, arayanlarınızın uyumlu olup olmamasının nedeni sizsiniz.
İfşayı arayüz yerine sözleşmeye nasıl dahil edeceğiniz aşağıdadır: ne döndürülecek, nereye konulacak, nasıl belgelenecek ve bir sonraki yeniden düzenlemeden sağ çıkması için nasıl test edilecek. Apidog, bunun tasarım, belge ve test taraflarını tek bir yerde ele alır.
Yanıtın içeriği
Üç şey ve üç farklı soruyu yanıtlıyorlar.
Bu oluşturuldu mu? Bir boolean, daha iyisi bir enum. ai_generated: true iyi bir başlangıçtır, ancak generation: "synthetic" | "assisted" | "human" daha kullanışlıdır, çünkü “Claude bir insanın taslağını sıkılaştırdı” ile “Claude her şeyi kendi yazdı” gerçekten farklıdır ve Madde 50'nin muafiyetleri bunları farklı şekilde ele alır.
Ne tarafından? Sağlayıcı ve model kimliği. Arayanlarınızın kendi model politikaları olabilir ve modelleri değiştiren bir yedekleme, çıktı ile ne yapmalarına izin verildiğini değiştirir.
Gerçekten ne biliyoruz? Kontrol ettiyseniz kaynak durumu. Bunu üretim bayrağından ayrı tutun, çünkü “bunu biz ürettik” sahip olduğunuz bir gerçektir ve “bir C2PA manifestini doğruladık” yaptığınız bir gözlemdir.
Tutarlı bir yapı:
{
"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
}
}
Savunmaya değer iki detay.
human_review Madde 50(4)'ten dolayı var. Kamu yararı taşıyan konularda halkı bilgilendirmek amacıyla yayınlanan yapay zeka tarafından üretilmiş metinler, insan incelemesinden veya editör sorumluluğu olan bir kişi tarafından editöryal kontrolden geçmediği sürece ifşa edilmelidir. Platformunuz bir insanın bir taslağı onayladığını kaydederse, bu gerçek yanıtta yer almalıdır, çünkü arayanınızın bir etikete ihtiyaç duyup duymaması arasındaki fark budur.
provenance.status ikiden fazla duruma sahiptir. verified (doğrulandı), absent (eksik), invalid (geçersiz) ve unchecked (kontrol edilmedi) hepsi farklı şeyler ifade eder ve bunları bir boolean'a indirgemek faydalı olanları ortadan kaldırır. Doğrulama hizmetinizdeki bir kesinti, temiz bir sonuçla aynı görünmemelidir.
Başlıklar mı, gövde mi?
Her ikisi de, farklı tüketiciler için.
Gövde gerçeği taşır. Depolanan, günlüğe kaydedilen, tekrar oynatılan ve aşağı akışa iletilen şey budur. Bir arayan yalnızca ayrıştırılmış JSON'ı tutuyorsa, ifşa orada olmalıdır.
Bir başlık uç noktalarda yardımcı olur. Gövdenizi asla ayrıştırmayan bir proxy, ağ geçidi veya günlük katmanı hala bir başlık üzerinden yönlendirme yapabilir veya kaydedebilir. Ayrıca, düz metin veya ikili uç nokta gibi JSON olmayan bir yanıtta ifşa için tek mantıklı yerdir.
HTTP/1.1 200 OK
Content-Type: application/json
X-AI-Generated: synthetic
X-AI-Model: anthropic/claude-opus-5
Başlıklar için iki kural. Her uç noktada tutarlı tutun, çünkü bazı rotalarda görünen bir başlık, hiçbirinde görünmeyenden daha kötüdür. Ve gövde ile çelişirse başlığı asla yetkili kabul etmeyin; birini standart olarak seçin, hangisi olduğunu belgeleyin ve testlerinizin bunu uygulamasını sağlayın.
Akış yanıtları için, ifşayı ilk olaya veya yanıt başlıklarına koyun. Bir token'ı işlemeye başlayan bir arayan, ne işlediğini bilmek için bir sonraki kısma (trailer) beklememelidir. Genel olarak başlık tasarımında yeniyseniz, HTTP başlıkları nedir temel konuları kapsar.
Spesifikasyona ekleyin
OpenAPI tanımınızda olmayan bir ifşa alanı bir kuraldır ve kurallar çürür. Her yapay zeka destekli uç noktanın aynı yapıyı kullanması için onu yeniden kullanılabilir bir şema olarak 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 her yerde referans verin ve model çıktısı içerebilen herhangi bir yanıtta ai öğesini zorunlu bir özellik yapın. Zorunluluk önemlidir: isteğe bağlı bir alan, arayanın savunmacı kod yazması gereken bir alandır ve çoğu bunu yapmayacaktır.
İki ek fayda. Oluşturulan belgeleriniz artık alanı her tüketiciye, kimsenin bir wiki sayfası yazmasına gerek kalmadan açıklıyor. Ve spesifikasyon doğrulama, aslında meydana gelen hata modu olan ortadan kaybolduğu günü yakalayacaktır. OpenAPI spesifikasyonları nasıl doğrulanır doğrulama tarafını kapsar ve CI'da bozucu değişiklikleri engellemek için OpenAPI diff, birinin sessizce onu isteğe bağlı hale getirmesini yakalayacaktır.
İnsanların unuttuğu yollar
İfşa alanları, kimsenin düşünmediği rotalarda kaybolur. Açıkça kontrol edilmesi gereken dört tane:
Önbelleğe alınmış yanıtlar. İfşa eklenmeden önce gövdeyi depolayan bir önbellek katmanı, TTL süresi boyunca işaretsiz çıktı sunacaktır. Model çıktısı artı yeniden oluşturduğunuz bir sarıcıyı değil, tam yanıtı önbelleğe alın.
Hata ve kısmi yanıtlar. Kısmi bir özet döndüren bir zaman aşımı hala model çıktısı döndürüyor demektir. Hata zarfınızın farklı bir şekli varsa, o da bu alanı içermelidir.
Toplu ve webhook yükleri. Asenkron teslimat genellikle farklı kod tarafından oluşturulan daha ince bir şema kullanır. Bu, alanın en sık eksik olduğu yerdir.
Geri dönüş yolları. Birincil model başarısız olduğunda ve geri dönüş yaptığınızda, model değeri de eşleşmelidir. Bir ifşa bloğunda sabit kodlanmış bir model dizesi, gerçekleşmeyi bekleyen bir yalandır.
Dördünün de çözümü aynıdır: ifşayı, model çıktısının yanıt nesnenize girdiği noktada ekleyin, başarılı yolu serileştirdiğiniz noktada değil.
Bir garanti gibi test edin
Bir ifşa alanı, arayanlarınıza verilen bir sözdür. Test edilmeyen sözler belgelemedir.
Beş iddia bunun çoğunu kapsar ve bunlar sıradan API testleridir.
1. Alan, yapay zeka destekli her rotada mevcuttur.
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 gövde ile eşleşir.
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ğırdığınız modelle eşleşir. Sessiz geri dönüşleri yakalayan budur. Çıktının yukarı akışta filigranlı olup olmadığı model kimliğine bağlıdır, bu yüzden Claude'un API filigranı, model sabitlemeyi bir performans detayı yerine bir uyumluluk detayı haline getirir.
4. Önbelleğe alınmış yol hala ifşa eder. İki kez çağırın, önbellekten gelen ikinci yanıtın, ilk yanıtla aynı ifşaya sahip olduğunu doğrulayın.
5. Hata yolu hala ifşa eder. Bir zaman aşımı veya aşağı akışta bir hatayı zorlayın ve zarfın hala alanı taşıdığını doğrulayın.
Bunları bir test senaryosunda gruplayın, OpenAPI tanımınıza karşı şema doğrulaması ekleyin ve CI'da apidog-cli'dan çalıştırın:
apidog run --access-token "$APIDOG_ACCESS_TOKEN" \
-t "$DISCLOSURE_SCENARIO_ID" -e "$APIDOG_ENV_ID" -r cli,html
Bir iddia başarısız olduğunda sıfır olmayan bir kodla çıkar, böylece alanı bırakan bir birleştirme, dağıtım yerine derlemeyi başarısız kılar. Tam kanal kurulumu GitHub Actions'ta API testlerini otomatikleştirme bölümündedir ve genel iddia desenleri API iddiaları bölümündedir. Kendi uç noktalarınıza karşı senaryoyu oluşturmak için Apidog'u indirin.
Arayanların baktığı yerde belgeleyin
İki kitle, iki yer.
Referansta. Şema açıklaması, doğru yazarsanız işin çoğunu yapar. assisted'in ürününüzde ne anlama geldiğini söyleyin, soyut olarak değil. Bir etikete ihtiyaç duyup duymadığına karar veren bir arayan, yasal bir karar vermek için o cümleyi okuyordur.
Kısa bir politika sayfasında. Hangi uç noktaların model çıktısı döndürebileceğini, hangi modelleri kullandığınızı, insan incelemesi olup olmadığını ve olduğunda ne anlama geldiğini, neyi garanti ettiğinizi ve etmediğinizi kapsayan tek bir sayfa. Referanstan bağlayın. Sürümleyin.
Sınırlamalar konusunda net olun. Claude çıktısını geçirirseniz, metin kendinizin doğrulayamadığı ve Anthropic'in algılamayı açmadığı gömülü bir filigran taşır. Sahip olmadığınız bir doğrulama yeteneğini ima etmektense bunu söylemek daha iyidir. Gerekçe, Claude'un filigranı nasıl tespit edilir bölümündedir.
Etkileşimli belgeler burada normalden daha fazla yardımcı olur, çünkü bir arayan, bir tabloya güvenmek yerine canlı bir yanıtta ifşa alanını görebilir. 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ış bir standart başlık yoktur. Bir ad seçin, belgeleyin, tutarlı tutun ve sözleşmenizin bir parçası olarak değerlendirin.
İfşa başlıkta mı yoksa gövdede mi olmalı? Her ikisi de. Gövde depolanan ve iletilen şeydir. Başlık, proxy'lere, ağ geçitlerine, günlüklere ve JSON olmayan yanıtlara hizmet eder. Çelişmeleri durumunda hangisinin standart olduğunu belgeleyin.
Bunu yasal olarak yapmak zorunda mıyım? Rolünüze ve içeriğinize bağlıdır. Madde 50 yükümlülükleri sağlayıcılar ve dağıtıcılar üzerinde farklılık gösterir ve 50(4), deepfake'ler ve kamu yararı taşıyan metinlerle sınırlıdır ve insan editör kontrolü için bir muafiyet içerir. API geliştiricileri için AB Yapay Zeka Yasası Madde 50 bunu ayrıntılarıyla açıklar. Yasal karar avukatınızındır; teknik uygulama sizindir.
Sağlayıcım çıktısını zaten filigranlıyor. Bu yeterli değil mi? Hayır. Filigran, arayanlarınızın metin için şu anda okuyamadığı makine tarafından okunabilir bir sinyaldir ve bir dağıtıcı olarak kendi ifşa görevlerinizi yerine getirmez. Bir tamamlayıcıdır, bir ikame değil.
Akış yanıtları ne olacak? İfşayı yanıt başlıklarına veya ilk olaya koyun. Arayanlar token'lar geldikçe işler ve sonu beklemek zorunda kalmamalıdır.
Üretim sonrası bir insan tarafından düzenlenen içeriği nasıl ele alırım? assisted ve human_review bunun içindir. Madde 50(4), editör sorumluluğu ile insan incelemesi altında olan içerik için bir muafiyet içerir, bu nedenle bunu doğru bir şekilde kaydetmek tek bir boolean'dan daha değerlidir.
Bu alanı sürümlemeli miyim? Yanıt şemanızın bir parçasıdır, bu yüzden aynen diğerleri gibi sürümleyin. Bir enum değeri eklemek, arayanlarınızın duyması gereken bir değişikliktir ve CI'daki bir spesifikasyon farkı bunu onlara bildirecektir.
Çıkarım
Yapay zeka ifşası bir kullanıcı arayüzü özelliği olarak başarısız olur ve bir sözleşme olarak işlev görür. Yanıta zorunlu bir alan koyun, bir başlıkta yansıtın, OpenAPI spesifikasyonunuzda bir kez tanımlayın ve her zaman kaybolduğu önbelleğe alınmış, hata, toplu iş ve geri dönüş yollarında doğrulayın.
Bu belki bir öğleden sonraki bir iştir ve pazarlamanızdaki bir iddiayı, arayanlarınızın üzerine inşa edebileceği ve testlerinizin uygulayabileceği bir şeye dönüştürür.