SeeDream Images Generation API Integrationsinstruktioner

Detta dokument introducerar en integrationsinstruktion för SeeDream Images Generation API, som låter dig generera officiella SeeDream-bilder genom att mata in anpassade parametrar.

Ansökningsprocess

För att använda API:et måste du först ansöka om motsvarande tjänst på SeeDream Images Generation API. När du går in på sidan klickar du på knappen “Acquire”, som visas nedan:

Om du inte är inloggad eller registrerad kommer du automatiskt att omdirigeras till inloggningssidan för att registrera och logga in. Efter inloggning eller registrering återvänder du automatiskt till den aktuella sidan. Vid första ansökan får du en gratis kvot som gör att du kan använda API:et kostnadsfritt.

Grundläggande användning

Först bör du förstå den grundläggande användningen, vilket innebär att du matar in prompten prompt, genereringsåtgärden action och bildstorleken size för att få ett bearbetat resultat. Du måste först skicka ett action-fält med värdet generate, och sedan mata in prompten. Det ser ut så här:

Här ser vi att vi ställer in Request Headers, inklusive:

accept: vilket format svaret ska ha, här application/json för JSON-format.
authorization: API-nyckeln för att anropa API:et, som du kan välja från en dropdown efter ansökan.

Dessutom ställer vi in Request Body, inklusive:

prompt: prompten.
model: genereringsmodellen, standard är doubao-seedream-5.0-lite. Stöder doubao-seedream-5.0-lite (senaste), doubao-seedream-4.5, doubao-seedream-4.0, doubao-seedream-3.0-t2i, doubao-seededit-3.0-i2i.
image: bildinformation som input, stöder URL eller Base64-kodning. doubao-seedream-5.0-lite, doubao-seedream-4.5, doubao-seedream-4.0 stöder en eller flera bilder, doubao-seededit-3.0-i2i stöder endast en bild, doubao-seedream-3.0-t2i stöder inte denna parameter.
size: specificerar bildens storlek, stöder två metoder som inte kan kombineras. Metod 1 | specificerar upplösning och beskriver bildens proportioner i prompten med naturligt språk. Olika modeller stöder olika förinställningar: doubao-seedream-5.0-lite stöder 2K/3K/4K; doubao-seedream-4.5 stöder endast 2K/4K; doubao-seedream-4.0 stöder 1K/2K/4K; doubao-seedream-3.0-t2i och doubao-seededit-3.0-i2i stöder inte förinställningar, endast metod 2. Metod 2 | specificerar bildens bredd och höjd i pixlar: standard är 2048x2048, total pixelmängd och proportioner varierar beroende på modell (t.ex. 5.0 / 4.5 har nedre gräns 3 686 400 pixlar, 4.0 har nedre gräns 921 600, 3.0-t2i / seededit-3.0-i2i har intervallet [512x512, 2048x2048]).
seed: slumpmässigt frö för att styra modellens slumpmässighet. Värdeintervall [-1, 2147483647]. Endast doubao-seedream-3.0-t2i stöder denna parameter.
sequential_image_generation: bildserie: genererar en serie relaterade bilder baserat på din input. Stöds av doubao-seedream-5.0-lite, doubao-seedream-4.5, doubao-seedream-4.0, standard är disabled.
stream: styr om strömningsläge ska aktiveras. Stöds av doubao-seedream-5.0-lite, doubao-seedream-4.5, doubao-seedream-4.0, standard är false.
guidance_scale: hur väl modellens output överensstämmer med prompten, högre värde ger starkare korrelation. Värdeintervall [1, 10]. Standardvärde för doubao-seedream-3.0-t2i är 2.5, för doubao-seededit-3.0-i2i är 5.5, stöds inte av andra modeller.
response_format: specificerar formatet för den genererade bilden. Standard är url, stöder även b64_json.
watermark: om en vattenstämpel ska läggas till i bilden. Standard är true.
output_format: specificerar filformat för den genererade bilden, stöder jpeg (standard) och png. Endast doubao-seedream-5.0-lite stöder detta.
tools: konfigurerar verktyg som modellen ska använda, för närvarande stöds web_search (internet-sökning). Endast doubao-seedream-5.0-lite stöder detta.
callback_url: URL för callback med resultat.

När du valt detta genereras motsvarande kod till höger, som visas nedan:

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

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

Svarresultatet innehåller flera fält, beskrivna nedan:

success: status för bildgenereringsuppgiften.
task_id: ID för bildgenereringsuppgiften.
trace_id: spårnings-ID för uppgiften.
data: lista med resultat för bildgenereringsuppgiften.
- image_url: URL till den genererade bilden.
- prompt: prompten.
- size: bildens pixeldimensioner.

Vi har fått en tillfredsställande bildinformation och kan enkelt hämta den genererade SeeDream-bilden via länken i data. Om du vill generera motsvarande integrationskod kan du kopiera den direkt, till exempel CURL-koden nedan:

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

Redigera bilduppgift

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

model: modellen som används för redigeringsuppgiften. doubao-seedream-5.0-lite, doubao-seedream-4.5, doubao-seedream-4.0 stöder en eller flera bilder, doubao-seededit-3.0-i2i stöder endast en bild.
image: bilden eller bilderna som ska redigeras.

Exempel på ifyllnad:

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

När du kör detta får du omedelbart ett resultat som nedan:

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

Resultatet visar en redigerad version av originalbilden, liknande tidigare exempel.

Asynkron callback

Eftersom SeeDream Images Generation API kan ta 1-2 minuter att generera bilder, och långa HTTP-förfrågningar kan orsaka extra systemresursförbrukning, erbjuder API:et stöd för asynkron callback. Processen är: klienten skickar en förfrågan med ett extra fält callback_url. API:et svarar omedelbart med ett resultat som innehåller task_id för uppgiften. När uppgiften är klar skickas resultatet som en POST med JSON till den angivna callback_url, inklusive task_id så att uppgiften kan kopplas ihop. Nedan ett exempel på hur det fungerar. När du kör får du omedelbart detta svar:

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

Innehållet är:

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

Resultatet innehåller task_id och övriga fält som tidigare, vilket möjliggör koppling av uppgiften via ID.

Felhantering

Vid anrop av API:et, om fel uppstår, returnerar API:et motsvarande felkod och meddelande. Exempel:

400 token_mismatched: Bad request, troligen saknade eller ogiltiga parametrar.
400 api_not_implemented: Bad request, troligen saknade eller ogiltiga parametrar.
401 invalid_token: Unauthorized, ogiltig eller saknad auktoriseringstoken.
429 too_many_requests: För många förfrågningar, du har överskridit gränsen.
500 api_error: Intern serverfel, något gick fel på servern.

Exempel på felrespons

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

Slutsats

Med detta dokument har du lärt dig hur du använder SeeDream Images Generation API för att generera bilder genom att mata in promptar. Vi hoppas att denna dokumentation hjälper dig att integrera och använda API:et bättre. Vid frågor, kontakta gärna vårt tekniska supportteam.

Documentation Index

​Ansökningsprocess

​Grundläggande användning

​Redigera bilduppgift

​Asynkron callback

​Felhantering

​Exempel på felrespons

​Slutsats