Seedream v4.5 Edit API: programowe edytowanie obrazów

Korzystanie z Seedream v4.5 Edit przez interfejs Arteza sprawdza się przy pojedynczych edycjach i małych partiach. W przypadku procesów o dużej skali, takich jak katalogi z tysiącami SKU, dynamiczne generowanie obrazów per użytkownik czy potoki zasobów sterowane przez CMS, warto sięgnąć po dostęp przez API. Ten przewodnik omawia strukturę endpointu, parametry żądań, obsługę odpowiedzi i wzorce produkcyjne do budowania zautomatyzowanych systemów edycji obrazów na bazie Seedream v4.5.

W skrócie

• Seedream v4.5 Edit jest dostępny przez endpoint fal-ai/bytedance/seedream/v4.5/edit
• Takie same kredyty 1 ($0,10) za obraz jak w interfejsie
• Przyjmuje do 10 adresów URL obrazów wejściowych oraz prompt tekstowy
• Wyjście 4 MP (2048x2048) zwracane jako adres URL obrazu
• Typowy czas generowania 30-60 sekund, do produkcji używaj wzorców asynchronicznych

Dlaczego warto korzystać z API

API otwiera możliwości automatyzacji, których interfejs nie zapewnia:

• Przetwarzanie wsadowe na dużą skalę. Przetwarzaj ponad 1000 edycji w jednym przebiegu potoku.
• Dynamiczne generowanie. Twórz obrazy na żądanie na podstawie danych użytkownika lub rekordów z bazy danych.
• Zaplanowane przepływy pracy. Nocne aktualizacje katalogów, regeneracja wyzwalana zdarzeniami.
• Integracja z istniejącymi stosami. Node.js, Python, Go, Ruby i każdy klient HTTP.
• Odtwarzalna produkcja. Skrypty pod kontrolą wersji zamiast ręcznych kliknięć.

Jeśli Twój przypadek użycia obejmuje więcej niż 20-50 podobnych edycji, wdrożenie API jest opłacalne.

Struktura endpointu

Model Seedream v4.5 Edit jest dostępny pod adresem:

fal-ai/bytedance/seedream/v4.5/edit

Jest to standardowy endpoint modelu fal.ai, który można wywoływać bezpośrednio lub przez system kredytów Arteza.

Uwierzytelnianie

Żądania do API Arteza są uwierzytelniane za pomocą klucza API przekazywanego w nagłówku Authorization jako token Bearer.

Jak uzyskać klucz API

1. Zaloguj się na arteza.ai
2. Przejdź do ustawień konta
3. Znajdź sekcję API
4. Wygeneruj nowy klucz API
5. Przechowuj go bezpiecznie, traktuj jak hasło

Nigdy nie umieszczaj klucza API w repozytorium kodu. Używaj zmiennych środowiskowych:

export SEEDANCE_API_KEY="your_api_key_here"

Nagłówek uwierzytelniania

Authorization: Bearer your_api_key_here

Struktura żądania

Podstawowe żądanie do Seedream v4.5 Edit wygląda następująco:

{
  "prompt": "Replace the background with a polished marble surface. Preserve the product position, color, and lighting exactly. Add a subtle contact shadow.",
  "image_urls": [
    "https://your-bucket.com/product-shot.jpg"
  ],
  "num_images": 1,
  "output_format": "png"
}

Dokumentacja parametrów

Można przekazać do 10 adresów URL obrazów. Model traktuje pierwszy obraz jako główny, a kolejne jako referencje.

Przykładowe żądanie: Node.js

const response = await fetch("https://api.arteza.ai/v1/seedream/v4.5/edit", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.SEEDANCE_API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    prompt: "Replace the background with a polished marble surface. Preserve the product position, color, and lighting exactly.",
    image_urls: [
      "https://your-bucket.com/product-shot.jpg"
    ],
    num_images: 1,
    output_format: "png"
  })
});

const result = await response.json();
console.log(result.images[0].url);

Przykładowe żądanie: Python

import os
import requests

response = requests.post(
    "https://api.arteza.ai/v1/seedream/v4.5/edit",
    headers={
        "Authorization": f"Bearer {os.environ['SEEDANCE_API_KEY']}",
        "Content-Type": "application/json"
    },
    json={
        "prompt": "Replace the background with a polished marble surface. Preserve the product position, color, and lighting exactly.",
        "image_urls": [
            "https://your-bucket.com/product-shot.jpg"
        ],
        "num_images": 1,
        "output_format": "png"
    }
)

result = response.json()
print(result["images"][0]["url"])

Struktura odpowiedzi

Pomyślna odpowiedź zawiera adresy URL wygenerowanych obrazów:

{
  "images": [
    {
      "url": "https://storage.arteza.ai/output/abc123.png",
      "width": 2048,
      "height": 2048,
      "content_type": "image/png"
    }
  ],
  "seed": 123456789,
  "credits_used": 8
}

Pobierz obraz ze zwróconego adresu URL. Adresy URL wyników są ważne przez 24 godziny.

Wzorzec asynchronicznego generowania

Seedream v4.5 Edit potrzebuje 30-60 sekund na żądanie. W produkcji zaleca się asynchroniczne generowanie z webhookami lub odpytywaniem (polling) zamiast blokowania żądań.

Asynchroniczność oparta na webhookach

Przekaż webhook_url w żądaniu, a Arteza prześle wynik metodą POST, gdy generowanie zostanie ukończone:

{
  "prompt": "...",
  "image_urls": ["..."],
  "webhook_url": "https://your-app.com/webhooks/seedream"
}

Twój handler webhooka otrzymuje:

{
  "request_id": "req_abc123",
  "status": "completed",
  "images": [
    {
      "url": "https://storage.arteza.ai/output/xyz.png"
    }
  ]
}

Obsługa webhooków to zalecany wzorzec produkcyjny.

Zacznij budować. Najpierw wypróbuj narzędzie.

Asynchroniczność oparta na odpytywaniu

Jeśli Twoja infrastruktura nie może odbierać webhooków, sprawdzaj status przez odpytywanie:

const initResponse = await fetch("https://api.arteza.ai/v1/seedream/v4.5/edit", {
  method: "POST",
  headers: { "Authorization": `Bearer ${key}`, "Content-Type": "application/json" },
  body: JSON.stringify({ prompt, image_urls, async: true })
});

const { request_id } = await initResponse.json();

// Poll for completion
let result;
while (!result) {
  await new Promise(r => setTimeout(r, 5000));
  const statusResponse = await fetch(
    `https://api.arteza.ai/v1/requests/${request_id}`,
    { headers: { "Authorization": `Bearer ${key}` } }
  );
  const status = await statusResponse.json();
  if (status.status === "completed") result = status;
}

Odpytuj co 5-10 sekund. Łączny czas oczekiwania wynosi zazwyczaj 30-60 sekund.

Wzorce produkcyjne

Wzorzec 1: Wsadowe generowanie katalogu

Uruchom API na całym katalogu produktów, aby wygenerować spójne podmiany tła dla każdego SKU:

for product in catalog:
    response = requests.post(
        API_URL,
        headers=HEADERS,
        json={
            "prompt": PROMPT_TEMPLATE.format(product_name=product.name),
            "image_urls": [product.source_image_url],
            "webhook_url": WEBHOOK_URL
        }
    )
    log_request(product.id, response.json()["request_id"])

Połącz z handlerem webhooka, który zapisuje wyniki na CDN i aktualizuje rekord produktu.

Wzorzec 2: Edycje na żądanie użytkownika

Pozwól użytkownikom przesyłać obrazy i otrzymywać wyniki edycji AI na żądanie:

1. Użytkownik przesyła obraz do Twojego bucketa
2. Twój backend wywołuje Seedream v4.5 Edit z promptem wybranym przez użytkownika
3. Odpytuj lub czekaj na webhooka
4. Zwróć adres URL wyniku do klienta użytkownika

Zaplanuj w UX około 60 sekund czasu oczekiwania na edycję.

Wzorzec 3: Potok zasobów sterowany przez CMS

Gdy treść jest publikowana w CMS, automatycznie generuj powiązane obrazy:

1. CMS emituje zdarzenie publikacji
2. Wyzwalana jest funkcja bezserwerowa
3. Wywołuje Seedream v4.5 Edit z szablonem promptu
4. Zapisuje wynik na CDN
5. Aktualizuje rekord CMS z adresem URL obrazu

Ten wzorzec eliminuje ręczne tworzenie obrazów przy publikowaniu dużych ilości treści.

Obsługa błędów

Typowe odpowiedzi błędów:

Zawsze owijaj wywołania API w blok try/except z logiką ponawiania dla odpowiedzi 429 i 500.

Limity żądań

Arteza stosuje rozsądne limity żądań do API. W przypadku większości produkcyjnych przepływów pracy nie zostaną one przekroczone, ale przy partiach powyżej 1000 żądań wdróż:

• Wykładnicze wycofanie przy odpowiedziach 429
• Limity równoległych żądań (zacznij od 5 jednoczesnych, dostrajaj w górę)
• Kolejkowanie żądań dla przewidywalnej przepustowości

Skontaktuj się z pomocą techniczną w celu uzyskania wyższych limitów przy intensywnych obciążeniach produkcyjnych.

Koszt przy dużym wolumenie API

Wywołania API kosztują tyle samo co wywołania przez interfejs: 1 kredytów ($0,10) za obraz. Dla celów planowania:

• 100 wywołań API = 100 kredytów (z zapasem w ramach planu Starter za $5)
• 1000 wywołań API = 1000 kredytów (plan Studio za $120, 1800 miesięcznie)
• 10 000 wywołań API = 10 000 kredytów (plan Studio za $120 plus około 8200 kredytów w doładowaniach)

Przy wolumenie powyżej 10 000 miesięcznie skontaktuj się z zespołem w sprawie indywidualnej wyceny.

Najlepsze praktyki

1. W produkcji używaj webhooków. Odpytywanie działa, ale marnuje zasoby.
2. Przechowuj prompty w systemie kontroli wersji. Traktuj prompty jak kod.
3. Loguj wszystko. Identyfikatory żądań, prompty, wyniki, błędy.
4. Sprawdzaj dane wejściowe przed wywołaniem. Złe adresy URL obrazów marnują kredyty.
5. Monitoruj saldo kredytów. Ustaw alert, gdy saldo spadnie poniżej progu.
6. Testuj zmiany promptów w środowisku staging. Sprawdź na 3-5 obrazach przed uruchomieniem pełnej partii.
7. Zapisuj wyniki w pamięci podręcznej. Jeśli dane wejściowe są identyczne, używaj poprzednich wyników.

Dalsze zasoby

• Kompletny przewodnik po edycji Seedream v4.5
• Samouczek edycji wsadowej
• Zestawienie cen

Pierwsze kroki

Wygeneruj klucz API w panelu Arteza, pobierz 10 darmowych kredytów i uruchom powyższy przykład Node.js z zdjęciem produktu. API odblokowuje pełny potencjał produkcyjny Seedream v4.5 Edit. Gdy już je podłączysz, reszta to inżynieria promptów. Aby najpierw przetestować ręcznie, otwórz narzędzie webowe i zweryfikuj prompty przed automatyzacją.