Seedream 5.5 API öğreticisi: görsel oluşturma, düzenleme ve geçiş

Seedream 5.5’e geçişte asıl önemli olan yalnızca model adını değiştirmek değil, dosya iş akışıdır: bir görsel oluşturun, dönen görevi inceleyin, görseli kaydedin ve ardından düzenleme için bu kayıtlı baytları referans olarak gönderin.

AIHubMix’te Seedream 5.5 şu anda doubao-seedream-5-5 ve POST /ai/v1/images/generations kullanıyor. Bu öğreticide seramik bir kupa için ürün görseli oluşturup ardından yalnızca rengini değiştiren bir düzenleme isteği göndereceğiz.

Kapsam: Belgeler 12 Kasım 2026 tarihinde kontrol edildi. Kod yalnızca yerel sözdizimi ve çevrimdışı yardımcı işlev kontrollerinden geçirildi; herhangi bir görsel oluşturma isteği yürütülmedi. Bunlar çıktı kalitesinin, düzenleme doğruluğunun, gecikmenin veya gerçek bir ücretlendirmenin kanıtı değildir.

1. Küçük ve açık bir istek hazırlayın

requests ile Python 3.10+ kullanın. Bash’te bağımlılığı yükleyin ve anahtar değerini kabuk geçmişine kaydetmeden girin:

python3 -m pip install requests
read -r -s -p 'AIHubMix API key: ' AIHUBMIX_API_KEY
printf '\n'
export AIHUBMIX_API_KEY

Dağıtıma alınan kodda ortam değişkenini gizli bilgi yöneticiniz üzerinden ekleyin. Anahtarı kaynak dosyalarında, istek örneklerinde, günlüklerde, not defterlerinde ve tarayıcı tarafındaki kodlarda bulundurmayın. Her iki POST isteğinden önce, eşzamansız görev kılavuzunda belirtildiği gibi hesabın görev özelliğini etkinleştirin. Bu ön koşul, eşzamanlı bekleme de dâhil olmak üzere yerel /ai/v1 medya görevi uç noktaları için geçerlidir; arka planda yürütmeyi seçmekten ayrıdır.

Güncel model uç noktası şemasını okuyun ve girdiyi dizi konumuna göre değil, path alanına göre seçin. Modele özgü kısıtlar, ortak parametre listesinden önceliklidir.

Şema, model ve boş olmayan bir prompt gerektirir, n değerini 1 ile sınırlar ve png ile jpeg çıktısını listeler. image alanı bir URL, Base64 girdisi veya {url} nesnesi kabul eder; images ise yayımlanmış üst sınırı 14 referans olan bir diziyi kabul eder. Bu sınır burada çalışma zamanında test edilmemiştir. Bu örnekte tek bir referans ve açıkça belirtilmiş varsayılan boyut kullanılır; dışarıda bir input nesnesi ya da extra uzantısı kullanılmaz.

2. Görsel oluşturun, görevi inceleyin ve PNG’yi kaydedin

Birleşik görsel API’si belgeleri, id, object: image, model, status, output ve error alanlarını içeren bir görev yanıtı tanımlar. Bunu eski data[0].url biçiminde okumayın.

Önce kısa iş akışını okuyun; kurulumun tamamı ve indirme yardımcı işlevi aşağıdaki daraltılmış Ek bölümünde yer alıyor. Bu örnekleri çalıştırmadan önce, ek bölümündeki bloğu aynı Python oturumuna bir kez yükleyin. Bu blok, görsel isteği göndermeden settings, api_json ve collect tanımlar. Ardından kısa blokları sırayla çalıştırın. Her POST ayrı bir ücretli işlemdir; eksik yanıtı veya başarısız indirmeyi düzeltmek için yeniden çalıştırmayın.

Görsel isteğini bir kez gönderin

generation = {
    **settings,
    "prompt": "Product photograph of one matte blue ceramic mug on a cream tabletop, "
              "soft side lighting, plain warm-gray background, no text or logos.",
}
task = api_json("POST", IMAGES + "/generations", generation)

Görevi inceleyin, ardından PNG’yi kaydedin

async belirtilmemesi eşzamanlı bekleme anlamına gelir. HTTP 200 yanıtı yine de status: failed içerebilir. Yardımcı işlev, durumu incelemeden önce görev kimliğini kaydeder: yalnızca completed durumunda indirme işlemine geçer; failed, cancelled ve bilinmeyen durumlarda işlemi durdurur. pending ve in_progress durumlarında yeni bir görsel oluşturmak yerine mevcut görevi inceleyin.

collect(task, "mug-blue")

Bu tek çağrı, tamamlanan çıktıyı almak için isteği oluşturan anahtarı kullanır, PNG baytlarını kontrol eder ve mug-blue.png dosyasına kaydeder. Otomatik olarak yeniden oluşturma denemesi yapmaz; anahtarı iletmeden önce beklenmeyen indirme ana bilgisayarlarını veya yönlendirmeleri reddeder. Tam uygulama ek bölümündedir; burada açıklananlar belgelere dayalı davranışlardır, doğrulanmış bir görsel oluşturma sonucu değildir.

Model kılavuzuna göre çıktı URL’leri yaklaşık 30 dakika geçerlidir. Dosyayı aynı Bearer başlığıyla gecikmeden indirin ve baytları kendiniz saklayın. expires_at: null, kalıcı saklama sözü vermez. b64_json doluysa URL indirmek yerine içeriği çözüp kullanın.

3. Korunan indirme URL’si yerine yerel dosyayı düzenleyin

Düzenleme için ücret harcamadan önce kaydedilen görseli kendiniz inceleyin. Kimliği doğrulanmış istemcinizin indirebildiği bir content_url, görsel sağlayıcısının erişebileceği herkese açık bir URL olmak zorunda değildir. Yerel PNG’yi Data URI olarak yeniden yükleyin:

reference = Path("mug-blue.png").read_bytes()
if not reference.startswith(b"\x89PNG\r\n\x1a\n"):
    raise SystemExit("The editing reference must be the saved PNG.")
edit = {
    **settings,
    "prompt": "Change only the mug color from blue to forest green. Preserve the mug shape, "
              "camera angle, tabletop, background, lighting, and shadows.",
    "image": "data:image/png;base64," + base64.b64encode(reference).decode("ascii"),
}
task = api_json("POST", IMAGES + "/generations", edit)
collect(task, "mug-green")

Bu istek, görselin korunmasını talep eder; korunduğunu kanıtlamaz. Başka bir ücretli işlemden önce sonucu inceleyin. Satır içi kodlama dâhil tüm JSON isteği 32 MiB sınırına sığmalıdır; modele özgü medya sınırları da geçerlidir. Gerçekten herkese açık ve sağlayıcının erişebildiği bir görsel URL’si de kabul edilen başka bir girdi seçeneğidir.

4. İsteğe bağlı: eşzamansız bekleme ve kesintiden kurtarma

1. bölümdeki hesap ön koşulu, yürütme kipinden ayrıdır. 403 async_not_enabled, görev özelliğinin konsoldan etkinleştirilmesi gerektiği anlamına gelir. Yalnızca arka planda yürütme isteğe bağlıdır.

Arka planda görsel oluşturmayı tercih ediyorsanız aynı generation sözlüğünü oluşturun ve ardından hem eşzamanlı task = api_json(...) satırı hem de ayrı collect(...) çağrısı yerine aşağıdaki iki satırı kullanın. Göndermeden önce kipi seçin; iki sürümü birden çalıştırmayın:

task = api_json("POST", IMAGES + "/generations", {**generation, "async": True})
collect(task, "mug-blue", poll=True)

Yardımcı işlev, son duruma ulaşılana kadar yaklaşık her 15 saniyede bir GET /ai/v1/images/{id} sorgusu gönderir. Bu, sunucu tarafından zorunlu kılınan bir aralık değil, belgelerde önerilen yoklama sıklığıdır. Webhook’lar için async: true gerekir; alıcı kurmak bu öğreticinin kapsamı dışındadır.

İşlem toplama durduysa, gerekirse yeni bir oturumda ek bölümündeki ortak kurulum/yardımcı işlev bloğunu yeniden yükleyin; görsel oluşturma bloğunu değil. Bir kimlik kaydedildiyse POST göndermeden kaldığınız yerden devam edin:

task_id = Path("mug-blue.task-id").read_text(encoding="utf-8").strip()
task = api_json("GET", IMAGES + "/" + quote(task_id, safe=""))
collect(task, "mug-blue", poll=True)

Düzenleme işlemini kurtarmak için karşılık gelen mug-green dosya adının kökünü kullanın. Oluşturma yanıtı bir kimlik kaydedilmeden kaybolduysa bunun yerine son görevleri inceleyin:

recent = api_json("GET", IMAGES + "?limit=20&order=desc")
for row in recent.get("data", []):
    print(row.get("id"), row.get("model"), row.get("status"), row.get("created_at"))

Modeli ve oluşturulma zamanını eşleştirin; en yeni görevi düşünmeden seçmeyin. Gerekirse sonraki isteğin after imleci olarak next_after değerini kullanın. Eşleşme belirsizse yeniden göndermek yerine destek ekibiyle iletişime geçin. Liste anlık görüntüdür; yoklama için görev ayrıntılarını kullanın. Bir satırdaki output_error, çıktının okunamadığı anlamına gelir; görsel oluşturulmadığı veya ücretlerin değiştiği anlamına gelmez.

İsteği oluşturan anahtarı kullanmaya devam edin. Özellikle birleşik görev listesi, ayrıntıları ve içeriğine erişim token bazında yalıtılmıştır: aynı hesaptaki başka bir anahtar bu görevlere erişemez. Yerel bir kesinti, işlemin başarısız olduğunu veya ücret alınmadığını kanıtlamaz.

5. Geçiş hataları ve güncel hatalar

Eski Doubao bağdaştırıcısı belgeleri, eski kimlikleri /v1/models/doubao/<id>/predictions altında, input zarfıyla listeler. Envanterde 5.5 bulunmuyor. Burada keşfedilebilir 5.5 rotasını ve düz gövdeyi kullanın; eski yöntemle görsel oluşturmanın başarısız olup olmadığı test edilmedi. Noktalı bir yazımın takma ad olduğunu varsaymak yerine güncel, tireli kimliği aynen kopyalayın.

Üst düzey quality, background, aspect_ratio veya seed alanlarını taşımayın: bunlar bu modelin güncel şemasında yer almıyor. ByteDance’in lansman duyurusu, yerel şeffaf RGBA çıktısından bahsediyor; ancak ağ geçidi şemasında ne background ne de layer_decomposition alanı bulunuyor. Yalnızca PNG seçmek, şeffaflık için doğrulanmış bir yöntem değildir.

Bunlar, gözlemlenmiş 5.5 yanıtları değil, belgelenmiş birleşik görsel hatalarıdır. HTTP durumunu görev durumundan ayrı kontrol edin ve tam ileti dizgesine değil, code alanına göre işlem yapın.

HTTP 502 task_status_unavailable için kılavuzda şöyle belirtiliyor:

Model sağlayıcısındaki görev durumu doğrulanamadı. Yeniden göndermeyin. Görev kimliği veya istek kimliğiyle destek ekibiyle iletişime geçin.

Görev düzeyindeki result_delivery_failed içinse şöyle belirtiliyor:

Oluşturulan sonuç teslim edilemedi. Otomatik olarak yeniden göndermeyin. Görev kimliğiyle destek ekibiyle iletişime geçin.

sync_timeout, yürütmenin hiç gerçekleşmediğini göstermez. error.tid değerini saklayın; görev kimliğini yalnızca gerçekten döndüyse kullanın ve belirsiz sonuçları çözmeleri için destek ekibine başvurun. Kurtarılabilir bir indirme hatasında görseli yeniden oluşturmak yerine yeniden indirmeyi deneyin. 410 artifact_expired durumu farklıdır: ilgili öğe artık indirilemez. Önce kaydedilmiş dosyaları kontrol edin; hâlâ yeni bir kopya gerekiyorsa yeni ve ücretli bir görsel oluşturulmasına bilinçli olarak onay verin. 429 too_many_downloads durumunda kaydedilmiş kopyaları kontrol edin veya destek ekibiyle iletişime geçin; yalnızca beklemek erişimin yeniden açılacağını garanti etmez.

Kılavuz, başarısız bir görevde bildirilse bile output_blocked için görsel oluşturma ücretinden açıkça feragat eder. Bu istisnayı başarısız veya moderasyona takılan tüm isteklere genellemeyin; output_policy_violation mevcut moderasyon ücretlendirme kurallarına tabidir.

6. Yalnızca tek bir çıktıyı değil, iş akışının tamamını bütçelendirin

Sina Technology’nin lansman haberinde, görsel girdisi ve çıktısı dâhil olmak üzere 2K kare bir görselin tek bir düzenlemesi için yaklaşık 0.28 CNY ücret bildiriliyor; metin token’ları ücretsiz. Bu, basında yer alan bir haberdir; doğrulanmış resmî fiyat tarifesi veya AIHubMix teklifi değildir.

Örnek olarak, mevcut bir görsel üzerinde yukarıdaki yaklaşık senaryoya uyan iki ücretli düzenleme turu yaklaşık 2 × CNY 0.28 = CNY 0.56 tutar. İlk metinden görsele oluşturma işlemi, ek referans görselleri, ilave adaylar ve yeniden denemeler bu tutara dâhil değildir. Bu, ölçülmüş bir fatura değildir.

Bu oluşturma-sonra-düzenleme örneği için şu formülü kullanın: toplam = ilk görsel oluşturma ücreti + referans görsel düzenleme ücreti. İncelenen sayfalarda 5.5 için eksiksiz bir resmî fiyat tarifesi belirlenmediğinden, bu öğretici sabit bir toplam veya eskiyle yeni arasındaki kesin bir tasarruf oranı sunmuyor.

Göndermeden önce:

• Güncel kimliği, rotayı, düz gövdeyi ve model şemasını doğrulayın.
• Anahtarı ortamda tutun; kurtarma için görev kimliklerini saklayın.
• Her POST işlemini ayrı bir ücretli işlem olarak değerlendirin; indirme işlemini yeniden denemek için yeni POST göndermeyin.
• Düzenlemeden önce görev durumunu ve kaydedilen görseli inceleyin.
• Yerel verileri doğru MIME türüyle yeniden yükleyin.
• Başka bir görsel üretmeyi düşünmeden önce sonucu belirsiz görevleri kurtarın.

Tek bir görsel ve bilinçli bir düzenlemeyle başlayın; dosyaları incelemeden yeni turlar eklemeyin.

Ek: ortak kurulum ve indirme yardımcısı

İş akışını okurken bu eki atlayabilirsiniz. Kısa örnekleri çalıştırmadan önce bu bloğu bir kez genişletip aynı Python oturumuna yükleyin. Oturumu yapılandırır ve görsel üretmeden işlevler tanımlar. Kesintiye uğramış bir görevi yeni bir oturumda kurtarmak için yalnızca bu bloğu yeniden yükleyin; oluşturma veya düzenleme bloğunu değil.

import base64
import os
import time
from pathlib import Path
from urllib.parse import quote, urlsplit

import requests

BASE = "https://aihubmix.com"
IMAGES = "/ai/v1/images"
settings = {
    "model": "doubao-seedream-5-5",
    "size": "2048x2048",
    "n": 1,
    "output_format": "png",
    "response_format": "url",
}
client = requests.Session()
client.headers["Authorization"] = "Bearer " + os.environ["AIHUBMIX_API_KEY"]


def api_json(method, path, body=None):
    try:
        response = client.request(
            method, BASE + path, json=body,
            timeout=(15, 600), allow_redirects=False,
        )
    except requests.RequestException:
        raise SystemExit(
            "Connection interrupted. Recover the existing task before another POST."
        ) from None
    try:
        data = response.json()
    except ValueError:
        raise SystemExit(
            f"HTTP {response.status_code}: non-JSON response; recover before another POST."
        ) from None
    if not isinstance(data, dict):
        raise SystemExit("Unexpected response; recover before another POST.")
    if not 200 <= response.status_code < 300:
        error = data.get("error") or {}
        raise SystemExit(
            f"HTTP {response.status_code}: code={error.get('code')}, "
            f"tid={error.get('tid')}. No automatic generation retry."
        )
    return data


def collect(task, stem, poll=False):
    task_id = task.get("id")
    if not isinstance(task_id, str) or not task_id:
        raise SystemExit("No task ID returned. Recover from the task list; do not resubmit.")
    Path(stem + ".task-id").write_text(task_id + "\n", encoding="utf-8")
    while True:
        status = task.get("status")
        print("Task:", task_id, "status:", status)
        if status == "completed":
            break
        if status not in {"pending", "in_progress"}:
            error = task.get("error") or {}
            raise SystemExit(
                f"Stopped: status={status}, code={error.get('code')}; task={task_id}."
            )
        if not poll:
            raise SystemExit("Task still active. Query the saved ID; do not recreate it.")
        time.sleep(15)
        task = api_json("GET", IMAGES + "/" + quote(task_id, safe=""))

    output = task.get("output") or []
    if not output:
        raise SystemExit("Completed without readable output; investigate the saved task.")
    item = output[0]
    if item.get("b64_json"):
        image_bytes = base64.b64decode(item["b64_json"], validate=True)
    else:
        url = item.get("content_url")
        if not isinstance(url, str):
            raise SystemExit("Missing content_url; investigate the saved task.")
        parsed = urlsplit(url)
        if (parsed.scheme, parsed.netloc) != ("https", "aihubmix.com"):
            raise SystemExit("Unexpected download origin; key was not forwarded.")
        try:
            response = client.get(url, timeout=(15, 120), allow_redirects=False)
        except requests.RequestException:
            raise SystemExit("Download interrupted; recover this task, not a new generation.") from None
        if not 200 <= response.status_code < 300:
            try:
                detail = response.json()
            except ValueError:
                detail = {}
            error = detail.get("error", {}) if isinstance(detail, dict) else {}
            code = error.get("code") if isinstance(error, dict) else None
            if response.status_code == 410 or code == "artifact_expired":
                raise SystemExit("Artifact expired; retrieval cannot recover it. Check saved files first.")
            if code == "too_many_downloads":
                raise SystemExit("Download allowance exhausted; check saved files or contact support.")
            raise SystemExit(
                f"Download HTTP {response.status_code}, code={code}; "
                "inspect the saved task. Retry retrieval only if recoverable."
            )
        image_bytes = response.content
    if not image_bytes.startswith(b"\x89PNG\r\n\x1a\n"):
        raise SystemExit("Expected PNG bytes; stopped before saving or reusing the result.")
    destination = Path(stem + ".png")
    destination.write_bytes(image_bytes)
    print("Saved:", destination)
    return destination

600 saniyelik okuma zaman aşımı, istemci tarafında yapılan bir tercihtir; hizmetin gecikmesine ilişkin bir taahhüt değildir. PNG kontrolü bu eğiticide açıkça belirtilen çıktı biçimine uygundur; JPEG seçerseniz bunu uyarlayın.

Sık sorulan sorular

Seedream 5.5 için hangi model kimliği ve uç nokta kullanılmalı?
doubao-seedream-5-5 modelini POST /ai/v1/images/generations ve düz JSON ile kullanın. Başka bir yazımın veya eski bir adaptörün eşdeğer olduğunu varsaymayın.

Bu eğitimde test edilmiş üretim sonuçları yer alıyor mu?
Hayır. Kod, yalnızca yerel sözdizimi ve çevrimdışı yardımcı kontrolleriyle doğrulanmış belgelere dayanıyor. Herhangi bir çıkarım isteği, görsel kalitesi ölçümü, gecikme ölçümü veya faturalandırma testi gerçekleştirilmedi.

Asenkron işlem gerekli mi?
Hayır; varsayılan yöntem eşzamanlı beklemedir. Arka planda çalıştırmak için Boole değeri olan async: true kullanılır. Eşzamanlı bekleseniz bile yerel medya görev uç noktalarını kullanabilmek için hesabınızda görev özelliğinin etkinleştirilmiş olması gerekir.

HTTP 200, görselin başarıyla oluşturulduğu anlamına mı gelir?
Hayır. Görev durumunu ve hata bilgisini kontrol edin. HTTP isteği başarılı olsa bile görev başarısız olabilir; yalnızca görev tamamlandıktan sonra indirin.

Sonuç indirme URL'si, sonraki düzenleme için referans olarak kullanılabilir mi?
Bunun mümkün olduğunu varsaymayın. Görseli, oluşturma işlemini yapan API anahtarıyla indirin; ardından yerel görseli Data URI olarak kodlayın veya herkese açık gerçek bir görsel URL'si sağlayın.

Zaman aşımı veya yanıtın kaybolması durumunda ne yapılmalı?
Görsel üretme isteğini otomatik olarak tekrarlamayın. Kaydedilen görev kimliğini inceleyin veya oluşturma işlemini yapan API anahtarıyla görsel listesinden kurtarın. İstek kimliklerini saklayın; sonuç belirsizse destek ekibiyle iletişime geçin.

PNG'yi seçmek, şeffaf çıktı veya CNY 0.28 tutarında fatura garantiler mi?
İkisini de garanti etmez. Şemada doğrulanmış bir şeffaflık kontrolü yoktur. CNY 0.28, basında yer alan yaklaşık bir 2K düzenleme örneğidir; AIHubMix fiyat teklifi değildir ve metinden görsele üretim ile düzenleme için sabit fiyat anlamına gelmez.

Okumaya devam edin: Seedream 5.5 serisi

• Mevcut 5.0 Pro iş akışınızı değiştirmeden önce yükseltmeyi değerlendirin: Seedream 5.5 ve 5.0 Pro karşılaştırması: yükseltmeye değer mi?
• Aynı iş akışında farklı bir görsel modeli kullanma olanağınız varsa, artılarını ve eksilerini karşılaştırın: Seedream 5.5 ve GPT Image 2.6 Sunburst karşılaştırması: hangisini seçmelisiniz?

Kaynaklar

1. Seedream 5.5 lansman duyurusu — ByteDance Seed; sağlayıcının yetenek iddiaları.
2. Güncel Seedream 5.5 uç nokta şeması — AIHubMix; istek alanları ve modele özgü kısıtlamalar.
3. Birleşik görsel üretim API'si — AIHubMix; görevler, indirmeler ve güncel hatalar.
4. Seedream 5.5 model kılavuzu — AIHubMix; model kimliği ve kısa süre geçerli, kimlik doğrulamalı indirmeler. Uç noktaya özgü hatalar için birleşik API belgesine bakın.
5. Seedream 5.5 lansman haberleri — Sina Technology; resmî tarife olmayan yaklaşık düzenleme maliyeti senaryosu.