Kling 4.0 API 출시. 동영상 생성을 시작하세요 →
PoYoPoYo
tutorials

Seedream 5.0 Pro API 가이드: 코드로 이미지 생성 및 편집하기

Poyo.ai Team
5 min read
Share:

Seedream 5.0 Pro API 가이드

Seedream 5.0 Pro API는 개발자가 프로덕션 중심의 비동기 워크플로를 통해 ByteDance의 대표 이미지 생성 및 편집 모델에 접근할 수 있도록 제공합니다. 이 가이드는 Poyo.ai를 통해 텍스트-이미지 및 이미지 편집 작업을 제출한 다음, 폴링 또는 웹훅으로 결과를 가져오는 방법을 설명합니다.

현재 가격은 두 모델 변형 모두 생성된 이미지 1장당 15 크레딧, 약 $0.075입니다.

API 모델 및 매개변수

워크플로모델 ID
텍스트에서 이미지 생성seedream-5.0-pro
이미지 편집seedream-5.0-pro-edit

지원되는 입력 항목:

  • prompt: 필수 생성 또는 편집 지시사항
  • size: 1K 또는 2K과 같은 해상도 프리셋, 또는 1:1, 4:3, 3:4, 16:9, 9:16과 같은 화면 비율
  • n: 생성할 이미지 수
  • output_format: jpeg 또는 png
  • image_urls: 편집 모델용 참조 이미지, 최대 10개
  • callback_url: 선택 사항인 완료 알림용 HTTPS 엔드포인트

현재 스키마는 실시간 API 참조에서 확인하세요.

1. API 키 생성

Poyo.ai 계정을 생성하고 API Key Management를 연 다음, 키를 환경 변수에 저장하세요. 프로덕션 키를 브라우저 코드에 노출하거나 Git에 커밋하지 마세요.

export POYO_API_KEY="your-api-key"

2. 텍스트-이미지 요청 제출

모든 작업은 통합 제출 엔드포인트를 사용합니다:

POST https://api.poyo.ai/api/generate/submit

cURL

curl --request POST \
  --url https://api.poyo.ai/api/generate/submit \
  --header "Authorization: Bearer $POYO_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "seedream-5.0-pro",
    "callback_url": "https://example.com/webhooks/poyo",
    "input": {
      "prompt": "Editorial science magazine cover about clean energy cities, title \"THE ELECTRIC CITY\", structured grid, accurate icons, dark navy and electric green palette",
      "size": "3:4",
      "n": 1,
      "output_format": "png"
    }
  }'

응답에는 작업 ID가 포함됩니다:

{
  "code": 200,
  "data": {
    "task_id": "task-unified-example",
    "status": "not_started",
    "created_time": "2026-07-16T10:10:00"
  }
}

3. JavaScript로 Seedream 5.0 Pro 호출

const API_URL = 'https://api.poyo.ai/api/generate/submit';

async function generateSeedreamImage(prompt) {
  const response = await fetch(API_URL, {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.POYO_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      model: 'seedream-5.0-pro',
      input: {
        prompt,
        size: '2K',
        n: 1,
        output_format: 'png',
      },
    }),
  });

  const payload = await response.json();
  if (!response.ok || payload.code !== 200) {
    throw new Error(payload.error?.message || 'Seedream request failed');
  }
  return payload.data.task_id;
}

해상도가 고정된 비율보다 중요한 경우 2K을 사용하세요. 배치 형식이 주요 제약 조건인 경우 화면 비율 값을 사용하세요.

4. Python으로 Seedream 5.0 Pro 호출

import os
import requests

API_URL = "https://api.poyo.ai/api/generate/submit"

def generate_seedream_image(prompt: str) -> str:
    response = requests.post(
        API_URL,
        headers={
            "Authorization": f"Bearer {os.environ['POYO_API_KEY']}",
            "Content-Type": "application/json",
        },
        json={
            "model": "seedream-5.0-pro",
            "input": {
                "prompt": prompt,
                "size": "16:9",
                "n": 1,
                "output_format": "jpeg",
            },
        },
        timeout=30,
    )
    response.raise_for_status()
    payload = response.json()
    if payload.get("code") != 200:
        raise RuntimeError(payload.get("error", {}).get("message", "Request failed"))
    return payload["data"]["task_id"]

5. 여러 참조 이미지로 이미지 편집

모델 ID를 변경하고 image_urls을 제공하세요. 각 참조 이미지가 어떤 역할을 하는지 모델에 설명하세요.

curl --request POST \
  --url https://api.poyo.ai/api/generate/submit \
  --header "Authorization: Bearer $POYO_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "seedream-5.0-pro-edit",
    "input": {
      "prompt": "Use the room from reference 1. Replace only the chair with the chair from reference 2. Put the logo from reference 3 on the wall. Preserve the original camera, windows, floor, and afternoon lighting.",
      "image_urls": [
        "https://example.com/room.jpg",
        "https://example.com/chair.png",
        "https://example.com/logo.png"
      ],
      "size": "16:9",
      "n": 1,
      "output_format": "png"
    }
  }'

안정적인 편집을 위해 프롬프트를 세 가지 요소로 나누세요: 참조 역할, 요청된 변경 사항, 유지해야 할 제약 조건.

6. 결과 가져오기

제출은 비동기 방식으로 처리됩니다. task_id을 받은 후 다음 중 하나를 수행하세요:

  • Poyo.ai의 통합 작업 상태 엔드포인트를 폴링합니다.
  • 또는 callback_url을 제공하고 완료 웹훅을 처리합니다.

현재 상태 경로와 응답 객체는 작업 관리 문서를 따르세요. 프로덕션 환경에서는 지속적으로 폴링하는 대신 지수 백오프를 사용하세요.

오류 처리

다음 상황을 명확하게 처리하세요:

  • 400: 잘못된 모델 매개변수, 지원되지 않는 크기, 접근할 수 없는 이미지 URL 또는 잘못된 JSON 형식
  • 401: 누락되었거나 유효하지 않은 API 키
  • 실패한 비동기 작업: 유효한 제출 후 생성 실패
  • 웹훅 재시도: 동일한 완료 이벤트가 두 번 이상 전달될 수 있음

작업 ID를 내부 작업 ID와 함께 저장하고, 웹훅 처리를 멱등적으로 구현하며, 비밀 정보를 기록하지 않고 제공자 오류 메시지를 로그로 남기세요.

프로덕션 체크리스트

  • API 키는 서버 측에 보관하세요.
  • 제출 전에 프롬프트 길이와 이미지 URL 유형을 검증하세요.
  • 생성 서비스가 접근할 수 있는 HTTPS 참조 이미지를 사용하세요.
  • 제출 호출에 요청 시간 제한을 설정하세요.
  • 일시적인 네트워크 오류는 재시도하되, 잘못된 요청을 무조건 재시도하지 마세요.
  • 현재 가격 기준으로 비용을 number of requested outputs × 15 credits으로 추적하세요.
  • 게시 전에 생성된 텍스트, 제품 세부 정보 및 사실 주장을 검토하세요.
  • 제품과 시장에 적합한 콘텐츠 조정 기능을 추가하세요.

Lite 대신 Pro를 사용해야 하는 경우

구조화된 디자인, 복잡한 레이아웃, 다국어 텍스트 및 정밀한 편집이 필요한 경우 Seedream 5.0 Pro를 사용하세요. Pro 수준의 디자인 정밀도가 필요하지 않은 저비용 대량 이미지 작업에는 Seedream 5.0 Lite를 사용하세요.

비기술적인 개요는 Seedream 5.0 Pro 기능 및 가격을 확인하세요. 또한 Seedream 5.0 Pro 모델 페이지에서 API 페이로드를 시각적으로 테스트할 수 있습니다.

자주 묻는 질문

Seedream 5.0 Pro API 엔드포인트는 무엇인가요?

생성 및 편집 작업을 POST https://api.poyo.ai/api/generate/submit 엔드포인트로 제출하세요.

편집 모델 ID는 무엇인가요?

seedream-5.0-pro-edit을 사용하고 input.image_urls에 하나 이상의 값을 포함하세요.

몇 개의 참조 이미지를 지원하나요?

현재 Poyo.ai 문서에서는 Seedream 5.0 Pro 편집에 최대 10개의 참조 이미지를 지원합니다.

API 이미지 1장의 비용은 얼마인가요?

현재 Poyo.ai 가격은 생성 또는 편집된 이미지 1장당 15 크레딧, 약 $0.075입니다.

Share: