SeeDream Images Generation API Integracja Opis

Ten dokument przedstawi sposób integracji z SeeDream Images Generation API, który pozwala na generowanie oficjalnych obrazów SeeDream poprzez wprowadzenie niestandardowych parametrów.

Proces aplikacji

Aby korzystać z SeeDream Images Generation API, najpierw przejdź do konsoli Ace Data Cloud, aby uzyskać swój token API, który należy zachować na przyszłość.

Jeśli nie jesteś zalogowany lub zarejestrowany, automatycznie zostaniesz przekierowany na stronę logowania, aby zarejestrować się i zalogować, a po zakończeniu zostaniesz automatycznie przekierowany z powrotem na bieżącą stronę. Jeden token API wystarczy do wywołania wszystkich usług platformy, nie ma potrzeby składania osobnych wniosków dla każdej usługi. Przy pierwszym wniosku otrzymasz darmowy limit, aby móc skorzystać z usługi; gdy limit się wyczerpie, możesz doładować saldo ogólne w konsoli.

📘 Pełna dokumentacja: SeeDream Images Generation API →

Podstawowe użycie

Najpierw zapoznaj się z podstawowym sposobem użycia, czyli wprowadzeniem słowa kluczowego prompt, działania action, rozmiaru obrazu size, aby uzyskać przetworzony wynik. Najpierw musimy przekazać pole action, którego wartość to generate, a następnie musimy wprowadzić słowo kluczowe, szczegóły są następujące:

Możemy zobaczyć, że ustawiliśmy nagłówki żądania, w tym:

accept: jakiego formatu odpowiedzi oczekujesz, tutaj wpisujemy application/json, czyli format JSON.
authorization: klucz do wywołania API, po złożeniu wniosku można go bezpośrednio wybrać z rozwijanej listy.

Dodatkowo ustawiono ciało żądania, w tym:

prompt: słowo kluczowe.
model: model generacji, domyślnie doubao-seedream-5-0-260128 (SeeDream 5.0 Lite, najnowszy). Obsługuje doubao-seedream-5-0-pro-260628, doubao-seedream-5-0-260128 (akceptuje również oficjalny alias doubao-seedream-5-0-lite-260128), doubao-seedream-4-5-251128, doubao-seedream-4-0-250828. Model doubao-seedream-5-0-pro-260628 (SeeDream 5.0 Pro) to flagowy model pojedynczego obrazu, generuje tylko pojedynczy obraz, nie obsługuje grup obrazów (sequential_image_generation), strumieniowego (stream) ani wyszukiwania w sieci (tools). model musi być przekazany jako pełny ciąg modelu (np. doubao-seedream-5-0-260128), przekazanie skrótu takiego jak doubao-seedream-5.0-lite zwróci 400.
image: informacje o wprowadzonym obrazie, obsługuje URL lub kodowanie Base64. doubao-seedream-5-0-pro-260628 obsługuje pojedynczy lub wiele obrazów (wiele obrazów 2-10, od drugiego obrazu naliczana jest opłata), doubao-seedream-5-0-260128, doubao-seedream-4-5-251128, doubao-seedream-4-0-250828 obsługują pojedynczy lub wiele obrazów.
size: określa informacje o rozmiarze generowanego obrazu, obsługuje dwie poniższe metody, które nie mogą być mieszane. Metoda 1 | Określenie rozdzielczości generowanego obrazu i opisanie proporcji szerokości i wysokości w naturalnym języku w prompt. Obsługiwane wstępne ustawienia różnią się w zależności od modelu: doubao-seedream-5-0-pro-260628 obsługuje 1K/1.5K/2K; doubao-seedream-5-0-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, całkowita liczba pikseli i proporcje szerokości i wysokości różnią się w zależności od modelu (na przykład 5.0 Pro całkowity zakres pikseli [921600, 4624220], 5.0 Lite / 4.5 dolny limit całkowitych pikseli 3,686,400, 4.0 dolny limit 921,600).
sequential_image_generation: grupy obrazów: na podstawie wprowadzonych treści generowane są powiązane obrazy. doubao-seedream-5-0-260128, doubao-seedream-4-5-251128, doubao-seedream-4-0-250828 obsługują ten parametr, domyślnie disabled.
stream: kontroluje, czy włączyć tryb strumieniowy. doubao-seedream-5-0-260128, doubao-seedream-4-5-251128, doubao-seedream-4-0-250828 obsługują ten parametr, domyślnie jest false.
response_format: określa format zwracany dla generowanego obrazu. Domyślnie jest url, obsługuje również b64_json.
watermark: czy dodać znak wodny do generowanego obrazu. Domyślnie jest true.
output_format: określa format pliku generowanego obrazu, obsługuje jpeg (domyślnie) i png. Tylko doubao-seedream-5-0-pro-260628 i doubao-seedream-5-0-260128 obsługują.
tools: konfiguruje narzędzia, które model ma wywołać, obecnie obsługuje web_search (wyszukiwanie w sieci). Tylko Seedream 5.0 Lite obsługuje.
optimize_prompt_options: konfiguracja optymalizacji słów kluczowych. 5.0 Pro obsługuje standard/fast; 5.0 Lite i 4.5 obsługują tylko standard; 4.0 obsługuje standard/fast.
background: tylko 5.0 Pro obsługuje edycję pojedynczego obrazu. transparent wymaga wprowadzenia obrazu PNG z przezroczystym kanałem, a output_format musi być png; opaque to zwykłe nieprzezroczyste tło.
layer_decomposition: tylko 5.0 Pro obsługuje. Ustawione na true, musi być wprowadzony obraz PNG/JPEG, można nie przekazywać prompt do automatycznego podziału lub użyć naturalnego języka/<bbox> do określenia elementów; size obsługuje auto/1K/1.5K/2K. Ten tryb nie może być używany z grupami obrazów, strumieniowym, wyszukiwaniem w sieci lub background.
callback_url: URL, na który mają być zwracane wyniki.
async: czy przetwarzać w trybie asynchronicznym. Ustawione na true, interfejs natychmiast zwraca task_id, nie ma potrzeby podawania callback_url, a następnie można uzyskać wyniki poprzez /seedream/tasks.

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

Kliknij przycisk „Try”, aby przeprowadzić test, jak pokazano na powyższym obrazku, tutaj uzyskaliśmy następujący wynik:

{
  "success": true,
  "task_id": "81246f86-05ff-4d7d-9553-1013e0c1cd32",
  "trace_id": "ab50a78d-ab1f-457f-a46b-c2259cd5d35b",
  "data": [
    {
      "prompt": "Fotorealistyczne zdjęcie produktu w studiu przedstawiające butelkę perfum z matowego szkła na mokrym czarnym łupku, pojedyncze światło kluczowe z softboxa, krople wody, ciemne nastrojowe tło, 85mm makro.",
      "size": "2048x2048",
      "image_url": "https://platform2.cdn.acedata.cloud/seedream/901c6af6-e83a-4849-b233-295f6c20bacb.jpg"
    }
  ]
}

Zwrócone wyniki zawierają wiele pól, które są opisane poniżej:

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: rozmiar wygenerowanego obrazu w pikselach.

Możemy zobaczyć, że otrzymaliśmy satysfakcjonujące informacje o obrazie, wystarczy, że uzyskamy wygenerowany obraz SeeDream z adresu linku data. Jeśli chcesz wygenerować odpowiedni kod do integracji, możesz po prostu skopiować wygenerowany kod, na przykład kod CURL wygląda następująco:

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-260128",
  "prompt": "Fotorealistyczne zdjęcie produktu w studiu przedstawiające butelkę perfum z matowego szkła na mokrym czarnym łupku, pojedyncze światło kluczowe z softboxa, krople wody, ciemne nastrojowe tło, 85mm makro."
}'

Edytowanie zadania obrazka

Jeśli chcesz edytować dany obrazek, najpierw parametr image musi zawierać link do obrazu, który ma być edytowany.

model: model użyty w tym zadaniu edytowania obrazu, doubao-seedream-5-0-pro-260628, doubao-seedream-5-0-260128, doubao-seedream-4-5-251128, doubao-seedream-4-0-250828 obsługują wejście obrazowe.
image: przesyłany obraz do edycji, jeden lub więcej.

Przykład wypełnienia wygląda następująco:

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": "Zachowaj pozę modelu i kształt płynącego materiału odzieżowego bez zmian. Zmień materiał odzieżowy z srebrnego metalu na całkowicie przezroczystą wodę (lub szkło). Przez płynny przepływ widoczne są szczegóły skóry modelu. Efekt światła i cienia zmienia się z odbicia na refrakcję.",
  "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)

Klikając uruchom, można zauważyć, że natychmiast otrzymamy wynik, jak poniżej:

{
  "success": true,
  "task_id": "c9aaffa2-b8ac-40ff-8468-43e77cb9ddde",
  "trace_id": "131a40c3-2eaf-44c9-af28-c9b408577286",
  "data": [
    {
      "prompt": "Zachowaj pozę modelu i kształt płynącego materiału odzieżowego bez zmian. Zmień materiał odzieżowy z srebrnego metalu na całkowicie przezroczystą wodę (lub szkło). Przez płynny przepływ widoczne są szczegóły skóry modelu. Efekt światła i cienia zmienia się z odbicia na refrakcję.",
      "size": "2048x2048",
      "image_url": "https://platform.cdn.acedata.cloud/seedream/3e88db7e-4771-4f6a-adbd-5ae4590c5d59.jpg"
    }
  ]
}

Można zauważyć, że wygenerowany efekt to efekt edytowania oryginalnego obrazu, wynik jest podobny do powyższego.

Rozdzielanie warstw (Seedream 5.0 Pro)

Rozdzielanie warstw podzieli jeden wejściowy obraz na 1 obraz podstawowy i maksymalnie 16 niezależnych, edytowalnych przezroczystych warstw PNG. Poniższe żądanie pozwala modelowi automatycznie rozpoznać główne elementy; jeśli chcesz określić elementy, możesz dodać prompt, możesz również użyć znormalizowanych współrzędnych <bbox> w słowach kluczowych.

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

Zwracane data są uporządkowane według z_index od dołu do góry. z_index obrazu podstawowego wynosi 0; warstwy zawierają również name, description oraz bounding_box.absolute/normalized. Podczas rekonstrukcji z użyciem współrzędnych absolutnych, warstwy są skalowane do [right-left, bottom-top], umieszczane w [left, top], a następnie nakładane w porządku rosnącym według z_index. Jeśli jakakolwiek warstwa nie powiedzie się w generacji, całe rozdzielenie nie powiedzie się.

Strumieniowe wyjście

W przypadku Lite/4.x, gdy ustawisz stream: true, nagłówek żądania używa accept: application/x-ndjson. Interfejs zwraca wierszami image_generation.partial_succeeded lub image_generation.partial_failed, a na końcu zwraca unikalne zdarzenie image_generation.completed oraz ostateczne usage; tylko zdarzenie zakończenia wywołuje jednorazowe naliczenie opłaty. Tryb strumieniowy nie może być używany razem z async lub callback_url.

Asynchroniczny callback

Ponieważ czas generowania API SeeDream Images Generation jest stosunkowo długi, wynosi około 1-2 minut, jeśli API nie odpowiada przez dłuższy czas, żądanie HTTP będzie utrzymywać połączenie, co prowadzi do dodatkowego zużycia zasobów systemowych, dlatego to API oferuje również wsparcie dla asynchronicznych callbacków. Cały proces polega na tym, że klient inicjuje żądanie, dodatkowo określając pole callback_url, po zainicjowaniu żądania API, API natychmiast zwraca wynik, zawierający pole task_id, które reprezentuje aktualne ID zadania. Po zakończeniu zadania, wynik wygenerowanego obrazu zostanie wysłany do określonego przez klienta callback_url w formie POST JSON, który również zawiera pole task_id, dzięki czemu wynik zadania można powiązać z ID. Jeśli nie masz publicznego adresu do callbacku, możesz nie określać callback_url, a zamiast tego ustawić pole async na true w żądaniu. W tym przypadku 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, aby sprawdzić status zadania i uzyskać ostateczny wynik. Poniżej przedstawiamy przykład, aby zrozumieć, jak dokładnie to działa. Klikając uruchom, można zauważyć, że natychmiast otrzymamy wynik, jak poniżej:

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

Zawartość jest następująca:

```json
{
    "success": true,
    "task_id": "c9aaffa2-b8ac-40ff-8468-43e77cb9ddde",
    "trace_id": "131a40c3-2eaf-44c9-af28-c9b408577286",
    "data": [
        {
            "prompt": "Zachowaj pozę modelu i kształt płynącej odzieży w stanie niezmienionym. Zmień materiał odzieży z srebrnego metalu na całkowicie przezroczystą wodę (lub szkło). Przez płynny przepływ widoczne są detale skóry modelu. Efekt światła i cienia zmienia się z odbicia na załamanie.",
            "size": "2048x2048",
            "image_url": "https://platform.cdn.acedata.cloud/seedream/3e88db7e-4771-4f6a-adbd-5ae4590c5d59.jpg"
        }
    ]
}

Można zauważyć, że w wynikach znajduje się pole task_id, a pozostałe pola są podobne do powyższych, dzięki czemu można zrealizować powiązanie z zadaniem.

Obsługa błędów

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

400 token_mismatched: Złe żądanie, prawdopodobnie z powodu brakujących lub nieprawidłowych parametrów.
400 api_not_implemented: Złe żądanie, prawdopodobnie z powodu brakujących lub nieprawidłowych parametrów.
401 invalid_token: Nieautoryzowany, nieprawidłowy lub brakujący token autoryzacyjny.
429 too_many_requests: Zbyt wiele żądań, przekroczono limit szybkości.
500 api_error: Błąd wewnętrzny serwera, coś poszło nie tak na serwerze.

Przykład odpowiedzi błędu

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "pobieranie nie powiodło się"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

Wnioski

Dzięki temu dokumentowi zrozumieliście, jak korzystać z API generowania obrazów SeeDream, które pozwala na generowanie obrazów na podstawie wprowadzonych podpowiedzi. Mamy nadzieję, że ten dokument pomoże Wam lepiej zintegrować i korzystać z 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ść

Proxy

Advanced

Coding

SeeDream Images Generation API Integracja Opis

Proces aplikacji

Podstawowe użycie

Edytowanie zadania obrazka

Rozdzielanie warstw (Seedream 5.0 Pro)

Strumieniowe wyjście

Asynchroniczny callback

Obsługa błędów

Przykład odpowiedzi błędu

Wnioski

​Proces aplikacji

​Podstawowe użycie

​Edytowanie zadania obrazka

​Rozdzielanie warstw (Seedream 5.0 Pro)

​Strumieniowe wyjście

​Asynchroniczny callback

​Obsługa błędów

​Przykład odpowiedzi błędu

​Wnioski

Proces aplikacji

Podstawowe użycie

Edytowanie zadania obrazka

Rozdzielanie warstw (Seedream 5.0 Pro)

Strumieniowe wyjście

Asynchroniczny callback

Obsługa błędów

Przykład odpowiedzi błędu

Wnioski