Instruktioner för integration av SeeDream Images Generation API

Den här artikeln introducerar en typ av instruktion för integration av SeeDream Images Generation API, som kan generera officiella bilder från SeeDream genom att ange anpassade parametrar.

Ansökningsprocess

För att använda SeeDream Images Generation API ska du först hämta din API Token från Ace Data Cloud-konsolen och spara den för senare användning.

Om du ännu inte har loggat in eller registrerat dig omdirigeras du automatiskt till inloggningssidan för att registrera dig och logga in, och återvänder automatiskt till den aktuella sidan efter slutförandet. En API Token kan anropa alla plattformens tjänster, utan att behöva ansöka separat för varje tjänst. Vid första ansökan får du gratis kredit som kan användas för en kostnadsfri testupplevelse; när krediten inte räcker till kan du fylla på det gemensamma saldot i konsolen.

📘 Fullständig dokumentation: SeeDream Images Generation API →

Grundläggande användning

Låt oss först förstå den grundläggande användningen: genom att ange prompten prompt, genereringsåtgärden action och bildstorleken size kan du få det bearbetade resultatet. Först behöver du enkelt skicka ett action-fält, vars värde är generate, och sedan behöver vi även ange prompten. Det specifika innehållet är följande:

Här kan vi se att vi har angett Request Headers, inklusive:

accept: Vilket format på svarsresultatet du vill ta emot. Här anges application/json, alltså JSON-format.
authorization: Nyckeln för att anropa API:t, som kan väljas direkt i en rullgardinsmeny efter ansökan.

Dessutom har Request Body angetts, inklusive:

prompt: Prompt.
model: Genereringsmodell, standard är doubao-seedream-5-0-lite-260128 (SeeDream 5.0 Lite, senaste). Stöder doubao-seedream-5-0-pro-260628, doubao-seedream-5-0-lite-260128, doubao-seedream-4-5-251128, doubao-seedream-4-0-250828. Bland dessa är doubao-seedream-5-0-pro-260628 (SeeDream 5.0 Pro) en flaggskeppsmodell för enstaka bilder, som endast genererar enstaka bilder och inte stöder bildgrupper (sequential_image_generation), streaming (stream) eller webbsökning (tools). model måste skickas in som den fullständiga modellsträngen (t.ex. doubao-seedream-5-0-lite-260128); förkortningar som doubao-seedream-5.0-lite returnerar 400.
image: Information om den inmatade bilden, stöder URL eller Base64-kodning. doubao-seedream-5-0-pro-260628 stöder inmatning av en eller flera bilder (högst 10), och doubao-seedream-5-0-lite-260128, doubao-seedream-4-5-251128, doubao-seedream-4-0-250828 stöder inmatning av en eller flera bilder.
size: Anger storleksinformationen för den genererade bilden och stöder följande två metoder, som inte kan blandas. Metod 1 | Ange upplösningen för den genererade bilden och beskriv bildens bildförhållande med naturligt språk i prompten. De förinställningar som stöds skiljer sig mellan modellerna: doubao-seedream-5-0-pro-260628 stöder 1K/1.5K/2K; doubao-seedream-5-0-lite-260128 stöder 2K/3K/4K; doubao-seedream-4-5-251128 stöder endast 2K/4K; doubao-seedream-4-0-250828 stöder 1K/2K/4K. Metod 2 | Ange bredd- och höjdpixelvärden för den genererade bilden: standard är 2048x2048, och intervallen för totalt antal pixlar och bildförhållande varierar beroende på modell (exempelvis har 5.0 Pro ett intervall för totalt antal pixlar på [921600, 4624220], 5.0 Lite / 4.5 har en nedre gräns för totalt antal pixlar på 3,686,400 och 4.0 har en nedre gräns på 921,600).
sequential_image_generation: Bildgrupp: en grupp bilder med innehåll som är relaterat till varandra, genererade utifrån innehållet du anger. doubao-seedream-5-0-lite-260128, doubao-seedream-4-5-251128, doubao-seedream-4-0-250828 stöder denna parameter, standard är disabled.
stream: Styr om streamingutmatningsläge ska aktiveras. doubao-seedream-5-0-lite-260128, doubao-seedream-4-5-251128, doubao-seedream-4-0-250828 stöder denna parameter, standard är false.
response_format: Anger returformatet för den genererade bilden. Standard är url, och b64_json stöds också.
watermark: Om en vattenstämpel ska läggas till i den genererade bilden. Standard är true.
output_format: Anger filformatet för den genererade bilden och stöder jpeg (standard) och png. Stöds endast av doubao-seedream-5-0-pro-260628 och doubao-seedream-5-0-lite-260128.
tools: Konfigurerar verktyg som modellen ska anropa, stöder för närvarande web_search (webbsökning). Stöds endast av Seedream 5.0 Lite.
optimize_prompt_options: Konfiguration för promptoptimering. 5.0 Pro stöder standard/fast; 5.0 Lite och 4.5 stöder endast standard; 4.0 stöder standard/fast.
background: Stöds endast för redigering av enstaka bilder i 5.0 Pro. transparent kräver att en PNG med transparent kanal matas in, och output_format måste vara png; opaque är en vanlig ogenomskinlig bakgrund.
layer_decomposition: Stöds endast av 5.0 Pro. När den ställs in på true måste en PNG/JPEG matas in; du kan utelämna prompt för automatisk uppdelning eller ange element med naturligt språk/<bbox>; size stöder auto/1K/1.5K/2K. Detta läge kan inte användas tillsammans med bildgrupper, streaming, webbsökning eller background.
callback_url: URL:en som behöver återkalla resultatet.
async: Om bearbetning ska ske i asynkront läge. När den ställs in på true returnerar gränssnittet omedelbart task_id, utan att callback_url behöver anges, och resultatet hämtas sedan genom att polla /seedream/tasks.

Efter valet kan du se att motsvarande kod också genereras på höger sida, som visas i bilden:

Klicka på knappen ”Try” för att testa. Som visas i bilden ovan får vi då följande resultat:

{
  "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"
    }
  ]
}

Det returnerade resultatet innehåller totalt flera fält, som beskrivs nedan:

success, statusen för videogenereringsuppgiften vid detta tillfälle.
task_id, ID:t för videogenereringsuppgiften vid detta tillfälle.
trace_id, spårnings-ID:t för videogenereringen vid detta tillfälle.
data, resultatlistan för bildgenereringsuppgiften vid detta tillfälle.
- image_url, länken till bildgenereringsuppgiften vid detta tillfälle.
- prompt, prompten.
- size: pixlarna för den genererade bilden

Vi kan se att vi har fått tillfredsställande bildinformation, och vi behöver bara hämta den genererade SeeDream-bilden enligt bildlänkadressen i resultatets data. Om du dessutom vill generera motsvarande integrationskod kan du kopiera den direkt, till exempel är CURL-koden följande:

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

Redigera bilduppgift

Om du vill redigera en bild måste parametern image först innehålla länken till bilden som ska redigeras.

model: modellen som används för denna bildredigeringsuppgift, doubao-seedream-5-0-pro-260628, doubao-seedream-5-0-lite-260128, doubao-seedream-4-5-251128, doubao-seedream-4-0-250828 stöder alla bildinmatning.
image: ladda upp bilden eller bilderna som behöver redigeras, en eller flera

Ett ifyllnadsexempel är följande:

Motsvarande 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)

Klicka på kör, så kan du se att du omedelbart får ett resultat, enligt följande:

{
  "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"
    }
  ]
}

Du kan se att den genererade effekten är en redigering av originalbilden, och resultatet liknar det ovan.

Lageruppdelning (Seedream 5.0 Pro)

Lageruppdelning delar upp en inmatad bild i 1 bakgrundsbild och upp till 16 oberoende redigerbara transparenta PNG-lager. Följande begäran låter modellen automatiskt identifiera huvudelementen; om du behöver ange element kan du lägga till prompt, och du kan även använda normaliserade <bbox>-koordinater i prompten.

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

Det returnerade data är ordnat från botten till toppen enligt z_index. Bakgrundsbildens z_index är 0; lagren innehåller även name, description och bounding_box.absolute/normalized. Vid återuppbyggnad med absoluta koordinater ska lagren skalas till [right-left, bottom-top], placeras vid [left, top] och sedan staplas i stigande ordning enligt z_index. Om genereringen av något lager misslyckas misslyckas hela uppdelningen.

Strömmande utdata

När Lite/4.x ställs in med stream: true använder begärandehuvudet accept: application/x-ndjson. Gränssnittet returnerar rad för rad image_generation.partial_succeeded eller image_generation.partial_failed, och returnerar till sist den unika händelsen image_generation.completed samt slutlig usage; endast slutförandehändelsen utlöser en debitering. Strömmande läge kan inte användas tillsammans med async eller callback_url.

Asynkron återuppringning

Eftersom SeeDream Images Generation API har en relativt lång genereringstid, cirka 1–2 minuter, kommer HTTP-begäran att fortsätta hålla anslutningen om API:t inte svarar under en längre tid, vilket leder till ytterligare förbrukning av systemresurser, så detta API erbjuder också stöd för asynkrona återuppringningar. Det övergripande flödet är: när klienten initierar en begäran anges dessutom ett fält callback_url; efter att klienten har initierat API-begäran returnerar API:t omedelbart ett resultat som innehåller fältet task_id, vilket representerar ID:t för den aktuella uppgiften. När uppgiften har slutförts skickas resultatet av den genererade bilden i form av POST JSON till den callback_url som klienten har angett, och detta inkluderar också fältet task_id, så att uppgiftsresultatet kan kopplas samman via ID:t. Om du inte har en offentlig adress tillgänglig för återuppringning kan du också välja att inte ange callback_url, utan i stället sätta fältet async till true i begäran. Gränssnittet returnerar då också omedelbart task_id, men skickar inte resultatet, och du måste använda detta task_id för att anropa gränssnittet /seedream/tasks och regelbundet kontrollera uppgiftsstatusen för att hämta slutresultatet. Nedan använder vi ett exempel för att förstå hur man specifikt gör detta. Klicka på kör, så kan du se att du omedelbart får ett resultat, enligt följande:

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

Innehållet är följande:

{
  "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"
    }
  ]
}

Det kan ses att resultatet innehåller ett fält task_id, och de andra fälten liknar de ovan. Genom detta fält kan uppgifter kopplas samman.

Felhantering

Vid anrop av API:t, om ett fel uppstår, returnerar API:t motsvarande felkod och information. Till exempel:

400 token_mismatched：Felaktig begäran, möjligen på grund av saknade eller ogiltiga parametrar.
400 api_not_implemented：Felaktig begäran, möjligen på grund av saknade eller ogiltiga parametrar.
401 invalid_token：Obehörig, ogiltig eller saknad auktoriseringstoken.
429 too_many_requests：För många begäranden, du har överskridit gränsen för begäranden.
500 api_error：Internt serverfel, något gick fel på servern.

Exempel på felsvar

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

Slutsats

Genom detta dokument har du lärt dig hur du använder SeeDream Images Generation API för att generera bilder genom att ange promptord. Vi hoppas att detta dokument kan hjälpa dig att bättre integrera och använda detta API. Om du har några frågor, vänligen kontakta vårt tekniska supportteam när som helst.

Getting Started

AI Samtal

AI Bild

AI Video

AI Ljud

Web & Data

CAPTCHA

Identitet

Coding

Fler guider

Instruktioner för integration av SeeDream Images Generation API

Ansökningsprocess

Grundläggande användning

Redigera bilduppgift

Lageruppdelning (Seedream 5.0 Pro)

Strömmande utdata

Asynkron återuppringning

Felhantering

Exempel på felsvar

Slutsats

​Ansökningsprocess

​Grundläggande användning

​Redigera bilduppgift

​Lageruppdelning (Seedream 5.0 Pro)

​Strömmande utdata

​Asynkron återuppringning

​Felhantering

​Exempel på felsvar

​Slutsats

Ansökningsprocess

Grundläggande användning

Redigera bilduppgift

Lageruppdelning (Seedream 5.0 Pro)

Strömmande utdata

Asynkron återuppringning

Felhantering

Exempel på felsvar

Slutsats