Seedream 5.0 Pro 文생성 이미지 API 연동: curl, Python 및 텍스트 작성 요령

Seedream 5.0 Pro 文생성 이미지(seedream-5.0-pro/text-to-image)는 Seedream 5.0 제품군에서 가장 비싼 등급이며, 강점은 이미지 안의 텍스트입니다. 간판, 포장, 포스터 제목을 프롬프트에 따라 글자 그대로 씁니다. 이 글에서는 바로 실행할 수 있는 curl 및 Python 예제, 전체 파라미터, 흔한 오류, 그리고 텍스트를 올바르게 쓰는 몇 가지 방법을 제시합니다.

먼저 가격

해상도	장당	100장
1K	$0.05	$5
2K(기본)	$0.10	$10

HiAPI 현재 가격, 2026년 10월 18일 확인.

화면 비율은 가격에 영향을 주지 않으며, 실패 시에는 과금되지 않습니다. Pro에는 4K가 없습니다. 4K가 필요하면 Seedream 5.0 Lite(2K/4K 동일 가격 $0.035)를 사용하세요. 세 등급 비교는 Seedream 5.0 API 가격을 참고하세요.

실제 출력 예시

16:9, 1K, 네온 간판의 글자를 글자 그대로 올바르게 작성:

A neon-lit night market street in a rainy cyberpunk city, a glowing storefront sign reads "SEEDREAM 5 PRO" in crisp lettering, cinematic composition, dramatic directional lighting, rich cohesive color grade, ultra-detailed, premium commercial finish, subtle film grain, shallow depth of field, high dynamic range

이 프롬프트로 생성하기 →

seedream-5.0-pro/text-to-image, 16:9, 1K, $0.05.

첫 이미지 생성까지

준비: 콘솔에서 API Key를 생성하고 환경 변수로 설정하세요:

export HIAPI_KEY="당신의 Key"

curl: 작업 제출

curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5.0-pro/text-to-image",
    "input": {
      "prompt": "A cozy coffee shop storefront at dusk, warm window light, a hand-painted wooden sign that reads \"THE DAILY GRIND\" in serif letters",
      "aspect_ratio": "16:9",
      "resolution": "2K"
    }
  }'

taskId 반환:

{"code": 200, "message": "success", "data": {"taskId": "tk-hiapi-..."}}

curl: 결과 조회

curl "https://api.hiapi.ai/v1/tasks/tk-hiapi-..." \
  -H "Authorization: Bearer $HIAPI_KEY"

data.status가 success이면 이미지 주소는 data.output[0].url에 있습니다. 만료 시간이 있는 임시 링크이므로 받자마자 다운로드하세요:

curl -o result.png "<output 里的 url>"

2K는 보통 1분 정도면 출력됩니다.

Python(표준 라이브러리만 사용)

import json, os, time, urllib.request

API = "https://api.hiapi.ai/v1/tasks"
KEY = os.environ["HIAPI_KEY"]

def api(url, payload=None):
    req = urllib.request.Request(
        url,
        data=json.dumps(payload).encode() if payload else None,
        headers={"Authorization": f"Bearer {KEY}", "Content-Type": "application/json"},
        method="POST" if payload else "GET",
    )
    with urllib.request.urlopen(req) as resp:
        return json.loads(resp.read())

task_id = api(API, {
    "model": "seedream-5.0-pro/text-to-image",
    "input": {
        "prompt": 'A minimalist product poster on matte black, bold white headline that reads "SHIP FASTER", small caption "batch v2.1" bottom right',
        "aspect_ratio": "3:4",
        "resolution": "2K",
    },
})["data"]["taskId"]

while True:
    task = api(f"{API}/{task_id}")["data"]
    if task["status"] == "success":
        break
    if task["status"] == "fail":
        raise RuntimeError(task)
    time.sleep(5)

urllib.request.urlretrieve(task["output"][0]["url"], "result.png")

전체 파라미터

필드	필수	값
prompt	예	3–4000자, 약 600개 영어 단어 이내로 유지 권장
aspect_ratio	예	1:1, 4:3, 3:4, 16:9, 9:16, 2:3, 3:2, 21:9
resolution	예	1K($0.05) 또는 2K($0.10)
output_format	아니오	png(기본) 또는 jpeg

필드가 매우 엄격합니다. seed, n, size, image_urls 등은 허용되지 않으며, 추가로 전달하면 HTTP 400이 반환됩니다. 요청 1회당 1장이 생성되며, 여러 장이 필요하면 여러 작업을 동시에 제출하세요.

같은 제품군의 등급별 해상도는 다릅니다. Pro는 1K/2K, Lite는 2K/4K입니다. 등급을 전환할 때는 resolution을 변경해야 합니다.

텍스트를 올바르게 쓰는 방법

• 쓸 글자는 따옴표로 감싸기: a sign that reads "OPEN 24 HOURS"가 설명보다 훨씬 안정적입니다.
• 위치와 스타일을 명확히: 글꼴 느낌(세리프, 손글씨, 네온), 위치(오른쪽 아래, 중앙), 소재(나무 간판, 유리문)를 지정하세요.
• 글자를 너무 많이 넣지 않기: 한 이미지에 짧은 텍스트 몇 개는 안정적이지만, 긴 문장은 불안정합니다.
• 텍스트가 핵심이면 2K 사용: 작은 글자는 고해상도에서 더 선명합니다.

흔한 오류

현상	반환	해결 방법
필수 필드 누락	400, missing required field "aspect_ratio"	필수 필드 세 개를 모두 전달
열거 값 오류	400, resolution: value must be one of '1K', '2K'	위 표에 따라 입력
seed, n 등 추가 전달	400, additional properties ... not allowed	불필요한 필드 삭제
Key 무효	401, permission_denied	콘솔에서 Key 확인

작업 생성 후 실패한 경우 조회 결과에서 status: "fail"로 표시되며, 과금되지 않습니다.

출시 전 유의사항

• 폴링 대신 콜백 사용: 요청 본문 최상위(model, input과 동일 레벨)에 "callback": {"url": "https://당신의도메인/hooks/hiapi", "when": "final"}을 추가하세요. 알림을 받은 후 작업을 한 번 더 GET하여 결과를 확인하세요.
• 중복 과금 방지: 작업이 접수되는 즉시 과금됩니다. 재시도 전에 해당 작업의 taskId를 기록했는지 확인하고, 있으면 계속 조회하며 재제출하지 마세요. 제출 시 Idempotency-Key 요청 헤더를 사용할 수도 있습니다.
• 즉시 저장: 출력 링크는 만료되므로 직접 외부 링크로 사용하지 마세요.

자주 묻는 질문

seed를 고정하여 재현할 수 있나요?

아니요, 이 인터페이스는 seed를 받지 않습니다. 기존 이미지를 기반으로 유사한 버전을 생성하려면 seedream-5.0-pro/image-to-image를 사용하세요. 최대 10장의 참조 이미지를 전달할 수 있습니다.

Lite와의 차이는 무엇인가요?

Lite는 장당 $0.035이며 해상도는 2K/4K입니다. Pro는 1K/2K이며 2K는 장당 $0.10입니다. 호출 방식은 동일합니다. Flash와 Lite의 동일 프롬프트 비교는 Seedream 5.0 Flash vs Lite를 참고하세요.

콜백을 반드시 사용해야 하나요?

아니요. 스크립트와 배치 작업은 직접 폴링하면 되며, 5초마다 한 번씩 조회하세요.

위의 네온 간판 프롬프트를 그대로 복사하여 $0.05로 한 장 생성할 수도 있습니다.