Seedream
Endpoint: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/si-image/generation인증: Tokenhub API Key / Bearer
Seedream Image는 텍스트 생성과 참조 이미지 편집을 지원합니다. 5.0 Pro는 레이어 분해, 5.0 Lite는 그룹 이미지 생성을 지원합니다.
기본 정보
| 항목 | 값 |
|---|---|
| 호출 경로 | Tokenhub API |
| 가드레일 해제 지원 | 미지원 |
버전별 지원 규격
| 버전 | 해상도 | 비율 | 참조 이미지 |
|---|---|---|---|
seedream-image-v5.0-pro | 1K / 1.5K / 2K | 프롬프트 / size 지정 | 최대 10장 |
seedream-image-v5.0-lite | 2K / 3K / 4K | 프롬프트 / size 지정 | 최대 14장 |
이미지 생성
API 설명
Seedream 이미지 생성(참조 이미지 기반 이미지 생성) API는 참조 이미지 기반 이미지 생성, 텍스트-이미지 생성, 이미지 편집을 지원합니다. 참조 이미지와 텍스트 프롬프트를 사용해 이미지를 생성하며, 이미지가 제공되지 않으면 텍스트-이미지 생성을 수행합니다.
API: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/si-image/generation
요청 파라미터
| 파라미터 | 필수 | 타입 | 설명 |
|---|---|---|---|
| model | 필수 | string | 모델 ID. 값: seedream-image-v5.0-pro, seedream-image-v5.0-lite |
| prompt | 필수 | string | 최대 길이가 600자인 텍스트 프롬프트입니다. images가 전달되지 않으면 이 텍스트를 기반으로 텍스트 기반 이미지 생성을 수행합니다. 프롬프트 권장 길이: 중국어 프롬프트는 300자 이하, 영어 프롬프트는 600단어 이하를 권장합니다. 지나치게 길면 정보가 분산되어 모델이 세부 사항을 놓치고 핵심에만 집중할 수 있으며, 생성된 이미지에서 일부 요소가 누락될 수 있습니다. |
| images | 선택 | array[string] | 참조 이미지: seedream-image-v5.0-pro는 최대 10개, seedream-image-v5.0-lite는 최대 14개의 이미지를 지원합니다.입력 이미지 정보는 URL 또는 Base64 인코딩을 지원합니다. 이미지 URL: 이미지 URL에 접근할 수 있어야 합니다. Base64 인코딩: data:image/<image_format>;base64,<Base64_encoded_string> 형식을 사용합니다. <image_format>은 소문자여야 합니다. 예: data:image/png;base64,<base64_image>. |
| layer_decomposition | 선택 | boolean | 레이어 분해 기능 활성화 여부를 제어하는 스위치입니다. 레이어 분해는 단일 이미지의 참조 대상, 배경, 텍스트 및 기타 콘텐츠를 기본 이미지 1개와 독립적으로 편집 가능한 최대 16개의 레이어로 자동 분해합니다. 각 레이어는 알파 채널이 있는 PNG 이미지입니다. 지원 모델: seedream-image-v5.0-pro |
| size | 선택 | string | 이미지 크기입니다.seedream-image-v5.0-pro(이미지 생성 시나리오)는 다음 두 가지 방식을 지원하며 함께 사용할 수 없습니다. 방식 1(권장): 해상도 등급을 지정하고 프롬프트에서 이미지의 종횡비, 형태 또는 용도를 자연어로 설명합니다.그러면 모델이 생성 이미지의 크기를 결정합니다. 기본값: 2K 유효한 값: 1K, 1.5K, 2K 방식 2: 픽셀 단위의 너비와 높이(width x height)를 지정합니다.총 픽셀 값 범위: [1280x720 ( 921600), 2048x2048x1.1025 (4624220)] 종횡비 값 범위: [1/16, 16]seedream-image-v5.0-pro(레이어 분해 시나리오)는 해상도 등급 지정 방식만 지원합니다.출력 이미지의 해상도 규칙은 다음과 같습니다. 기본 이미지: 출력 기본 이미지의 해상도는 size로 지정한 해상도와 일치합니다. 출력 기본 이미지의 종횡비는 분할할 원본 이미지의 종횡비와 일치합니다. 레이어: 각 출력 레이어의 해상도는 size로 지정한 해상도에 가깝습니다. 각 출력 레이어의 종횡비는 원본 이미지에서 해당 레이어의 종횡비와 일치합니다. size의 기본값 및 선택 가능 값: 기본값: auto 유효한 값: 1K, 1.5K, 2K, auto(입력 이미지의 크기와 종횡비를 기준으로 출력)seedream-image-v5.0-lite는 다음 두 가지 방식을 지원하며 함께 사용할 수 없습니다.방식 1: 해상도를 지정하고 프롬프트에서 이미지의 종횡비, 형태 또는 용도를 자연어로 설명합니다.그러면 모델이 생성 이미지의 크기를 결정합니다. 유효한 값: 2K, 3K, 4K 방식 2: 생성 이미지의 너비와 높이를 픽셀 단위로 지정합니다.기본값: 2048x2048 총 픽셀 값 범위: [2560x1440 (3686400), 4096x4096 (16777216)] 종횡비 값 범위: [1/16, 16] |
| optimize_prompt_options | 선택 | object | 프롬프트 최적화 구성입니다. |
| optimize_prompt_options.mode | 선택 | string | 최적화 모드입니다. standard: 표준 모드. 더 높은 품질의 콘텐츠를 생성하지만 시간이 더 오래 걸립니다. fast: 고속 모드. 콘텐츠를 더 빠르게 생성하지만 품질이 standard 모드보다 약간 낮습니다. seedream-image-v5.0-lite는 현재 이 모드를 지원하지 않습니다. |
| output_format | 선택 | string | 이미지 형식입니다. 생성 이미지의 파일 형식을 지정합니다. 선택 가능 값: png jpeg |
| background | 선택 | string | 이미지 알파 채널입니다. 알파 채널이 있는 이미지를 생성할지 제어합니다. 선택 가능 값: transparent: 투명 배경 모드. 투명 배경의 이미지를 출력합니다. opaque: 불투명 배경 모드. 일반 단색 배경 이미지를 생성합니다. 지원 모델: seedream-image-v5.0-pro |
| response_format | 선택 | string | 응답 형식입니다. 생성 이미지의 반환 형식을 지정합니다. 다음 두 가지 반환 방식을 지원합니다. url: 이미지 다운로드 링크를 반환합니다. 링크는 이미지 생성 후 24시간 동안 유효합니다. 이미지를 즉시 다운로드하세요. b64_json: Base64로 인코딩된 이미지 데이터를 JSON 문자열로 반환합니다. |
| sequential_image_generation | 선택 | string | 그룹 이미지 모드입니다. 그룹 이미지 기능(입력에 따라 생성되는 서로 연관된 이미지 세트)을 비활성화할지 제어합니다. auto: 자동 모드. 모델이 사용자가 제공한 프롬프트를 기반으로 이미지 그룹 반환 여부와 그룹 내 이미지 수를 결정합니다. disabled: 그룹 이미지 기능을 비활성화합니다. 모델이 이미지 1개만 생성합니다.지원 모델: seedream-image-v5.0-lite |
| sequential_image_generation_options | 선택 | object | 그룹 이미지 구성입니다. 그룹 이미지 기능의 구성으로, sequential_image_generation이 auto로 설정된 경우에만 적용됩니다. 지원 모델: seedream-image-v5.0-lite |
| sequential_image_generation_options.max_images | 선택 | integer | 최대 생성 이미지 수입니다. 이 요청에서 생성할 수 있는 최대 이미지 수를 지정합니다. 값 범위: [1, 15]. |
| tools | 선택 | object | 도구 구성입니다. 지원 모델: seedream-image-v5.0-lite |
| tools.type | 선택 | string | 도구 유형입니다. 사용할 도구 유형을 지정합니다. web_search: 웹 검색 기능입니다. |
| watermark | 선택 | boolean | 워터마크 스위치입니다. 생성 이미지에 워터마크를 추가할지 지정합니다. false: 워터마크를 추가하지 않습니다. true: 이미지 오른쪽 하단에 "AI-generated" 워터마크를 추가합니다. |
요청 예시
참조 이미지 기반 이미지 생성
bash
curl -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/si-image/generation' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"model": "seedream-image-v5.0-pro",
"images": [
"https://mpstestmodel-1315536146.cos.ap-singapore.myqcloud.com/justin/wiki-examples/reference-cup.png"
],
"prompt": "a cat sitting on a windowsill at sunset",
"size": "2048x2048"
}'텍스트-이미지 생성(images 미사용)
bash
curl -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/si-image/generation' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"model": "seedream-image-v5.0-pro",
"prompt": "a cat sitting on a windowsill at sunset",
"size": "2048x2048"
}'응답 파라미터
| 필드 | 타입 | 설명 |
|---|---|---|
| created_at | string | 작업 생성 시간입니다. |
| data | object | 반환된 이미지 콘텐츠입니다. |
| data[].output_format | string | 출력 형식입니다. |
| data[].size | string | 이미지 크기입니다. |
| data[].url | string | 이미지 URL입니다. |
| data[].b64_json | string | 이미지 Base64 데이터입니다. |
| request_id | string | 문제 해결에 사용하는 고유 요청 식별자입니다. |
| model | string | 사용된 이미지 생성 모델입니다. |
| tokenhub_usage | object | 사용량입니다. |
| tokenhub_usage.total_tokens | integer | 이 작업에서 소비한 토큰 수로, 청구/정산에 사용됩니다. |
응답 예시
json
{
"created": 1787309367,
"data": [
{
"output_format": "jpeg",
"size": "2048x2048",
"url": "https://xxxxxxx.jpg"
}
],
"model": "doubao-seedream-5-0-pro-260628",
"tokenhub_usage": {
"total_tokens": 60000
},
"request_id": "f781d9dc-9792-43d8-82f3-90de51a1ff44"
}부록
통합 오류 코드
| 오류 코드 | 오류 메시지 | 설명 |
|---|---|---|
| BadRequest | 잘못된 요청 | 유효하지 않은 요청입니다. |
| FieldLacking | 필드가 없거나 비어 있음 | 필수 필드가 누락되었습니다. |
| FieldUnwanted | 불필요한 필드 | 불필요한 필드가 전달되었습니다. |
| FieldInvalid | 유효하지 않은 필드 | 입력 파라미터가 유효성 검사를 통과하지 못했습니다. |
| FieldItemCountOutOfRange | 필드 항목 수가 범위를 벗어남 | 필드 항목 수가 제한을 초과했습니다(예: 이미지 수가 제한을 초과함). |
| PageSizeOutOfRange | 페이지 크기가 범위를 벗어남 | 이미지 크기/파라미터가 제한을 초과했습니다. |
| ImageFormatInvalid | 유효하지 않은 이미지 형식 | 이미지 형식이 요구 사항을 충족하지 않습니다. |
| ImageSizeInvalid | 유효하지 않은 이미지 크기 | 이미지 크기가 너무 크거나 작습니다. |
| ImageDownloadFailure | 이미지 다운로드 실패 | URL에서 이미지를 다운로드하지 못했습니다. 링크를 확인하세요. |
| TaskPromptPolicyViolation | 프롬프트 정책 위반 | 프롬프트가 보안 검토 및 위험 제어를 트리거했습니다. |
| CreationPolicyViolation | 생성 정책 위반 | 생성된 콘텐츠가 위험 제어를 트리거했습니다. |
| AuditSubmitIllegal | 제출이 유효하지 않음 | 입력이 보안 검토를 통과하지 못했습니다. |
| CreditInsufficient | 크레딧 부족 | 크레딧이 부족합니다. |
| ModelUnavailable | 모델 사용 불가 | 모델을 사용할 수 없습니다. |
| Unauthorized | 인증되지 않음 | 인증되지 않았습니다(Authorization 확인). |
| Forbidden | 금지됨 | 요청에 권한이 없습니다. |
| TaskNotFound | 작업을 찾을 수 없음 | task_id를 찾을 수 없습니다. |
| QuotaExceeded | 할당량 초과 | 동시 실행 제한을 초과했습니다. |
| TooManyRequests | 요청이 너무 많음 | 요청 빈도가 너무 높습니다. |
| InternalServiceFailure | 내부 서비스 장애 | 내부 서버 오류입니다. |
이미지 리소스의 일반 제한
참조 이미지: seedream-image-v5.0-pro는 최대 10개, seedream-image-v5.0-lite는 최대 14개의 이미지를 지원합니다. 이미지 URL 또는 Base64 문자열을 지원합니다(Base64 문자열에는 data:image/png;base64, 접두사가 포함되어야 함). 지원 형식에는 jpeg/png/webp/bmp/tiff/gif/heic/heif가 있습니다. 최소 픽셀 크기는 14 x 14이고, 총 픽셀 수는 36 million을 초과할 수 없으며, 종횡비는 1:16 미만 또는 16:1 초과여야 합니다. 각 이미지는 30 MB를 초과할 수 없으며 POST 본문은 20 MB를 초과할 수 없습니다.
FAQ
1. 텍스트-이미지와 이미지-이미지를 구분하는 방법은 무엇인가요?
동일한 API가 두 모드를 모두 지원합니다. image를 전달하면 이미지의 참조 대상을 기준으로 참조 이미지 기반 이미지 생성이 활성화되고, images를 생략하면 프롬프트만으로 텍스트-이미지 생성을 수행합니다. seedream-image-v5.0-pro는 두 모드를 모두 지원합니다.
2. 생성된 이미지 링크에 만료 시간이 있나요?
생성 결과는 12시간 후 만료되는 임시 주소입니다. 작업 성공 후 즉시 다운로드하세요.