Instrukcja integracji API SeeDream Images Generation

Ten artykuł przedstawi instrukcję integracji API SeeDream Images Generation, które umożliwia generowanie oficjalnych obrazów SeeDream poprzez wprowadzenie niestandardowych parametrów.

Proces aplikacji

Aby korzystać z API SeeDream Images Generation, najpierw przejdź do konsoli Ace Data Cloud, aby uzyskać swój API Token i zachować go do późniejszego użycia.

Jeśli nie jesteś jeszcze zalogowany lub zarejestrowany, zostaniesz automatycznie przekierowany na stronę logowania z zaproszeniem do rejestracji i zalogowania się, a po zakończeniu automatycznie wrócisz na bieżącą stronę. Jeden API Token umożliwia wywoływanie wszystkich usług platformy, bez konieczności osobnego aplikowania dla każdej usługi. Przy pierwszej aplikacji otrzymasz bezpłatny limit do darmowego wypróbowania; gdy limit będzie niewystarczający, możesz doładować wspólne saldo w konsoli.

📘 Pełna dokumentacja: SeeDream Images Generation API →

Podstawowe użycie

Najpierw poznajmy podstawowy sposób użycia: wystarczy wprowadzić prompt prompt, działanie generowania action oraz rozmiar obrazu size, aby uzyskać przetworzony wynik. Najpierw należy po prostu przekazać pole action, którego wartością jest generate, a następnie musimy również wprowadzić prompt. Szczegółowa zawartość jest następująca:

Można zauważyć, że tutaj ustawiliśmy Request Headers, w tym:

accept: format odpowiedzi, który chcesz otrzymać; tutaj należy wpisać application/json, czyli format JSON.
authorization: klucz do wywoływania API, po aplikacji można go bezpośrednio wybrać z listy rozwijanej.

Dodatkowo ustawiono Request Body, w tym:

prompt: prompt.
model: model generowania, domyślnie doubao-seedream-5-0-lite-260128 (SeeDream 5.0 Lite, najnowszy). Obsługuje doubao-seedream-5-0-pro-260628, doubao-seedream-5-0-lite-260128, doubao-seedream-4-5-251128, doubao-seedream-4-0-250828. Wśród nich doubao-seedream-5-0-pro-260628 (SeeDream 5.0 Pro) jest flagowym modelem pojedynczego obrazu, generuje wyłącznie pojedyncze obrazy i nie obsługuje grup obrazów (sequential_image_generation), przesyłania strumieniowego (stream) ani wyszukiwania internetowego (tools). model musi otrzymać pełny ciąg modelu (np. doubao-seedream-5-0-lite-260128); przekazanie skrótu, takiego jak doubao-seedream-5.0-lite, zwróci 400.
image: informacje o obrazie wejściowym, obsługuje URL lub kodowanie Base64. doubao-seedream-5-0-pro-260628 obsługuje wejście z pojedynczym lub wieloma obrazami (maksymalnie 10), doubao-seedream-5-0-lite-260128, doubao-seedream-4-5-251128, doubao-seedream-4-0-250828 obsługują wejście z pojedynczym lub wieloma obrazami.
size: określa informacje o rozmiarze generowanego obrazu, obsługuje następujące dwie metody, których nie można mieszać. Metoda 1 | Określenie rozdzielczości generowanego obrazu oraz opisanie w prompt naturalnym językiem proporcji szerokości do wysokości obrazu. Obsługiwane ustawienia wstępne różnią się zależnie od modelu: doubao-seedream-5-0-pro-260628 obsługuje 1K/1.5K/2K; doubao-seedream-5-0-lite-260128 obsługuje 2K/3K/4K; doubao-seedream-4-5-251128 obsługuje tylko 2K/4K; doubao-seedream-4-0-250828 obsługuje 1K/2K/4K. Metoda 2 | Określenie wartości pikseli szerokości i wysokości generowanego obrazu: domyślnie 2048x2048; zakres całkowitej liczby pikseli oraz proporcji szerokości do wysokości zależy od modelu (na przykład zakres całkowitej liczby pikseli dla 5.0 Pro to [921600, 4624220], dolna granica całkowitej liczby pikseli dla 5.0 Lite / 4.5 wynosi 3,686,400, a dla 4.0 wynosi 921,600).
sequential_image_generation: grupa obrazów: grupa wygenerowanych obrazów, których treści są powiązane na podstawie wprowadzonych przez Ciebie treści. doubao-seedream-5-0-lite-260128, doubao-seedream-4-5-251128, doubao-seedream-4-0-250828 obsługują ten parametr, domyślnie disabled.
stream: kontroluje, czy włączyć tryb wyjścia strumieniowego. doubao-seedream-5-0-lite-260128, doubao-seedream-4-5-251128, doubao-seedream-4-0-250828 obsługują ten parametr, domyślnie jest to false.
response_format: określa format zwracany dla generowanego obrazu. Domyślnie jest to url, obsługiwany jest również b64_json.
watermark: czy dodać znak wodny do generowanego obrazu. Domyślnie jest to true.
output_format: określa format pliku generowanego obrazu, obsługuje jpeg (domyślny) i png. Obsługują go wyłącznie doubao-seedream-5-0-pro-260628 oraz doubao-seedream-5-0-lite-260128.
tools: konfiguruje narzędzia, które ma wywoływać model; obecnie obsługiwane jest web_search (wyszukiwanie internetowe). Obsługiwane wyłącznie przez Seedream 5.0 Lite.
optimize_prompt_options: konfiguracja optymalizacji promptów. 5.0 Pro obsługuje standard/fast; 5.0 Lite oraz 4.5 obsługują wyłącznie standard; 4.0 obsługuje standard/fast.
background: obsługiwane wyłącznie przez edycję pojedynczego obrazu 5.0 Pro. transparent wymaga wprowadzenia obrazu PNG z kanałem przezroczystości, a output_format musi mieć wartość png; opaque oznacza zwykłe nieprzezroczyste tło.
layer_decomposition: obsługiwane wyłącznie przez 5.0 Pro. Gdy ustawione na true, należy wprowadzić jeden obraz PNG/JPEG; można nie przekazywać prompt, aby automatycznie rozdzielić warstwy, lub określić elementy za pomocą języka naturalnego/<bbox>; size obsługuje auto/1K/1.5K/2K. Tego trybu nie można używać razem z grupami obrazów, przesyłaniem strumieniowym, wyszukiwaniem internetowym ani background.
callback_url: URL, na który należy przekazać wynik zwrotny.
async: czy przetwarzać w trybie asynchronicznym. Gdy ustawione na true, interfejs natychmiast zwraca task_id, bez konieczności podawania callback_url, a następnie wynik można uzyskać poprzez odpytywanie /seedream/tasks.

Po dokonaniu wyboru można zauważyć, że po prawej stronie również wygenerowano odpowiedni kod, jak pokazano na ilustracji:

Kliknij przycisk „Try”, aby przeprowadzić test. Jak pokazano powyżej, otrzymaliśmy tutaj następujący wynik:

{
  "success": true,
  "task_id": "80ceeed1-17d4-4eb7-82e0-18b34290f36e",
  "trace_id": "96b7fdc8-0fc8-4e2e-82a9-83c0a82f0a08",
  "data": [
    {
      "prompt": "A single matte blue cube centered on a clean white studio background, neutral lighting",
      "size": "2048x2048",
      "image_url": "https://cdn.acedata.cloud/assets/examples/seedream/db93b46e-c302-4676-8a11-63f0ba638a27-1c6f66f6b7e8.jpg"
    }
  ]
}

Wynik zwracany zawiera łącznie wiele pól, których opis jest następujący:

success, status zadania generowania wideo w tym momencie.
task_id, ID zadania generowania wideo w tym momencie.
trace_id, ID śledzenia generowania wideo w tym momencie.
data, lista wyników zadania generowania obrazu w tym momencie.
- image_url, link do zadania generowania obrazu w tym momencie.
- prompt, słowo kluczowe.
- size: piksele generowanego obrazu

Możemy zobaczyć, że uzyskaliśmy satysfakcjonujące informacje o obrazie, wystarczy pobrać wygenerowany obraz SeeDream na podstawie adresu linku obrazu data w wyniku. Ponadto, jeśli chcesz wygenerować odpowiedni kod integracyjny, możesz go bezpośrednio skopiować i wygenerować, na przykład kod CURL jest następujący:

curl -X POST 'https://api.acedata.cloud/seedream/images' \
-H 'accept: application/json' \
-H 'authorization: Bearer ${token}' \
-H 'content-type: application/json' \
-d '{
  "action": "generate",
  "model": "doubao-seedream-5-0-lite-260128",
  "prompt": "A single matte blue cube centered on a clean white studio background, neutral lighting"
}'

Zadanie edycji obrazu

Jeśli chcesz edytować określony obraz, najpierw parametr image musi przekazać link do obrazu, który wymaga edycji

model: model używany w tym zadaniu edycji obrazu, doubao-seedream-5-0-pro-260628, doubao-seedream-5-0-lite-260128, doubao-seedream-4-5-251128, doubao-seedream-4-0-250828 wszystkie obsługują wprowadzanie obrazu.
image: prześlij obraz wymagający edycji, jeden lub wiele

Przykład wypełnienia jest następujący:

Odpowiedni kod:

import requests

url = "https://api.acedata.cloud/seedream/images"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "doubao-seedream-4-0-250828",
  "prompt": "Keep the model pose and the liquid garment flowing shape unchanged. Change the clothing material from silver metal to completely transparent water (or glass). Through the liquid flow, the details of the model skin are visible. The light and shadow effect shifts from reflection to refraction.",
  "image": ["https://ark-project.tos-cn-beijing.volces.com/doc_image/seedream4_5_imageToimage.png"],
  "size": "2K",
  "watermark": False
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

Kliknij uruchom, można zauważyć, że natychmiast otrzymasz wynik, jak poniżej:

{
  "success": true,
  "task_id": "c9aaffa2-b8ac-40ff-8468-43e77cb9ddde",
  "trace_id": "131a40c3-2eaf-44c9-af28-c9b408577286",
  "data": [
    {
      "prompt": "Keep the model pose and the liquid garment flowing shape unchanged. Change the clothing material from silver metal to completely transparent water (or glass). Through the liquid flow, the details of the model skin are visible. The light and shadow effect shifts from reflection to refraction.",
      "size": "2048x2048",
      "image_url": "https://platform.cdn.acedata.cloud/seedream/3e88db7e-4771-4f6a-adbd-5ae4590c5d59.jpg"
    }
  ]
}

Można zobaczyć, że wygenerowany efekt jest efektem edycji oryginalnego obrazu, a wynik jest podobny do powyższego.

Rozdzielanie warstw (Seedream 5.0 Pro)

Rozdzielanie warstw rozdziela jeden obraz wejściowy na 1 obraz tła i maksymalnie 16 niezależnie edytowalnych przezroczystych warstw PNG. Poniższe żądanie pozwala modelowi automatycznie rozpoznać główne elementy; jeśli chcesz określić elementy, możesz dodać prompt, a także użyć znormalizowanych współrzędnych <bbox> w słowie kluczowym.

curl -X POST 'https://api.acedata.cloud/seedream/images' \
-H 'accept: application/json' \
-H 'authorization: Bearer ${token}' \
-H 'content-type: application/json' \
-d '{
  "model": "doubao-seedream-5-0-pro-260628",
  "image": "https://example.com/poster.png",
  "layer_decomposition": true,
  "size": "2K",
  "watermark": false
}'

Zwrócone data są uporządkowane od dołu do góry według z_index. z_index obrazu tła wynosi 0; warstwy zawierają również name, description oraz bounding_box.absolute/normalized. Podczas ponownego składania przy użyciu współrzędnych bezwzględnych przeskaluj warstwę do [right-left, bottom-top], umieść ją w [left, top], a następnie nakładaj według rosnącego z_index. Gdy generowanie dowolnej warstwy nie powiedzie się, całe rozdzielanie kończy się niepowodzeniem.

Wyjście strumieniowe

Gdy Lite/4.x ma ustawione stream: true, nagłówek żądania używa accept: application/x-ndjson. Interfejs zwraca wiersz po wierszu image_generation.partial_succeeded lub image_generation.partial_failed, a na końcu zwraca jedyne zdarzenie image_generation.completed oraz końcowe usage; tylko zdarzenie ukończenia powoduje jednokrotne naliczenie opłaty. Tryb strumieniowy nie może być używany razem z async lub callback_url.

Asynchroniczne wywołanie zwrotne

Ponieważ czas generowania przez SeeDream Images Generation API jest względnie długi, około 1–2 minut, jeśli API przez długi czas nie odpowiada, żądanie HTTP będzie stale utrzymywać połączenie, co prowadzi do dodatkowego zużycia zasobów systemowych, dlatego to API zapewnia również obsługę asynchronicznych wywołań zwrotnych. Ogólny proces jest następujący: gdy klient inicjuje żądanie, dodatkowo określa pole callback_url, po wysłaniu przez klienta żądania API, API natychmiast zwróci wynik zawierający informacje o polu task_id, reprezentującym bieżące ID zadania. Po ukończeniu zadania wynik wygenerowanego obrazu zostanie wysłany w formie POST JSON do callback_url określonego przez klienta, co również obejmuje pole task_id, dzięki czemu wyniki zadania mogą zostać powiązane przez ID. Jeśli nie masz publicznego adresu dostępnego do wywołania zwrotnego, możesz również nie określać callback_url, lecz ustawić pole async w żądaniu na true. W tym czasie interfejs również natychmiast zwróci task_id, ale nie wyśle wyniku, musisz użyć tego task_id, aby wywołać interfejs /seedream/tasks i cyklicznie odpytywać status zadania w celu uzyskania końcowego wyniku. Poniżej dowiemy się na przykładzie, jak konkretnie to zrobić. Kliknij uruchom, można zauważyć, że natychmiast otrzymasz wynik, jak poniżej:

{
  "task_id": "c9aaffa2-b8ac-40ff-8468-43e77cb9ddde"
}

Treść jest następująca:

{
    "success": true,
    "task_id": "c9aaffa2-b8ac-40ff-8468-43e77cb9ddde",
    "trace_id": "131a40c3-2eaf-44c9-af28-c9b408577286",
    "data": [
        {
            "prompt": "Keep the model pose and the liquid garment flowing shape unchanged. Change the clothing material from silver metal to completely transparent water (or glass). Through the liquid flow, the details of the model skin are visible. The light and shadow effect shifts from reflection to refraction.",
            "size": "2048x2048",
            "image_url": "https://platform.cdn.acedata.cloud/seedream/3e88db7e-4771-4f6a-adbd-5ae4590c5d59.jpg"
        }
    ]
}

Można zauważyć, że w wyniku znajduje się pole task_id, pozostałe pola są podobne do tych powyżej, a za pomocą tego pola można zrealizować powiązanie zadania.

Obsługa błędów

Podczas wywoływania API, jeśli wystąpi błąd, API zwróci odpowiedni kod błędu i informację. Na przykład:

400 token_mismatched：Nieprawidłowe żądanie, prawdopodobnie z powodu brakujących lub nieprawidłowych parametrów.
400 api_not_implemented：Nieprawidłowe żądanie, prawdopodobnie z powodu brakujących lub nieprawidłowych parametrów.
401 invalid_token：Brak autoryzacji, nieprawidłowy lub brakujący token autoryzacyjny.
429 too_many_requests：Zbyt wiele żądań, przekroczono limit szybkości.
500 api_error：Wewnętrzny błąd serwera, coś poszło nie tak na serwerze.

Przykład odpowiedzi błędu

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

Wnioski

Dzięki temu dokumentowi dowiedzieli się Państwo, jak korzystać z SeeDream Images Generation API, aby generować obrazy poprzez wprowadzanie promptów. Mamy nadzieję, że ten dokument pomoże Państwu lepiej integrować i używać tego API. W razie jakichkolwiek pytań prosimy o kontakt z naszym zespołem wsparcia technicznego.

Getting Started

Czat AI

Obraz AI

Wideo AI

Audio AI

Sieć i dane

CAPTCHA

Tożsamość

Coding

Więcej przewodników

Instrukcja integracji API SeeDream Images Generation

Proces aplikacji

Podstawowe użycie

Zadanie edycji obrazu

Rozdzielanie warstw (Seedream 5.0 Pro)

Wyjście strumieniowe

Asynchroniczne wywołanie zwrotne

Obsługa błędów

Przykład odpowiedzi błędu

Wnioski

​Proces aplikacji

​Podstawowe użycie

​Zadanie edycji obrazu

​Rozdzielanie warstw (Seedream 5.0 Pro)

​Wyjście strumieniowe

​Asynchroniczne wywołanie zwrotne

​Obsługa błędów

​Przykład odpowiedzi błędu

​Wnioski

Proces aplikacji

Podstawowe użycie

Zadanie edycji obrazu

Rozdzielanie warstw (Seedream 5.0 Pro)

Wyjście strumieniowe

Asynchroniczne wywołanie zwrotne

Obsługa błędów

Przykład odpowiedzi błędu

Wnioski