신청 절차
SeeDream 이미지 생성 API를 사용하려면 먼저 Ace Data Cloud 콘솔에서 API 토큰을 받아야 합니다. 이를 보관해 두세요.
로그인 또는 등록이 되어 있지 않으면 자동으로 로그인 페이지로 이동하여 등록 및 로그인을 요청합니다. 완료 후 현재 페이지로 자동으로 돌아옵니다.
하나의 API 토큰으로 플랫폼의 모든 서비스를 호출할 수 있으며, 각 서비스마다 별도로 신청할 필요가 없습니다. 처음 신청 시 무료 사용량이 제공되어 무료로 체험할 수 있습니다; 사용량이 부족할 경우 콘솔에서 일반 잔액을 충전할 수 있습니다.
📘 전체 문서: SeeDream 이미지 생성 API →
기본 사용법
먼저 기본 사용 방법을 이해해야 합니다. 즉,prompt(프롬프트), action(행동), size(이미지 크기)를 입력하면 처리된 결과를 얻을 수 있습니다. 먼저 간단히 action 필드를 전달해야 하며, 그 값은 generate입니다. 그런 다음 프롬프트를 입력해야 하며, 구체적인 내용은 다음과 같습니다:
accept: 어떤 형식의 응답 결과를 받고 싶은지, 여기서는application/json으로 작성하여 JSON 형식을 요청합니다.authorization: API 호출을 위한 키로, 신청 후 드롭다운에서 직접 선택할 수 있습니다.
prompt: 프롬프트.model: 생성 모델, 기본값은doubao-seedream-5-0-260128(SeeDream 5.0 Lite, 최신)입니다. 지원되는 모델은doubao-seedream-5-0-pro-260628,doubao-seedream-5-0-260128(공식 별명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-260128)을 전달해야 하며,doubao-seedream-5.0-lite와 같은 약어를 전달하면 400 오류가 발생합니다.image: 입력 이미지 정보로, URL 또는 Base64 인코딩을 지원합니다.doubao-seedream-5-0-pro-260628은 단일 이미지 또는 다중 이미지 입력(다중 이미지 2-10장, 2장부터 장당 요금 부과)을 지원하며,doubao-seedream-5-0-260128,doubao-seedream-4-5-251128,doubao-seedream-4-0-250828은 단일 이미지 또는 다중 이미지 입력을 지원합니다.size: 생성할 이미지의 크기 정보를 지정하며, 다음 두 가지 방법을 지원합니다. 혼용할 수 없습니다. 방법 1 | 생성할 이미지의 해상도를 지정하고 프롬프트에서 자연어로 이미지의 가로 세로 비율을 설명합니다. 각 모델이 지원하는 프리셋이 다릅니다:doubao-seedream-5-0-pro-260628은1K/1.5K/2K를 지원하며,doubao-seedream-5-0-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-260128,doubao-seedream-4-5-251128,doubao-seedream-4-0-250828은 이 매개변수를 지원하며, 기본값은disabled입니다.stream: 스트리밍 출력 모드를 활성화할지 여부를 제어합니다.doubao-seedream-5-0-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-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, 현재 비디오 생성 작업의 상태.task_id, 현재 비디오 생성 작업 ID.trace_id, 현재 비디오 생성 추적 ID.data, 현재 이미지 생성 작업의 결과 목록.image_url, 현재 이미지 생성 작업의 링크.prompt, 프롬프트.size: 생성된 이미지의 픽셀.
data에서 이미지 링크 주소를 통해 생성된 SeeDream 이미지를 가져오면 됩니다.
또한, 해당하는 코드 생성을 원하시면 직접 복사하여 생성할 수 있습니다. 예를 들어 CURL의 코드는 다음과 같습니다:
이미지 편집 작업
특정 이미지를 편집하고자 할 경우, 먼저 매개변수image에 편집할 이미지 링크를 전달해야 합니다.
- model: 이번 이미지 편집 작업에 사용되는 모델,
doubao-seedream-5-0-pro-260628,doubao-seedream-5-0-260128,doubao-seedream-4-5-251128,doubao-seedream-4-0-250828모두 이미지 입력을 지원합니다. - image: 편집할 이미지를 업로드, 한 장 또는 여러 장.
레이어 분해 (Seedream 5.0 Pro)
레이어 분해는 입력 이미지를 1개의 바닥 이미지와 최대 16개의 독립적으로 편집 가능한 투명 PNG 레이어로 분해합니다. 다음 요청은 모델이 주요 요소를 자동으로 인식하게 합니다; 요소를 지정하려면prompt를 추가하거나 프롬프트에서 정규화된 <bbox> 좌표를 사용할 수 있습니다.
data는 z_index에 따라 바닥에서 위로 정렬됩니다. 바닥 이미지의 z_index는 0입니다; 레이어는 또한 name, description 및 bounding_box.absolute/normalized를 포함합니다. 절대 좌표로 재구성할 때, 레이어를 [right-left, bottom-top]로 스케일링하고 [left, top]에 배치한 후 z_index 오름차순으로 쌓습니다. 어떤 레이어의 생성이 실패하면 전체 분해가 실패합니다.
스트리밍 출력
Lite/4.x에서stream: true로 설정할 경우, 요청 헤더는 accept: application/x-ndjson을 사용합니다. 인터페이스는 image_generation.partial_succeeded 또는 image_generation.partial_failed를 줄 단위로 반환하며, 마지막으로 고유한 image_generation.completed 이벤트와 최종 usage를 반환합니다; 완료 이벤트가 한 번 발생할 때만 요금이 청구됩니다. 스트리밍 모드는 async 또는 callback_url과 함께 사용할 수 없습니다.
비동기 콜백
SeeDream 이미지 생성 API의 생성 시간은 상대적으로 길어 약 1-2분이 소요되며, API가 오랜 시간 응답하지 않으면 HTTP 요청이 연결을 유지하여 추가 시스템 리소스 소모를 초래할 수 있으므로, 이 API는 비동기 콜백 지원도 제공합니다. 전체 프로세스는: 클라이언트가 요청을 시작할 때 추가로callback_url 필드를 지정하고, 클라이언트가 API 요청을 시작한 후 API는 즉시 결과를 반환하며, 현재 작업 ID를 나타내는 task_id 필드 정보를 포함합니다. 작업이 완료되면 생성된 이미지 결과가 POST JSON 형식으로 클라이언트가 지정한 callback_url로 전송되며, 여기에도 task_id 필드가 포함되어 있어 작업 결과를 ID로 연결할 수 있습니다.
콜백을 위한 공용 주소가 없다면 callback_url을 지정하지 않고 요청 중에 async 필드를 true로 설정할 수 있습니다. 이 경우 인터페이스는 즉시 task_id를 반환하지만 결과를 푸시하지 않으며, 해당 task_id를 가지고 /seedream/tasks 인터페이스를 호출하여 작업 상태를 폴링하여 최종 결과를 얻어야 합니다.
아래 예제를 통해 구체적으로 어떻게 작업하는지 알아보겠습니다.
실행하면 즉시 결과를 얻을 수 있으며, 결과는 다음과 같습니다:
task_id 필드가 있으며, 다른 필드는 위와 유사하여 이 필드를 통해 작업을 연관시킬 수 있습니다.
오류 처리
API를 호출할 때 오류가 발생하면, API는 해당 오류 코드와 정보를 반환합니다. 예를 들어:400 token_mismatched：잘못된 요청, 누락되거나 잘못된 매개변수 때문일 수 있습니다.400 api_not_implemented：잘못된 요청, 누락되거나 잘못된 매개변수 때문일 수 있습니다.401 invalid_token：권한 없음, 잘못되었거나 누락된 인증 토큰입니다.429 too_many_requests：요청이 너무 많습니다. 비율 제한을 초과했습니다.500 api_error：내부 서버 오류, 서버에서 문제가 발생했습니다.