Instrukcja integracji SeeDream Images Generation API

Niniejszy dokument przedstawia instrukcję integracji SeeDream Images Generation API, które umożliwia generowanie oficjalnych obrazów SeeDream na podstawie wprowadzonych niestandardowych parametrów.

Proces rejestracji

Aby korzystać z API, należy najpierw zarejestrować odpowiednią usługę na stronie SeeDream Images Generation API. Po wejściu na stronę kliknij przycisk „Acquire”, jak pokazano na obrazku:

Jeśli nie jesteś zalogowany lub zarejestrowany, zostaniesz automatycznie przekierowany na stronę logowania, gdzie możesz się zarejestrować i zalogować. Po zalogowaniu zostaniesz automatycznie przeniesiony z powrotem na bieżącą stronę. Przy pierwszym zgłoszeniu otrzymasz darmowy limit, który pozwala na bezpłatne korzystanie z API.

Podstawowe użycie

Najpierw zapoznaj się z podstawowym sposobem użycia, który polega na wprowadzeniu słowa kluczowego prompt, działania action oraz rozmiaru obrazu size, aby uzyskać przetworzony wynik. Najpierw należy przekazać pole action o wartości generate, a następnie wprowadzić słowo kluczowe. Szczegóły przedstawiono poniżej:

Widać tutaj, że ustawiamy nagłówki żądania (Request Headers), w tym:

accept: format odpowiedzi, który chcemy otrzymać, tutaj ustawiony na application/json (format JSON).
authorization: klucz API do wywołania, który można wybrać z listy po rejestracji.

Dodatkowo ustawiamy ciało żądania (Request Body), które zawiera:

prompt: słowo kluczowe.
model: model generujący, domyślnie doubao-seedream-5.0-lite. Obsługiwane modele to doubao-seedream-5.0-lite (najnowszy), doubao-seedream-4.5, doubao-seedream-4.0, doubao-seedream-3.0-t2i, doubao-seededit-3.0-i2i.
image: dane wejściowe obrazu, obsługiwane są URL lub kodowanie Base64. Modele doubao-seedream-5.0-lite, doubao-seedream-4.5, doubao-seedream-4.0 obsługują pojedyncze lub wielokrotne obrazy, doubao-seededit-3.0-i2i tylko pojedynczy obraz, doubao-seedream-3.0-t2i nie obsługuje tego parametru.
size: określa rozmiar generowanego obrazu, obsługiwane są dwie metody, które nie mogą być mieszane. Metoda 1 | określenie rozdzielczości obrazu i opisanie proporcji szerokości do wysokości w prompt w języku naturalnym. Każdy model obsługuje inne ustawienia domyślne: doubao-seedream-5.0-lite obsługuje 2K/3K/4K; doubao-seedream-4.5 tylko 2K/4K; doubao-seedream-4.0 obsługuje 1K/2K/4K; doubao-seedream-3.0-t2i i doubao-seededit-3.0-i2i nie obsługują ustawień domyślnych, akceptują tylko metodę 2. Metoda 2 | określenie szerokości i wysokości obrazu w pikselach: domyślnie 2048x2048, zakres wartości całkowitej liczby pikseli i proporcji zależy od modelu (np. dla 5.0 / 4.5 minimalna liczba pikseli 3 686 400, dla 4.0 minimalna 921 600, dla 3.0-t2i / seededit-3.0-i2i zakres [512x512, 2048x2048]).
seed: ziarno losowości, służy do kontrolowania losowości generowanego obrazu. Zakres wartości [-1, 2147483647]. Obsługiwane tylko przez doubao-seedream-3.0-t2i.
sequential_image_generation: generowanie serii obrazów powiązanych tematycznie na podstawie wprowadzonej treści. Obsługiwane przez doubao-seedream-5.0-lite, doubao-seedream-4.5, doubao-seedream-4.0, domyślnie disabled.
stream: kontroluje, czy włączyć tryb strumieniowego przesyłania wyników. Obsługiwane przez doubao-seedream-5.0-lite, doubao-seedream-4.5, doubao-seedream-4.0, domyślnie false.
guidance_scale: stopień zgodności wyniku modelu z prompt, im większa wartość, tym większa zgodność. Zakres [1, 10]. Domyślnie 2.5 dla doubao-seedream-3.0-t2i, 5.5 dla doubao-seededit-3.0-i2i, nieobsługiwane przez inne modele.
response_format: format zwracanego obrazu. Domyślnie url, obsługuje również b64_json.
watermark: czy dodać znak wodny do wygenerowanego obrazu. Domyślnie true.
output_format: format pliku obrazu, obsługuje jpeg (domyślny) i png. Obsługiwane tylko przez doubao-seedream-5.0-lite.
tools: konfiguracja narzędzi wywoływanych przez model, obecnie obsługuje web_search (wyszukiwanie w sieci). Obsługiwane tylko przez doubao-seedream-5.0-lite.
callback_url: URL do wywołania zwrotnego (callback) z wynikiem.

Po wybraniu parametrów po prawej stronie wygenerowany zostanie odpowiedni kod, jak pokazano na obrazku:

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

{
  "success": true,
  "task_id": "25027ba3-0430-4a1b-91c8-d2297f19ba73",
  "trace_id": "8043a9e9-692f-43b0-82f7-5890f798be38",
  "data": [
    {
      "prompt": "a white siamese cat",
      "size": "2048x2048",
      "image_url": "https://platform.cdn.xhuoapi.ai/seedream/3c060029-69b1-406f-a957-fcd55ddc9386.jpg"
    }
  ]
}

Wynik zawiera następujące pola:

success: status zadania generowania obrazu.
task_id: identyfikator zadania generowania obrazu.
trace_id: identyfikator śledzenia zadania.
data: lista wyników generowania obrazu.
- image_url: link do wygenerowanego obrazu.
- prompt: słowo kluczowe.
- size: rozmiar wygenerowanego obrazu w pikselach.

Jak widać, otrzymaliśmy satysfakcjonujące informacje o obrazie. Wystarczy pobrać obraz SeeDream z linku image_url w polu data. Jeśli chcesz wygenerować kod integracji, możesz go bezpośrednio skopiować, na przykład kod CURL wygląda następująco:

curl -X POST 'https://api.xhuoapi.ai/v1/seedream/images' \
-H 'accept: application/json' \
-H 'authorization: Bearer ${token}' \
-H 'content-type: application/json' \
-d '{
  "action": "generate",
  "model": "doubao-seedream-4-0-250828",
  "prompt": "a white siamese cat"
}'

Zadanie edycji obrazu

Jeśli chcesz edytować istniejący obraz, musisz przekazać parametr image z linkiem do obrazu, który chcesz edytować.

model: model używany do edycji obrazu, doubao-seedream-5.0-lite, doubao-seedream-4.5, doubao-seedream-4.0 obsługują pojedyncze lub wielokrotne obrazy, doubao-seededit-3.0-i2i tylko pojedynczy obraz.
image: przesyłany obraz do edycji, jeden lub więcej.

Przykład wypełnienia formularza:

Odpowiedni kod:

import requests

url = "https://api.xhuoapi.ai/v1/flux/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)

Po uruchomieniu 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.xhuoapi.ai/seedream/3e88db7e-4771-4f6a-adbd-5ae4590c5d59.jpg"
        }
    ]
}

Jak widać, wygenerowany efekt to edycja oryginalnego obrazu, wynik jest podobny do powyższego.

Asynchroniczne wywołanie zwrotne (callback)

Ponieważ generowanie obrazów przez SeeDream Images Generation API zajmuje stosunkowo dużo czasu, około 1-2 minut, a długotrwałe oczekiwanie na odpowiedź API powoduje utrzymywanie połączenia HTTP i dodatkowe zużycie zasobów systemowych, API oferuje również wsparcie dla asynchronicznych wywołań zwrotnych. Cały proces wygląda następująco: klient wysyła żądanie z dodatkowym polem callback_url. Po wysłaniu żądania API natychmiast zwraca wynik zawierający pole task_id, które identyfikuje zadanie. Po zakończeniu zadania wynik generowania obrazu zostanie przesłany metodą POST w formacie JSON na wskazany przez klienta callback_url, zawierając również pole task_id, co umożliwia powiązanie wyników z zadaniem. Poniżej przykład działania. Po uruchomieniu natychmiast otrzymasz wynik, jak poniżej:

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

Zawartość odpowiedzi:

{
    "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.xhuoapi.ai/seedream/3e88db7e-4771-4f6a-adbd-5ae4590c5d59.jpg"
        }
    ]
}

Wynik zawiera pole task_id, pozostałe pola są podobne jak powyżej. Dzięki temu pole task_id można powiązać z konkretnym zadaniem.

Obsługa błędów

Podczas wywoływania API, w przypadku błędów, API zwraca odpowiedni kod błędu i komunikat. Przykładowe kody:

400 token_mismatched: Nieprawidłowe żądanie, prawdopodobnie brak lub nieprawidłowe parametry.
400 api_not_implemented: Nieprawidłowe żądanie, prawdopodobnie brak lub nieprawidłowe parametry.
401 invalid_token: Brak autoryzacji, nieprawidłowy lub brakujący token.
429 too_many_requests: Zbyt wiele żądań, przekroczono limit.
500 api_error: Błąd wewnętrzny serwera.

Przykład odpowiedzi błędu

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

Podsumowanie

W tym dokumencie poznaliście sposób korzystania z SeeDream Images Generation API, które umożliwia generowanie obrazów na podstawie wprowadzonych słów kluczowych. Mamy nadzieję, że dokument ten pomoże w integracji i efektywnym wykorzystaniu API. W razie pytań prosimy o kontakt z naszym zespołem wsparcia technicznego.

Documentation Index

​Proces rejestracji

​Podstawowe użycie

​Zadanie edycji obrazu

​Asynchroniczne wywołanie zwrotne (callback)

​Obsługa błędów

​Przykład odpowiedzi błędu

​Podsumowanie