Geliştiriciler için Üretken Yapay Zeka API'si: "Başarılı" Başarısızlıkları Yayına Almayı Durdurun

İsteğiniz başarıyla sonuçlanıyor. Uygulamanın hâlâ kullanılabilir bir görseli yok. Belki yanıt bir görev kimliği içeriyor ya da tamamlanan görselde sayfa için uygun olmayan fazladan bir nesne var.

Geliştiriciler için üretken yapay zeka API'si, uygulamanızın bir modele girdi göndermesini ve üretilen içeriği almasını sağlar. Seçiminizi gerekli girdilerinize, çıktı biçiminize, bekleme sürenize ve kabul kriterlerinize göre yapın. Ardından bir yanıtı kullanıcının kullanabileceği bir şeye dönüştüren görev yönetimini ve kontrolleri kurun.

Bu kılavuz, seçimden teslimata kadar bir görsel iş akışını izler. Bir görev seçim tablosu, birbiriyle uyumlu JavaScript ve Python örnekleri, 3 somut görsel briefi ve bir maliyet çalışma sayfası elde edeceksiniz. Aynı karar süreci, farklı protokoller ve çıktı kontrolleriyle metin ve video için de geçerlidir.

Önemli çıkarımlar

• Görevi ve kabul kriterlerini modelden önce seçin.
• Asenkron görev kimliklerini kaydedin, böylece kesintiye uğrayan iş kaldığı yerden devam edebilsin.
• Reddedilen üretimler dâhil olmak üzere kabul edilen çıktı başına maliyeti ölçün.
• Tamamlanmış bir sonucu göstermeden önce dosyaları ve iş kısıtlarını test edin.

Geliştiriciler İçin Üretken Yapay Zeka API'si: Ne Yapar

Üretimi bir model gerçekleştirir. Bir API, yazılımınızın bu işi nasıl talep edeceğini tanımlar. Bir SDK, arayüzü dile özgü yardımcılarla sarar. Barındırılan bir platform modellere erişimi işletir; kullanıcı deneyimini, izinleri ve sonucu kabul etme kurallarını ise uygulamanız sağlar.

Bu ayrımlar bir ürün sayfasını okurken önemlidir. Görsel üreten bir sohbet uygulaması, geliştirici uç noktasının da aynı girdileri kabul ettiğini göstermez. Kullanışlı bir yöntem sunan bir SDK, altında yatan yanıtı ve hata durumlarını anlama ihtiyacını ortadan kaldırmaz.

Aşağıdaki görev haritasıyla başlayın. Etkileşim sütunu, her sağlayıcının bu modu desteklediğine dair bir vaat değil, değerlendirilecek bir uygulama tasarımını tanımlar.

Görsel üretmek, yüklenen bir görseli analiz etmek ve mevcut bir görseli düzenlemek ayrı yeteneklerdir. Her birini açıkça doğrulayın. Benzer şekilde, bir video uç noktası başlangıç karesini desteklerken rastgele çoklu görsel referanslarını desteklemeyebilir.

Gömlemler (embedding), girdileri getirim ve benzerlik için yararlı vektörlere dönüştürür. Bir yanıt üretilmeden önce ilgili belgelerin bulunmasına yardımcı olabilirler. Kendileri yanıtı üretmez veya getirilen içeriğin iddiaları desteklediğini göstermez.

Pratik sınır şudur: girdi → istek → çıktı → uygulama kabulü. Son aşamanın sahibi sizsiniz. Üretilen bir fatura alanı yine de doğrulanmalıdır; bir görsel yine de incelenmelidir; bir destek yanıtı yine de içerdiği vaadi yerine getirme iznine ihtiyaç duyar.

Protokol seçimleri de farklılık gösterir. Google'ın referansı standart üretim, akış ve canlı etkileşim arasında ayrım yapar. Bunu, başka yerlerde aynı desteğin olduğunu varsaymak yerine etkileşim modlarının farklı olduğuna dair kanıt olarak değerlendirin. (Google Gemini API referansı, erişim: Eylül 2026.)

Geliştiriciler İçin Üretken Yapay Zeka API'si: Nasıl Seçilir

Katalogları karşılaştırmadan önce kısa bir kabul briefi yazın. Editoryal bir görsel özelliği için bu brief yatay çıktı, sınırlı bir nesne sayısı, görünür marka öğesi olmaması ve bir insan inceleme adımı belirtebilir. Destek talebi sınıflandırması için sabit bir etiket kümesi ve açık bir belirsiz sonuç belirtebilir.

Adayları şu sırayla değerlendirin:

1. Girdiler ve çıktılar. Desteklenen dosyalar, girdi sınırları, çıktı biçimleri ve referans görsel davranışı için tam model uç noktasını kontrol edin. Bir model ailesi adı, sözleşme işlevi göremeyecek kadar geniştir.
2. Görev uyumu. Zorlayıcı olanlar dâhil temsili briefleri deneyin. Kısıt ihlallerini dosya veya ağ hatalarından ayrı sayın, böylece neyin düzeltilmesi gerektiğini bilirsiniz.
3. Entegrasyon uyumu. Kimlik doğrulamayı, yanıt zarflarını, görev durumu değerlerini ve istemci kitaplığı desteğini doğrulayın. Bunları mevcut arka ucunuza uyarlamak için gereken işi de hesaba katın.
4. Bekleme süresi ve eşzamanlılık. Kullanıcıların sayfadan ayrılıp geri dönüp dönemeyeceğine karar verin. Kısa süreli bir etkileşimli deneyime bağlanmadan önce beklenen iş yükünüzü test edin.
5. Faturalandırma netliği. Ücretlendirilebilir birimi ve hangi ayarların bunu değiştirdiğini belirleyin. Gönderilen her isteğin aynı ücreti aldığını varsaymak yerine hata ve iade işleyişini kontrol edin.
6. Veri gereksinimleri. Girdi işleme, saklama, silme ve geçerli koşulları göndermeyi planladığınız gerçek verilere göre gözden geçirin. Hassas materyal kullanmadan önce çözülmemiş soruları belgeleyin.
7. Değişiklik yönetimi. Bir regresyon kümesi tutun ve model tanımlayıcılarını, promptları ve parametreleri kaydedin. Bir güncelleme veya değişim sonrası davranışı nasıl yeniden değerlendireceğinizi planlayın.

Kurumsal rehberlik, erişim ve veri kurallarının neden bu karara dâhil olduğunu gösterir: Harvard, yapay zeka geliştirici araçlarıyla ilgili onaylı erişim yollarını ve kısıtlamaları açıklar. Bunlar Harvard'ın düzenlemeleridir, uygulamanız için evrensel izinler değildir. (Harvard University Information Technology, erişim: Eylül 2026.)

Atlas Cloud, aynı uygulamada birkaç model yeteneği yer alacaksa değerlendirilebilecek barındırılan bir seçenektir. Bu makale, somut bir örnek olarak onun görsel görevi arayüzünü kullanır. Yine de her modelin girdilerini ve çıktılarını doğrulamanız gerekir; yalnızca model kimliğini değiştirmek yeterli değildir.

Çıktı biçimini, kaliteyi ve boyut kısıtlarını gösteren resmi görsel uç noktası belgeleri

Model özel parametreler, entegrasyon sözleşmesinin bir parçasıdır. Bir istek gövdesini yeniden kullanmadan önce izin verilen değerlerini okuyun.

Küçük bir SaaS ekibi için yararlı karşılaştırma, kabul edilen tek bir sonucu yayına almanın toplam emeğidir. Çıkarım ücretinin yanına bağdaştırıcı kodunu, destek incelemesini, gözden geçirme süresini ve geçiş testlerini de ekleyin. Bu, kullanışlı bir prototipin pahalı bir üretim iş akışını gizlemesini önler.

Geliştiriciler İçin Üretken Yapay Zeka API'si: İlk İstek

Örnek, model kimliği openai/gpt-image-2/text-to-image olan GPT Image 2 Text-to-Image kullanır. Uç nokta belgeleri quality: high, size: 2048x1152 ve output_format: png değerlerini listeler. Bunlar aşağıdaki örnekler için istenen ayarlardır.

1. Promptu oyun alanında oluşturun. Referans görsel eklemeden aşağıdaki kahvaltı briefini kullanın. Çalıştır'a basmadan önce model adını ve kesinleşmiş ayarları kontrol edin. Bir alandan ayrıldığınızda geri dönen bir seçim, istediğiniz ayar değildir.

plaintextCopy
1Create a realistic editorial food photograph for an article about a simple breakfast.
2
3On a light oak table, show exactly one white ceramic plate holding exactly two slices of toasted sourdough bread, one small clear glass bowl of strawberry jam, and one stainless steel butter knife resting to the right of the plate.
4
5Use soft morning window light from the left, natural colors, a three-quarter overhead camera angle, and realistic bread texture. Keep every requested object fully inside the frame.
6
7No people, no hands, no drinks, no extra dishes, no packaging, no logos, no text, and no watermark. Landscape composition, 16:9.

2. Kimlik doğrulamayı sunucuda tutun. Ön ucunuz bir görevi başlatmak için kendi arka ucunuzdan istekte bulunmalıdır. ATLAS_API_KEY değerini sunucu ortamında saklayın. Bunu asla tarayıcı JavaScript'ine, görsel URL'lerine veya istemcinin görebileceği günlüklere eklemeyin. ATLAS_API_HOST değerini api.atlascloud.ai olarak ayarlayın; bu, şema veya yol içermeyen bir ana makine adıdır.

3. Bir kez gönderin ve kimliği kalıcı olarak saklayın. Belgelenen üretim yolu POST /api/v1/model/generateImage şeklindedir. data.id değerini okuyun, ardından uygulamanızın göreviyle ilişkilendirerek saklayın. Gönderim yanıtı kaybolursa, ücretlendirilebilecek yeni bir görev oluşturmadan önce durumu araştırın.

4. Kaydedilen görevi yoklayın. GET /api/v1/model/prediction/{prediction_id} sorgusunu kullanın. Tahmin belgeleri, çıktı URL'lerini data.outputs içinde vererek processing, completed ve failed durumlarını açıklar. Bir completed durumu yine de boş olmayan bir çıktı dizisi için kontrol edilmelidir.

5. İndirin ve doğrulayın. Dosyayı kendi denetiminiz altına kaydedin, çözülebildiğini doğrulayın ve briefe göre inceleyin. Ancak bundan sonra kabul edilmiş bir sonucu uygulamaya döndürün. Bir indirme veya doğrulama hatası mevcut göreve bağlı kalmalıdır.

Aşağıdaki kod, resmi arayüz belgelerinden derlenmiştir. Canlı bir API kıyaslaması olarak sunulmamaktadır. Makalenin medya iş akışı, API anahtarı değil tarayıcı test oyun alanını kullanır.

Kahvaltı promptunu tam olarak prompt.txt olarak kaydedin. Node.js için yerleşik fetch içeren bir ortam kullanın, sharp kurun ve bunu generate.mjs olarak kaydedin. Ayrı bir çalışma dizininde çalıştırın. İki görevi kasıtlı olarak istemiyorsanız, iki dildeki örneklerden yalnızca birini çalıştırın.

javascriptCopy
1import { readFile, writeFile, mkdir } from 'node:fs/promises';
2import sharp from 'sharp';
3
4const key = process.env.ATLAS_API_KEY;
5const host = process.env.ATLAS_API_HOST;
6if (!key || host !== 'api.atlascloud.ai') {
7  throw new Error('Set ATLAS_API_KEY and ATLAS_API_HOST');
8}
9const base = 'https:' + '//' + host;
10const headers = { Authorization: `Bearer ${key}` };
11const sleep = ms => new Promise(resolve => setTimeout(resolve, ms));
12const payload = {
13  model: 'openai/gpt-image-2/text-to-image',
14  prompt: await readFile('prompt.txt', 'utf8'),
15  quality: 'high', size: '2048x1152', output_format: 'png'
16};
17await mkdir('output', { recursive: true });
18await writeFile('output/request.json', JSON.stringify(payload, null, 2));
19
20async function api(path, method = 'GET', body) {
21  const response = await fetch(base + path, {
22    method,
23    headers: { ...headers, 'Content-Type': 'application/json' },
24    body: body ? JSON.stringify(body) : undefined,
25    signal: AbortSignal.timeout(30000)
26  });
27  const requestId = response.headers.get('x-request-id');
28  console.error(JSON.stringify({ method, status: response.status, requestId }));
29  if (!response.ok) {
30    const error = new Error(`HTTP ${response.status}; request ${requestId}`);
31    error.retryable = [429, 500, 503, 504].includes(response.status);
32    throw error;
33  }
34  const json = await response.json();
35  if (!json.data) throw new Error('Missing response data');
36  return json.data;
37}
38
39let id = process.env.PREDICTION_ID;
40try {
41  if (!id) {
42    // Deliberately no automatic retry for submission.
43    const submitted = await api('/api/v1/model/generateImage', 'POST', payload);
44    id = submitted.id;
45    if (typeof id !== 'string' || !id) throw new Error('Missing prediction ID');
46    await writeFile('output/prediction-id.txt', id);
47  }
48  const deadline = Date.now() + 600000;
49  let errors = 0;
50  let outputUrl;
51  while (Date.now() < deadline) {
52    let job;
53    try {
54      job = await api('/api/v1/model/prediction/' + encodeURIComponent(id));
55      errors = 0;
56    } catch (error) {
57      const transient = error.retryable ||
58        ['TimeoutError', 'AbortError'].includes(error.name) ||
59        error instanceof TypeError;
60      if (!transient || ++errors > 3) throw error;
61      await sleep(Math.min(30000, 1000 * 2 ** errors) + Math.random() * 500);
62      continue;
63    }
64    if (job.status === 'failed') {
65      throw new Error(`Task failed; code ${job.error_code ?? 'unknown'}`);
66    }
67    if (job.status === 'completed') {
68      outputUrl = job.outputs?.[0];
69      if (typeof outputUrl !== 'string' || !outputUrl) {
70        throw new Error('Completed task has no output');
71      }
72      break;
73    }
74    if (job.status !== 'processing') throw new Error('Unexpected task status');
75    await sleep(2000);
76  }
77  if (!outputUrl) throw new Error('Polling deadline reached; resume this ID');
78  const url = new URL(outputUrl);
79  if (url.protocol !== 'https:') throw new Error('Unexpected output protocol');
80  // Do not forward the API credential to the media host.
81  const file = await fetch(url, { signal: AbortSignal.timeout(60000) });
82  if (!file.ok) throw new Error(`Download HTTP ${file.status}`);
83  const bytes = Buffer.from(await file.arrayBuffer());
84  await sharp(bytes, { limitInputPixels: 20000000 }).raw().toBuffer();
85  const meta = await sharp(bytes).metadata();
86  if (meta.format !== 'png' || meta.width !== 2048 || meta.height !== 1152) {
87    throw new Error('File format or dimensions differ from the request');
88  }
89  await writeFile('output/breakfast.png', bytes);
90  console.log(JSON.stringify({ id, state: 'ready_for_review',
91    file: 'output/breakfast.png' }));
92} catch (error) {
93  console.error(JSON.stringify({ id: id ?? null, state: 'needs_attention',
94    error: error.message }));
95  process.exitCode = 1;
96}

Daha kısa olan Python eşdeğeri requests ve Pillow kullanır, aynı prompt.txt ve özdeş ayarlarla. Devam etmek için PREDICTION_ID değerini de kabul eder. Bu betikler tek bir yerel görevi gösterir; dağıtılmış bir hizmet kalıcı görev kayıtları ve sınırlı indirmeler gerektirir.

pythonCopy
1import io, json, os, random, time
2from pathlib import Path
3from urllib.parse import quote, urlparse
4import requests
5from PIL import Image
6
7key = os.environ['ATLAS_API_KEY']
8assert os.environ['ATLAS_API_HOST'] == 'api.atlascloud.ai'
9base = 'https:' + '//' + os.environ['ATLAS_API_HOST']
10headers = {'Authorization': 'Bearer ' + key}
11out = Path('output')
12out.mkdir(exist_ok=True)
13payload = dict(model='openai/gpt-image-2/text-to-image',
14               prompt=Path('prompt.txt').read_text(encoding='utf-8'),
15               quality='high', size='2048x1152', output_format='png')
16job_id = os.getenv('PREDICTION_ID')
17try:
18    if not job_id:
19        # A submission timeout needs investigation, not a blind retry.
20        r = requests.post(base + '/api/v1/model/generateImage',
21                          headers=headers, json=payload, timeout=30)
22        r.raise_for_status()
23        job_id = r.json()['data']['id']
24        if not isinstance(job_id, str) or not job_id:
25            raise ValueError('Missing prediction ID')
26        (out / 'prediction-id.txt').write_text(job_id)
27    deadline, errors, url = time.monotonic() + 600, 0, None
28    while time.monotonic() < deadline:
29        try:
30            r = requests.get(base + '/api/v1/model/prediction/' +
31                             quote(job_id, safe=''), headers=headers, timeout=30)
32            r.raise_for_status()
33        except requests.RequestException as exc:
34            status = exc.response.status_code if exc.response is not None else None
35            if status not in (None, 429, 500, 503, 504) or errors >= 3:
36                raise
37            errors += 1
38            time.sleep(min(30, 2 ** errors) + random.random() / 2)
39            continue
40        errors = 0
41        job = r.json()['data']
42        if job['status'] == 'failed':
43            raise RuntimeError('Task failed: ' + str(job.get('error_code')))
44        if job['status'] == 'completed':
45            outputs = job.get('outputs') or []
46            if not outputs or not isinstance(outputs[0], str) or not outputs[0]:
47                raise ValueError('Completed task has no output')
48            url = outputs[0]
49            break
50        if job['status'] != 'processing':
51            raise ValueError('Unexpected task status')
52        time.sleep(2)
53    if not url:
54        raise TimeoutError('Polling deadline reached; resume this ID')
55    if urlparse(url).scheme != 'https':
56        raise ValueError('Unexpected output protocol')
57    r = requests.get(url, timeout=60)  # No Authorization header here.
58    r.raise_for_status()
59    with Image.open(io.BytesIO(r.content)) as image:
60        image.load()
61        if image.format != 'PNG' or image.size != (2048, 1152):
62            raise ValueError('Unexpected file format or dimensions')
63    (out / 'breakfast.png').write_bytes(r.content)
64    print(json.dumps(dict(id=job_id, state='ready_for_review')))
65except Exception as exc:
66    print(json.dumps(dict(id=job_id, state='needs_attention', error=str(exc))))
67    raise SystemExit(1)

Gönderilen kahvaltı promptunu ve tamamlanan çıktıyı gösteren tamamlanmış GPT Image 2 oyun alanı

Tamamlanmış bir oyun alanı çalıştırması, gönderilen promptu, çıktı boyutunu, kalite ayarını ve üretilen sonucu bir arada kaydeder.

Yoklama için belirlenen bir son tarih, bu istemcinin beklemeyi bırakmasını sağlar; sunucu tarafındaki işi iptal etmez. Hâlihazırda yolda olan bir istek, yoklama penceresinden sonra tamamlanabilir; dolayısıyla bu, kesin bir uçtan uca gecikme garantisi değildir. Kimliği koruyun ve bir çalışanın bunu daha sonra kontrol etmesine izin verin.

Geliştiriciler İçin Üretken Yapay Zeka API'si: Pratik Kullanımlar

Aşağıdaki 3 brief farklı gereksinimleri test eder. Bunlar bağımsız isteklerdir; bir sonucun bir sonrakinin girdisi olduğu bir zincir değildir. Brieflerdeki farkların anlaşılır kalması için aynı modeli ve istenen ayarları koruyun.

A. Yemek editoryal görseli: sayı ve yerleşim. Kahvaltı promptu, çıktının 2 dilim kızarmış ekmek, 1 tabak, 1 reçel kâsesi ve 1 bıçak içerip içermediğini test eder. Bıçak tabağın sağında olmalı ve gerekli tüm nesneler çerçevenin içinde kalmalıdır.

Nesne sayısı ve bıçak yerleşimi kontrolüyle eşleştirilen kahvaltı görseli üretim örneğisTüretilen sonuç istenen tabağı, kızarmış ekmeği, reçel kâsesini ve sağ taraftaki bıçağı içerir; aşağıdaki yerleşim incelemesi için hazırdır.

Üst üste binen dilimleri tek tek inceleyin. Arka planda bir bardak belirirse veya bıçak tabağın üzerine kayarsa, görsel olarak ikna edici bir kahvaltı yine de başarısız olabilir. Bir sonuç başarısız olursa, belirsiz uzamsal talimatı gözden geçirin, tek bir değişkeni değiştirin ve reddetme nedenini saklayın. Genel olarak daha iyi bir görsel istemeyi tekrarlamaktan kaçının.

B. Makale kapağı: kullanılabilir başlık alanı. Bu istek, kompozisyonu bir düzen bağımlılığı olarak ele alır. Sayfa editörünün solda boş alana ihtiyacı var; sağ tarafta ise aletler ve saksı yer alıyor. Gerçek başlığı daha sonra HTML/CSS kullanarak ekleyin, böylece düzenlenebilir ve okunabilir kalır.

plaintextCopy
1Create a realistic editorial photograph for an article about repairing everyday objects.
2
3On the right half of a light wooden workbench, show one pair of worn gardening gloves, one small metal hand trowel, and one unbranded terracotta plant pot. The left 45 percent of the image must remain an empty, softly lit section of the same workbench, suitable for adding a headline later.
4
5Use natural side light from a nearby window, believable material textures, neutral colors, and a slightly elevated camera angle.
6
7No people, no hands, no extra tools, no plants, no logos, no letters, no text, and no watermark. Landscape composition, 16:9.

İstenen sol taraftaki başlık alanını ve sağ taraftaki nesneleri gösteren çalışma tezgâhı kapağı örneği

Sonuç, eldivenleri, saksıyı ve malayı sağda tutarken solda kullanılabilir boş alanı korur.

Sonucu amaçlanan yayın kırpmasında kontrol edin. Mobil bir kart ortadan kırptığında, yatay ana görsel yararlı boş bölgesini kaybedebilir. Kompozisyon başarısız olursa, nesne sınırlarını daha sıkı belirtin veya uygulama kırpmasını değiştirin. Başarısızlığı, istenen öznelerin üzerine metin yerleştirerek gizlemeyin.

C. Kumaş illüstrasyonu: ayrıntı ve sıralama. Sonraki istek, ayırt edilebilir görünür dokulara sahip 3 katlanmış kumaş parçası ister. Sayıyı, konumu ve sonucun okuyucuların göreceği boyutta açıklayıcı bir illüstrasyonu destekleyip desteklemediğini test eder.

plaintextCopy
1Create a realistic close-up editorial photograph for an article explaining common fabric textures.
2
3Show exactly three folded fabric swatches arranged side by side on a neutral matte gray surface: natural beige linen on the left, blue cotton denim in the center, and dark green wool on the right.
4
5Use the same soft daylight across all three fabrics, an overhead camera angle, and sufficient depth of field to keep the visible weave of each fabric in focus. Preserve natural wrinkles and believable fiber detail.
6
7No labels, no rulers, no sewing tools, no hands, no additional objects, no text, no logos, and no watermark. Landscape composition, 16:9.

Bej, mavi ve koyu yeşil kumaş parçası yerleşim kontrollerini içeren yapay zeka ile üretilmiş kumaş illüstrasyonu

İstenen üç kumaş parçası görsel olarak birbirinden ayrıdır. Bu üretilmiş doku bir illüstrasyondur; gerçek bir ürünün elyaf bileşiminin kanıtı değildir.

Ortadaki kumaş parçasında okunabilir bir dokuma yoksa bu sorunu kaydedin ve çerçevelemeyi veya ayrıntı talimatını ayarlayın. Üretilmiş dokuyu asla gerçek bir ürünün ölçülmüş özelliği olarak tanımlamayın.

Metin özellikleri de benzer şekilde dar kontrollere ihtiyaç duyar. Destek talebi sınıflandırması için izin verilen kümenin dışındaki etiketleri reddedin ve bir belirsizlik yolu tutun. Belge çıkarımı için ayrıştırılabilir JSON'un yanı sıra alanları ve kaynak aralıklarını da zorunlu kılın. Sözdizimsel olarak geçerli bir yanıt yine de yanlış tutarı yanlış alana yerleştirebilir.

Geliştiriciler İçin Üretken Yapay Zeka API'si: Hataları Ele Alma

Aktarım başarısını, görev tamamlanmasını ve iş kabulünü ayrı ayrı izleyin. Başarılı bir HTTP yanıtı, işlenen bir görev içerebilir. Tamamlanmış bir görev bozuk bir indirme üretebilir. Okunabilir bir görsel briefi ihlal edebilir. Her biri farklı bir kurtarma eylemi gerektirir.

Bilinçli olarak 3 zaman sınırı belirleyin: tek bir HTTP zaman aşımı, bir yoklama aralığı ve genel bir bekleme penceresi. Örnekler 30 saniyelik API istek zaman aşımı, 2 saniyelik yoklama ve 10 dakikalık yoklama penceresi kullanır. Bunlar uygulama tercihleridir, reklamı yapılan hizmet performansı değildir.

Güncel platform hata belgeleri, LLM ve medya uç noktalarının Retry-After veya kalan hız sınırı başlıkları sağlamadığını söyler. İstemci tarafında bir gecikme politikası kullanın; kurtarmayı bu yolların döndürmediği bir başlığa bağımlı hâle getirmeyin. Diğer API aileleri farklı davranabilir.

Otomatik okuma yeniden denemelerini sınırlı tutun. Üstel gecikmeler artı biraz rastgele titreşim, birçok çalışanın aynı anda yeniden denemesini önlemeye yardımcı olur. Kısıtlama sürerse eşzamanlılığı azaltın. Tekrarlanan hatalar, bir dönen simgenin arkasına gizlenmiş sonsuz bir döngü yerine gözlemlenebilir bir olaya dönüşmelidir.

Gönderim yeniden denemeleri daha sıkı bir yaklaşımı hak eder. Gövdeyi gönderdikten sonra bağlantı kapanırsa, sunucunun bir görev oluşturup oluşturmadığını bilemeyebilirsiniz. Gönderimden önce yerel bir niyet kaydedin ve tahmin kimliği gelmediğinde istek geçmişini ya da destek izlerini araştırın. Uç nokta belgelemiyorsa bir eşgüdüm (idempotency) başlığı uydurmayın.

Bir kimliğiniz olduğunda, devam etmek için onu kullanın. Bir indirme hatası başka bir indirme denemesini veya durum kontrolünü tetiklemelidir; yeni bir görsel üretim isteğini değil. Örnekler, otomatik yeniden deneme davranışını bilinçli olarak yoklama okumalarında tutar ve başarısız bir gönderimde durur.

Her görev için uygulama görev kimliğinizi, tahmin kimliğini, istek kimliklerini, modeli, ayarları, zaman damgalarını ve nihai durumu saklayın. Promptları yalnızca uygun bir veri politikası kapsamında saklayın. Yetkilendirme başlıklarını veya hassas kullanıcı içeriğini asla genel hata günlüklerine koymayın.

Ön uca açıklayabileceği durumları verin: hazırlanıyor, işleniyor, çıktı kontrol ediliyor, hazır veya ilgi gerekiyor. Biri sayfayı yenilediğinde kurtarılabilir bir görev gösterin. Aynı yerel görev beklemedeyken tekrarlanan gönderimi devre dışı bırakın; yine de uygun olduğunda kasıtlı yeni bir isteğe izin verin.

Geliştiriciler İçin Üretken Yapay Zeka API'si: Gerçek Maliyetler

Düşük bir istek fiyatı, size kullanılabilir bir özelliğin maliyetini söylemez. Bütçenizin ücretlendirilen tutara, kabul edilen çıktı sayısına ve bunları sunmak için gereken destek işine ihtiyacı vardır.

Metin API'leri genellikle girdi ve çıktı token'larını ayırt eder. Uzun bağlam, getirilen pasajlar, konuşma geçmişi ve tekrarlanan yanıtların tümü kullanıma katkıda bulunabilir. Her iş yüküne tek bir token tahmini uygulamak yerine seçilen uç noktanın gerçekte ücretlendirdiği kategorileri kaydedin.

Görseller için tam modelin faturalandırma birimini ve yapılandırmasını inceleyin. Boyut ve kalite, modeller arasında faturalandırmayı farklı şekilde etkileyebilir. Video için süre, çözünürlük ve model seçimi ücreti değiştirebilir. Bir katalogdaki başlangıç fiyatını belirli bir yapılandırmanın teklifine dönüştürmeyin.

Seçilen görsel modelinin yüksek kalite, 2048 × 1152 için tam fiyatı, bu makalenin araştırması sırasında hem katalogda hem de ayrıntı sayfasında doğrulanmadı. Burada güncel bir birim fiyat veya indirim iddia edilmemektedir. Ücretli bir üretim değerlendirmesi çalıştırmadan önce bunu doğrulayın.

İki ilgili hesaplama kullanın:

plaintextCopy
1API cost per accepted output = actual API charges / accepted outputs
2
3Full feature cost per accepted output =
4(API charges + attributable review + storage + transfer + processing costs)
5/ accepted outputs

Gözlem dönemini tutarlı tutun. Süregelen depolama için hesaplamanın ilk ayı, tanımlı bir saklama süresini mi yoksa tahsis edilmiş yinelenen bir maliyeti mi kapsadığını belirtin. Bir modelin yalnızca çıkarım rakamını başka bir iş akışının tüm maliyetleri yüklenmiş değeriyle karşılaştırmaktan kaçının.

Varsayımsal örnek: 100 istek gönderirsiniz ve 80 çıktıyı kabul edersiniz. Bu grubun gerçek toplam ücretini 80'e bölün. 100 isteğin tümü aynı c tutarında ücretlendirilmişse, kabul edilen çıktı başına API maliyeti 1.25c olur. Bu koşul önemlidir: başarısız olan her isteğin ücretlendirildiğini varsaymaz.

Bunu bir sonuç tablosu değil, bir çalışma sayfası olarak kullanın. Görsel gösterimler temsili bir kabul oranı veya üretim maliyeti ortaya koymaz. Özellikle bir test ortamında değerlendirme yaparken oyun alanı alıntılarını kesinleşmiş faturalandırma kayıtlarından ayrı tutun.

Kabul edilen çıktılar sıfıra eşitse, grubu başarısız olarak bildirin ve toplam harcamayı gösterin. Bu durumda kabul edilen çıktı başına maliyet oranı tanımsızdır. Başarısız grupları gizlemek, bütçenizi uygulamanın davranışından daha iyi gösterir.

Önce israfı azaltın: gönderimden önce girdileri doğrulayın, görev kimliklerini kaydedin, kazara yinelenenleri önleyin ve ürün izin verdiğinde kabul edilen varlıkları yeniden kullanın. Ardından aynı briefler ve kontroller üzerinde daha ucuz ayarları karşılaştırın. Teklifi düşüren ama reddetme işini ikiye katlayan bir ayar, özellik maliyetini artırabilir.

Yalnızca Yanıtı Değil, Çıktıyı Test Edin

Promptu yazarken kabul kriterlerini de yazın. Bu, ikna edici bir görselin başarı tanımınızı sonradan değiştirmesini önler. Kesin gereksinimleri isteğe bağlı tercihlerden ayrı tutun ve bir gözden geçirenin bir sonucu neden reddettiğini kaydedin.

Net mekanik yanıtları olan kontrolleri otomatikleştirin: indirme başarısı, dosya çözme, biçim, boyutlar ve dosya boyutu sınırları. JSON için şemayı, gerekli alanları, izin verilen etiketleri ve türleri doğrulayın. Eksik bir gerekli alan sessizce uydurulmuş bir varsayılana dönüşmemelidir.

Yorum gerektiren gereksinimler için insan incelemesi kullanın. Kahvaltı örneğinde, gözden geçiren kişi üst üste binen dilimleri ayırt etmeli, bıçağı tanımlamalı, konumunu değerlendirmeli ve fazladan nesneleri aramalıdır. Otomatik bir görüntü denetleyicisi yardımcı olabilir, ancak sonuçları tek başına onaylamasına izin vermeden önce hatalarını değerlendirin.

Kahvaltı incelemesi aşağıdaki bağımsız kontrolleri içermelidir:

• Tam olarak 2 dilim kızarmış ekmek, 1 beyaz tabak, 1 şeffaf reçel kâsesi ve 1 bıçak.
• Bıçak tabağın sağında; gerekli nesneler tamamen çerçeve içinde.
• Fazladan bardak, tabak, el, ambalaj veya görünür marka öğesi yok.
• İstenen boyutlarda okunabilir PNG.

Dosya meta verisi kontrollerini görsel kabul kontrollerinden ayıran doğrulama kaydı

Kayıt, üretilen dosyanın gerçek boyutlarını ve boyutunu görsel kabul kontrollerinden ayrı olarak raporlar.

Gerçek özellikten sabit bir regresyon kümesi oluşturun: sıradan istekler, kalabalık kompozisyonlar, çelişkili talimatlar, zor kırpmalar ve ilgili girdi sınırları. Briefleri ve gözden geçiren kurallarını sürümleyin. Modeli, prompt şablonunu veya çıktı ayarlarını değiştirdiğinizde bunları yineleyin.

Teknik başarıyı ve kabul edilen çıktı oranını ayrı ayrı raporlayın. Fazladan bir nesne içeren okunabilir bir dosya, başarılı bir teslimat ve içerik reddi olarak sayılır. Bu sonuçları tek bir başarı sayısında birleştirmek, ekibinizin ihtiyaç duyduğu düzeltmeyi gizler.

2025 geliştirici anketi, %46'nın yapay zeka aracı doğruluğuna güvenmediğini ve %33'ün güvendiğini buldu; %3 yüksek güven bildirdi. Bu yanıtlar, üretim API'leri için ölçülmüş bir hata oranını değil, geliştirme iş akışlarındaki yapay zeka araçlarını ilgilendirir. (Stack Overflow Developer Survey, 2025.)

Benzer şekilde, 3 örnek çalıştırma genel doğruluğu veya yararlı bir p95 gecikmeyi ortaya koyamaz. Üretimde beklediğiniz koşullar genelinde daha büyük, ilgili bir örnek toplayın ve aykırı değerleri saklayın. Kontrolleri geliştirmek için gösterimleri kullanın, ardından bir sürüm kararı vermek için sistematik değerlendirmeden yararlanın.

Yayına Almadan Önce Bir Üretim Kontrol Listesi

İlk çalışan istek, sürüm kararının yalnızca küçük bir bölümünü çözer. Uygulamanızın ayrıca harcamayı sınırlaması, bitmemiş işi kurtarması ve sonuç yokken ne olduğunu açıklaması gerekir.

Erişimi koruyun. Kimlik bilgilerini arka uçta tutun, ortamları ayırın, görev kayıtlarına erişimi kısıtlayın ve kimlik bilgisi rotasyonunu planlayın. Her durum ve indirme isteğini, o görevin sahibi olan kullanıcıya göre yetkilendirin. Tahmin edilemeyen bir görev kimliği, izin kontrollerinin yerini tutmaz.

Girdileri ve kaynak kullanımını sınırlayın. Prompt uzunluğunu, yükleme türünü ve boyutunu, istenen çıktı ayarlarını ve desteklenen birleşimleri doğrulayın. İndirilen medya için izin verilen hedefleri, yönlendirmeleri, bayt sınırlarını ve çözme sınırlarını uygulayın. Yukarıdaki kısa betikler yaşam döngüsünü gösterir; sağlamlaştırılmış bir genel indirme hizmeti değildir.

Gönderimden önce bütçeleri belirleyin. Kullanıcı başına ve görev başına sınırlar, en fazla eşzamanlı görev sayısı ve daha pahalı ayarları kimin isteyebileceğini tanımlayın. İş beklemedeyken bütçe ayırın, böylece eşzamanlı isteklerin tümü aynı kalan bakiye kontrolünü geçemez.

Durumu kalıcı hâle getirin. Sağlayıcıyı çağırmadan önce yerel görevi yazın. Döndürülen tahmin kimliğini hemen kaydedin ve yoklamayı bir süreç yeniden başlatıldıktan sonra sürdürülebilir hâle getirin. Gönderim durumu bilinmiyorsa, kullanıcılara görevin kesinlikle başarısız olduğunu söylemek yerine bir araştırma durumu kullanın.

Teslim edilen varlığın sahibi olun. Kabul edilen dosyaların nerede duracağına, bunlara kimin erişebileceğine ve ne zaman sona ereceğine karar verin. Geçici bir çıktı URL'sine süresiz bağımlı olmak yerine sağlayıcı bağlantısının ömrünü ve saklama koşullarını doğrulayın. Türetilmiş dosyaların silinmesini uygulamanın veri iş akışına dâhil edin.

Hatayı anlaşılır kılın. Gecikmiş bir görevi, reddedilmiş bir sonucu ve bir hizmet hatasını birbirinden ayırın. Kasıtlı olarak yeniden denemek veya inceleme istemek için net bir yol sunun. Kurtarmanın işi yeniden oluşturmayı gerektirmemesi için kullanıcının briefini koruyun.

Değişiklikleri izleyin. Tamamlanmayı, kabulü, maliyeti ve bekleme süresini ayrı ayrı izleyin. Model veya parametre değişikliklerinden sonra regresyon kümesini yeniden çalıştırın ve mümkün olduğunda önceki yapılandırmayı kullanılabilir tutun. Hassas günlükleri gizleyin ve hem içerik hem de operasyonel kayıtlara saklama süreleri atayın.

Örnek platformu kendi uygulamanız için değerlendirmek üzere Atlas Cloud model kataloğu ile başlayın, ardından seçilen uç nokta ve tahmin belgelerini okuyun. Bir görev seçin, kabulü tanımlayın ve erişimi genişletmeden önce değerlendirmenin gerçekte ne sunduğunu kaydedin.

Sıkça Sorulan Sorular

Uygulamam için hangi üretken yapay zeka API'sini seçmeliyim?

Seçiminizi özelliğin girdilerine, çıktılarına, kabul edilebilir bekleme süresine ve inceleme gereksinimlerine göre yapın. Yasal ve operasyonel olarak kullanabileceğiniz adaylara karşı aynı temsili briefleri çalıştırın. Kabul edilen çıktı maliyetini ve entegrasyon işini yeteneklerin yanında karşılaştırın. Bu 3 görsel örneğin ortaya koyduğu evrensel bir seçim yoktur.

Geliştiriciler için ücretsiz üretken yapay zeka API'leri var mı?

Bazı hizmetler deneme sürümleri veya sınırlı ücretsiz kullanım sunar, ancak kullanılabilirlik, uygunluk, kotalar ve izin verilen kullanımlar değişir. Tam uç nokta için güncel koşulları doğrulayın. Ücretsiz bir tüketici aracı ödeneği, API erişimini de kapsamayabilir. Model ağırlıkları indirilebilir olsa bile kendi sunucunuzda barındırma donanım, elektrik ve mühendislik zamanı kullanır.

Üretken bir yapay zeka API'si kullanmak için makine öğrenmesi deneyimine ihtiyacım var mı?

HTTP, JSON, kimlik doğrulama ve sıradan arka uç geliştirme becerileriyle başlayabilirsiniz. Güvenilir bir özelliği yayına almak ayrıca değerlendirme ve operasyonel çalışma gerektirir. Kendiniz bir model eğitmeniz gerekmeden, kabul edilebilir çıktıyı tanımlayacak kadar modelin sınırlamalarını anlamanız gerekir.

Tek bir API metin, görsel ve videoyu işleyebilir mi?

Bir platform üçünü de sunabilir, ancak her yetenek farklı uç noktalar, parametreler, çıktı türleri ve bekleme düzenleri kullanabilir. Her arayüzü ayrı ayrı doğrulayın. Paylaşılan bir hesap veya kimlik bilgisi, bir metin istek gövdesini görsel ya da video modeliyle uyumlu hâle getirmez.

Görsel isteğim neden görsel yerine bir görev kimliği döndürüyor?

Uç nokta işi asenkron olarak gönderir. Kimliği kaydedin ve belgelenen durum yolunu sorgulayın. Görev tamamlandığında dosyayı alın, ardından doğrulayın. İstemciniz beklemeyi bırakırsa sunucu tarafındaki görev hâlâ çalışıyor olabilir; başka bir istek göndermeden önce o görevi sürdürün.

İş akışını bozmadan API maliyetlerini nasıl azaltabilirim?

Yinelenen gönderimleri önleyin, girdileri erkenden doğrulayın, uygun olduğunda kabul edilen varlıkları yeniden kullanın ve daha ucuz yapılandırmaları değişmemiş kabul kriterlerine karşı test edin. Kabul edilen sonuç başına gerçek ücretleri ölçün. Geliştiriciler için üretken bir yapay zeka API'si, çevresindeki uygulama sürdürebileceğiniz bir maliyetle kullanılabilir iş sunabildiğinde yerini hak eder.