Seedream v4.5 Edit API: Programmatyczne Edytowanie Obrazów

Uruchamianie Seedream v4.5 Edit za pośrednictwem interfejsu Arteza działa w przypadku jednorazowych edycji i małych partii. W przypadku przepływów pracy o dużej skali - katalogi z tysiącami SKU, dynamiczne generowanie obrazów dla poszczególnych użytkowników, potoki zasobów sterowane CMS - chcesz mieć dostęp do API. Ten przewodnik przeprowadza Cię przez strukturę punktu końcowego, parametry żądania, obsługę odpowiedzi i wzorce produkcyjne do budowania zautomatyzowanych systemów edycji obrazów w Seedream v4.5.

Dlaczego warto używać API

API odblokowuje wzorce automatyzacji, których interfejs nie może osiągnąć:

• Wsadowe przetwarzanie o dużej skali. Przetwarzaj ponad 1000 edycji w pojedynczym przebiegu potoku.
• Dynamiczne generowanie. Buduj obrazy na żądanie na podstawie danych użytkownika lub rekordów bazy danych.
• Zaplanowane przepływy pracy. Nocne aktualizacje katalogów, regeneracja wyzwalana zdarzeniami.
• Integracja z istniejącymi stosami. Node.js, Python, Go, Ruby - dowolny klient HTTP.
• Reprodukowalna produkcja. Skrypty kontrolowane wersją zamiast ręcznych kliknięć.

Jeśli Twój przypadek użycia obejmuje więcej niż 20-50 podobnych edycji, warto skonfigurować API.

Struktura punktu końcowego

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

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

To standardowy punkt końcowy modelu fal.ai, który można wywoływać bezpośrednio lub za pośrednictwem systemu kredytów Arteza.

Uwierzytelnianie

Żądania API Arteza są uwierzytelnianie za pośrednictwem klucza API przekazywanego w nagłówku Authorization jako token Bearer.

Uzyskanie klucza 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 go jak hasło

Nigdy nie zatwierdzaj klucza API do kontroli źródła. Użyj zmiennych środowiskowych:

export SEEDANCE_API_KEY="your_api_key_here"

Nagłówek uwierzytelniania

Authorization: Bearer your_api_key_here

Struktura żądania

Podstawowe żądanie 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"
}

Odniesienie parametrów

Można przekazać do 10 adresów URL obrazów. Model traktuje pierwszy obraz jako główny i następne obrazy jako odniesienia.

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 wygenerowane adresy URL 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 z zwróconego adresu URL - wyjściowe adresy URL są ważne przez 24 godziny.

Asynchroniczny wzorzec generowania

Seedream v4.5 Edit zajmuje 30-60 sekund na żądanie. W produkcji prawdopodobnie będziesz chciał asynchroniczne generowanie z webhooks lub pollingiem zamiast blokowania żądań.

Asynchroniczny oparty na Webhook

Przekaż webhook_url w swoim żądaniu, a Arteza opublikuje wynik do niego po zakończeniu generowania:

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

Twój moduł obsługi webhook odbiera:

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

Obsługa webhook jest zalecanym wzorcem produkcyjnym.

Zacznij budować. Spróbuj narzędzia.

Asynchroniczny oparty na Polling

Jeśli Twoja infrastruktura nie może odbierać webhook, sprawdzaj status pollingiem:

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;
}

Polling co 5-10 sekund. Całkowity czas oczekiwania wynosi zwykle 30-60 sekund.

Wzorce produkcyjne

Wzorzec 1: Wsadowe generowanie katalogów

Uruchom API w swoim katalogu produktów, aby wygenerować spójne zamiany 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 modułem obsługi webhook, który zapisuje wyniki na CDN i aktualizuje rekord produktu.

Wzorzec 2: Edycje użytkownika na żądanie

Pozwól użytkownikom przesyłać obrazy i uzyskiwać wyniki edytowane przez AI na żądanie:

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

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

Wzorzec 3: Potok zasobów sterowany CMS

Po opublikowaniu zawartości w CMS, auto-generuj powiązane obrazy:

1. CMS emituje zdarzenie publikacji
2. Wyzwala funkcję bezserwerową
3. Wywołuje Seedream v4.5 Edit z promptem szablonu
4. Przechowuje wynik na CDN
5. Aktualizuje rekord CMS za pomocą adresu URL obrazu

Ten wzorzec eliminuje ręczne tworzenie obrazów dla publikowania o dużej skali.

Obsługa błędów

Wspólne odpowiedzi na błędy:

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

Limity szybkości

Arteza stosuje rozsądne limity szybkości na API. W przypadku większości przepływów pracy produkcyjnych nie osiągniesz ich, ale w przypadku masowych partii ponad 1000 żądań, zaimplementuj:

• Wykładnicze wycofanie na odpowiedzi 429
• Limity równoczesnych żądań (zacznij od 5 równolegle, dostraj w górę)
• Kolejkowanie żądań dla przewidywalnej przepustowości

Skontaktuj się z pomocą techniczną, aby uzyskać wyższe limity szybkości dla dużych obciążeń produkcyjnych.

Koszt na głośności API

Wywołania API kosztują tyle samo co wywołania interfejsu: 8 punktów ($0.08) na obraz. Do celów planowania:

• 100 wywołań API = 800 punktów (warstwa Starter, 10 dolarów)
• 1000 wywołań API = 8000 punktów (warstwa Pro, 50 dolarów)
• 10000 wywołań API = 80000 punktów (wiele warstw Studio, około 650 dolarów)

W przypadku wolumenów przekraczających 10000/miesiąc skontaktuj się z zespołem, aby uzyskać niestandardową wycenę.

Najlepsze praktyki

1. Używaj webhook w produkcji. Polling działa, ale marnuje zasoby.
2. Przechowuj prompty w kontroli wersji. Traktuj prompty jak kod.
3. Rejestruj wszystko. Identyfikatory żądań, prompty, wyniki, błędy.
4. Weryfikuj dane wejściowe przed wywołaniem. Złe adresy URL obrazów marnują kredyty.
5. Monitoruj saldo kredytów. Alertuj, gdy spadnie poniżej progu.
6. Testuj zmiany promptów w środowisku przejściowym. Zweryfikuj na 3-5 obrazach przed uruchomieniem pełnej partii.
7. Wyniki pamięci podręcznej. Jeśli dane wejściowe są identyczne, ponownie użyj poprzednich wyników.

Dalsze czytanie

• Kompletny przewodnik edycji Seedream v4.5
• Poradnik edycji wsadowej
• Podział cen

Zacznij

Wygeneruj klucz API na pulpicie nawigacyjnym Arteza, weź 50 bezpłatnych kredytów i uruchom przykład Node.js powyżej ze zdjęciem produktu. API odblokowuje pełny potencjał produkcji Seedream v4.5 Edit - po podłączeniu wszystko inne to inżynieria promptu. Aby najpierw przetestować praktycznie, otwórz narzędzie internetowe i zweryfikuj swoje prompty przed automatyzacją.