SeeDream Images Generation API 연동 안내

​

신청 절차

📘 전체 문서: SeeDream Images Generation API →

​

기본 사용

• accept: 어떤 형식의 응답 결과를 받을지 지정하며, 여기서는 JSON 형식인 application/json으로 입력합니다.
• authorization: API 호출 키이며, 신청 후 직접 드롭다운에서 선택할 수 있습니다.

• prompt: 프롬프트.
• model: 생성 모델이며, 기본값은 doubao-seedream-5-0-lite-260128(SeeDream 5.0 Lite, 최신)입니다. doubao-seedream-5-0-pro-260628, doubao-seedream-5-0-lite-260128, doubao-seedream-4-5-251128, doubao-seedream-4-0-250828을 지원합니다. 이 중 doubao-seedream-5-0-pro-260628(SeeDream 5.0 Pro)는 플래그십 단일 이미지 모델로, 단일 이미지만 생성하며 이미지 그룹(sequential_image_generation), 스트리밍(stream) 및 웹 검색(tools)을 지원하지 않습니다. model에는 전체 모델 문자열(예: doubao-seedream-5-0-lite-260128)을 반드시 전달해야 하며, doubao-seedream-5.0-lite와 같은 축약형을 전달하면 400이 반환됩니다.
• image: 입력 이미지 정보로, URL 또는 Base64 인코딩을 지원합니다. doubao-seedream-5-0-pro-260628은 단일 이미지 또는 여러 이미지 입력(최대 10장)을 지원하며, doubao-seedream-5-0-lite-260128, doubao-seedream-4-5-251128, doubao-seedream-4-0-250828은 단일 이미지 또는 여러 이미지 입력을 지원합니다.
• size: 생성 이미지의 크기 정보를 지정하며, 다음 두 가지 방식을 지원하고 혼용할 수 없습니다. 방식 1 | 생성 이미지의 해상도를 지정하고, prompt에서 자연어로 이미지의 가로세로 비율을 설명합니다. 각 모델이 지원하는 프리셋은 서로 다릅니다: doubao-seedream-5-0-pro-260628은 1K/1.5K/2K를 지원하며, doubao-seedream-5-0-lite-260128은 2K/3K/4K를 지원하고, doubao-seedream-4-5-251128은 2K/4K만 지원하며, doubao-seedream-4-0-250828은 1K/2K/4K를 지원합니다. 방식 2 | 생성 이미지의 가로세로 픽셀값을 지정합니다: 기본값은 2048x2048이며, 총 픽셀 수와 가로세로 비율의 범위는 모델마다 다릅니다(예: 5.0 Pro의 총 픽셀 범위는 [921600, 4624220]이고, 5.0 Lite / 4.5의 총 픽셀 하한은 3,686,400이며, 4.0의 하한은 921,600입니다).
• sequential_image_generation: 이미지 그룹: 입력한 내용을 기반으로 내용이 서로 연관된 이미지 그룹을 생성합니다. doubao-seedream-5-0-lite-260128, doubao-seedream-4-5-251128, doubao-seedream-4-0-250828은 이 파라미터를 지원하며, 기본값은 disabled입니다.
• stream: 스트리밍 출력 모드를 활성화할지 제어합니다. doubao-seedream-5-0-lite-260128, doubao-seedream-4-5-251128, doubao-seedream-4-0-250828은 이 파라미터를 지원하며, 기본값은 false입니다.
• response_format: 생성 이미지의 반환 형식을 지정합니다. 기본값은 url이며, b64_json도 지원합니다.
• watermark: 생성된 이미지에 워터마크를 추가할지 여부입니다. 기본값은 true입니다.
• output_format: 생성 이미지의 파일 형식을 지정하며, jpeg(기본값) 및 png를 지원합니다. doubao-seedream-5-0-pro-260628 및 doubao-seedream-5-0-lite-260128만 지원합니다.
• tools: 모델이 호출할 도구를 구성하며, 현재 web_search(웹 검색)를 지원합니다. Seedream 5.0 Lite만 지원합니다.
• optimize_prompt_options: 프롬프트 최적화 구성입니다. 5.0 Pro는 standard/fast를 지원하며, 5.0 Lite와 4.5는 standard만 지원하고, 4.0은 standard/fast를 지원합니다.
• background: 5.0 Pro 단일 이미지 편집만 지원합니다. transparent는 투명 채널이 있는 PNG 한 장의 입력을 요구하며, output_format은 반드시 png여야 합니다. opaque는 일반 불투명 배경입니다.
• layer_decomposition: 5.0 Pro만 지원합니다. true로 설정하면 PNG/JPEG 한 장을 반드시 입력해야 하며, prompt를 전달하지 않아도 자동으로 분할하거나 자연어/<bbox>로 요소를 지정할 수 있습니다. size는 auto/1K/1.5K/2K를 지원합니다. 이 모드는 이미지 그룹, 스트리밍, 웹 검색 또는 background와 함께 사용할 수 없습니다.
• callback_url: 결과 콜백이 필요한 URL입니다.
• async: 비동기 모드로 처리할지 여부입니다. true로 설정하면 인터페이스는 즉시 task_id를 반환하며, callback_url을 제공할 필요 없이 이후 /seedream/tasks를 통해 폴링하여 결과를 가져옵니다.

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

• success, 현재 비디오 생성 작업의 상태입니다.
• task_id, 현재 비디오 생성 작업 ID입니다.
• trace_id, 현재 비디오 생성 추적 ID입니다.
• data, 현재 이미지 생성 작업의 결과 목록입니다.
  • image_url, 현재 이미지 생성 작업의 링크입니다.
  • prompt, 프롬프트입니다.
  • size: 생성 이미지의 픽셀입니다.

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

​

이미지 편집 작업

• model: 이번 이미지 편집 작업에 사용되는 모델이며, doubao-seedream-5-0-pro-260628, doubao-seedream-5-0-lite-260128, doubao-seedream-4-5-251128, doubao-seedream-4-0-250828은 모두 이미지 입력을 지원합니다.
• image: 편집할 이미지를 업로드하며, 한 장 또는 여러 장일 수 있습니다.

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)

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

​

레이어 분해（Seedream 5.0 Pro）

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

​

스트리밍 출력

​

비동기 콜백

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

{
    "success": true,
    "task_id": "c9aaffa2-b8ac-40ff-8468-43e77cb9ddde",
    "trace_id": "131a40c3-2eaf-44c9-af28-c9b408577286",
    "data": [
        {
            "prompt": "모델의 포즈와 액체 의상의 흐르는 형태를 변경하지 마세요. 의상 소재를 은색 금속에서 완전히 투명한 물(또는 유리)로 변경하세요. 액체의 흐름을 통해 모델 피부의 디테일이 보입니다. 빛과 그림자 효과는 반사에서 굴절로 전환됩니다.",
            "size": "2048x2048",
            "image_url": "https://platform.cdn.acedata.cloud/seedream/3e88db7e-4771-4f6a-adbd-5ae4590c5d59.jpg"
        }
    ]
}

​

오류 처리

• 400 token_mismatched: 잘못된 요청으로, 매개변수가 누락되었거나 유효하지 않기 때문일 수 있습니다.
• 400 api_not_implemented: 잘못된 요청으로, 매개변수가 누락되었거나 유효하지 않기 때문일 수 있습니다.
• 401 invalid_token: 권한 없음, 인증 토큰이 유효하지 않거나 누락되었습니다.
• 429 too_many_requests: 요청이 너무 많습니다. 속도 제한을 초과했습니다.
• 500 api_error: 내부 서버 오류로, 서버에서 문제가 발생했습니다.

​

오류 응답 예시

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

​

결론