메인 콘텐츠로 건너뛰기
POST
Text-to-Image: generate an image from a text prompt
오른쪽의 인터랙티브 Playground를 통해 API를 직접 호출할 수 있습니다. Authorization을 API 키(형식: Bearer sk-xxx)로 설정하고, prompt를 입력한 후 모델과 크기를 선택하고 전송을 누르십시오.
적용 범위: 이 문서는 순수 텍스트-이미지 생성(image 필드 없음)을 다룹니다. 참조 이미지 편집, 다중 이미지 합성 또는 배치 시퀀스 생성에 대해서는 이미지 편집을 참조하십시오 — 동일한 엔드포인트이며 파라미터만 다릅니다.
🖥️ 브라우저 Playground 제한 사항(b64_json 모드 전용)기본 response_format: "url" 모드에서는 Playground가 정상 작동합니다(응답은 임시 BytePlus TOS 링크일 뿐입니다). response_format: "b64_json"(으)로 전환하면 응답에 수 MB 크기의 base64 문자열이 포함되어 브라우저 Playground에 请求时发生错误: unable to complete request이(가) 표시될 수 있습니다 — 실제로는 요청이 성공한 것이며, 단지 브라우저에서 이처럼 긴 base64 문자열을 렌더링하지 못할 뿐입니다.권장 워크플로:
  • 이미지만 확인하고 싶으신가요? 기본 url 모드를 유지하십시오 — Playground에서 링크를 직접 반환합니다(24시간 이내에 자체 스토리지로 다운로드해야 함을 유의하십시오).
  • b64_json이 필요하신가요? 아래 코드 샘플을 복사하여 로컬에서 실행하십시오 — 코드가 이미지를 자동으로 디코딩하여 파일로 저장합니다.
⚠️ 버전별로 해상도 등급이 다릅니다
  • seedream-5-0-flash-260915 — 프리셋 1K / 1.5K / 2K 및 총 0.92M4.62M 픽셀 범위의 정확한 WxH 지원, 가로세로 비율 최대 16:1(3K/4K 프리셋 없음, 프리셋 사용 시 모델이 화면 비율을 선택함, sequential_image_generation / stream은 허용되지 않음 — 전달 시 400 반환, 이미지당 약 1520초 소요, 요청당 $0.018)
  • seedream-5-0-pro-260628 — 프리셋 1K / 2K 및 최대 4.19M 총 픽셀의 정확한 WxH 지원(16:9 비율에서 가장 긴 변이 2720×1530에 도달함이 확인됨, 3K/4K 프리셋 없음, sequential_image_generation / stream은 허용되지 않음 — 전달 시 400 반환, 이미지당 약 2분 소요)
  • seedream-5-0-260128 — 2K / 3K만 지원(4K 미지원)
  • seedream-4-5-251128 — 2K / 4K
  • seedream-4-0-250828 — 1K / 2K / 4K
지원되지 않는 크기는 400을 반환합니다. 정확한 픽셀 값은 총 픽셀 수 ∈ [1280×720, 4096×4096] 및 가로세로 비율 ∈ [1/16, 16] 조건을 충족해야 합니다.
모든 이미지 API는 동기식입니다 — 폴링할 작업 ID가 없으며, 클라이언트 연결이 끊어지면 결과가 유실되어도 요청에 대해서는 과금됩니다. 이 모델에 대해 넉넉한 타임아웃을 설정하십시오. 자세한 내용은 이미지 API 필수 사항 및 모범 사례를 참조하십시오.

코드 예시

Python (OpenAI SDK)

Python (원시 요청)

cURL

Node.js (fetch)

브라우저 JavaScript

파라미터 참조

자세한 파라미터 제약 조건, 허용되는 값 및 예시는 오른쪽 Playground 패널에서 확인할 수 있습니다. 편집 / 다중 이미지 파라미터(image, sequential_image_generation 등)는 이미지 편집 페이지에 설명되어 있습니다.

응답 형식

⚠️ 응답 필드 주의 사항
  • response_format=url일 때, data[].url는 임시 서명된 BytePlus TOS URL입니다(일반적으로 24시간 동안 유효합니다). 운영 환경에서는 즉시 자체 저장소로 다운로드하십시오.
  • response_format=b64_json일 때, data[].b64_json는 data:image/...;base64, 접두사가 없는 일반 base64 문자열입니다. 파일 출력용으로는 이를 디코딩하고(base64.b64decode), 브라우저 렌더링용으로는 직접 접두사를 추가하십시오.
  • data[].size는 실제 출력 크기를 반영하며, 모델의 가로세로 비율 정규화 후 요청한 size와 약간 다를 수 있습니다.
usage.generated_images는 과금된 이미지 수를 반영합니다. Seedream은 이미지당 과금되며, output_tokens / total_tokens는 관측 지표이므로 과금에 영향을 주지 않습니다.

인증

Authorization
string
header
필수

API Key obtained from APIYI Console

본문

application/json
model
enum<string>
기본값:seedream-5-0-260128
필수

Model ID

사용 가능한 옵션:
seedream-5-0-260128,
seedream-5-0-lite-260128,
seedream-4-5-251128,
seedream-4-0-250828,
seedream-5-0-pro-260628,
seedream-5-0-flash-260915
prompt
string
필수

Prompt, supports both English and Chinese. Describe scene, style, and lighting in detail for better results.

예시:

"A serene Japanese garden with cherry blossoms, koi pond, traditional bridge, golden hour, ultra detailed"

size
string
기본값:2K

Output size. Preset tiers (vary by version):

  • 1K (~1024×1024) — 4.0 / 5.0-pro / 5.0-flash
  • 1.5K (~1536×1536) — 5.0-flash only
  • 2K (~2048×2048) — 5.0 / 4.5 / 4.0
  • 3K (~3072×3072) — 5.0 only
  • 4K (~4096×4096) — 4.5 / 4.0

Or exact pixel size WxH, total pixels ∈ [1280×720, 4096×4096], aspect ratio ∈ [1/16, 16]

예시:

"2K"

response_format
enum<string>
기본값:url

url returns a temp signed link (24h validity); b64_json returns plain base64 (no data: prefix)

사용 가능한 옵션:
url,
b64_json
output_format
enum<string>
기본값:jpeg

Output format. 5.0 supports png/jpeg; 4.5/4.0 only jpeg

사용 가능한 옵션:
png,
jpeg
seed
integer

Random seed. Note: officially supported only by seedream-3-0-t2i; ignored by the current 4.x / 5.x models

예시:

42

watermark
boolean
기본값:false

Whether to include the BytePlus watermark. Set to false for commercial use

stream
boolean
기본값:false

Enable streaming output. Useful for long prompts and high-resolution generation. Not accepted by 5.0-pro / 5.0-flash (returns 400)

응답

Image generated successfully

model
string
예시:

"seedream-5-0-260128"

created
integer

Unix timestamp

예시:

1768518000

data
object[]
usage
object