튜토리얼
HiAPI API로 seedream-4.5/text-to-image 사용하는 방법: curl 및 Python 예제
개발자를 위한 최소 실행 가능 통합 실전 가이드
이 페이지에서
seedream-4.5/text-to-image가 제공하는 것
seedream-4.5/text-to-image는 HiAPI API를 통해 제공되는 텍스트-투-이미지 엔드포인트입니다. 텍스트 프롬프트와 몇 가지 선택적 파라미터를 보내면 모델이 생성된 이미지를 반환합니다. 장면 일러스트, 제품 목업 이미지, 콘셉트 아트, 또는 이미지 안에 읽을 수 있는 텍스트(간판, 라벨, 짧은 제목)를 렌더링해야 하는 모든 시각 콘텐츠를 만드는 데 사용할 수 있습니다. 이 엔드포인트는 상태를 저장하지 않습니다. 각 요청은 독립적인 한 번의 생성이므로 반복과 변화에 대한 제어권은 애플리케이션 코드에 있습니다.
다른 HiAPI 모델과 동일한 통합 인터페이스 뒤에서 실행되므로 한 번만 인증하면 되고, 같은 기본 URL과 오류 규약을 사용하며, 모델을 전환할 때 새로운 통합 패턴을 배울 필요가 없습니다. seedream-4.5/text-to-image의 모델 상세 페이지에 현재 파라미터 이름과 허용 값이 나열되어 있습니다. 필드에 대한 권위 있는 출처는 이 문서가 아니라 해당 페이지를 기준으로 삼으세요.
요청 구조: 보내는 것과 받는 것
모든 텍스트-투-이미지 호출은 동일한 구조를 가집니다. 모델의 HiAPI 엔드포인트에 JSON 요청 본문을 담아 POST 요청을 보냅니다. 요청 본문에는 모델이 필요로 하는 필드가 포함되고, 응답에는 생성된 이미지와 해당 요청에 대한 메타데이터가 포함됩니다.
보내는 내용
prompt(문자열, 필수): 이미지에 대한 설명입니다. 이것이 주요 제어 수단입니다. 아래 프롬프트 섹션을 참고하세요.aspect_ratio또는 크기 관련 필드(선택): 출력 캔버스의 형태를 제어합니다. 모델 상세 페이지에 적힌 정확한 필드 이름을 사용하세요. 다른 모델의 파라미터 이름과 같다고 가정하지 마세요.- 모델 페이지에 기록된 모든 모델 전용 옵션(예: 스타일 또는 품질 힌트). 필요 없는 필드는 생략하세요. API가 기본값을 적용합니다.
받는 내용
성공 응답은 JSON 객체입니다. 코드에서 실제로 읽게 되는 필드는 보통 다음과 같습니다:
- 이미지 페이로드: 응답 스키마에 따라 생성 이미지의 URL이거나 base64로 인코딩된 이미지 문자열입니다. 코드는 엔드포인트가 실제로 반환하는 형식을 처리해야 합니다. 모델 페이지에서 어느 쪽인지 설명합니다.
- 요청 메타데이터(예: 식별자 또는 상태)로, 로깅과 지원에 유용합니다.
모든 필드가 모든 버전에서 보장되지는 않으므로 고정된 스키마를 가정하지 말고 응답 구조를 검증하세요. 필요한 필드만 찾고 나머지는 선택 사항으로 취급하는 파서를 만들면 사소한 응답 변화에도 통합이 견딜 수 있습니다.
첫 번째 실행 가능한 curl 요청
최소한의 유효한 호출은 프롬프트 하나만 보내고 다른 것은 보내지 않습니다. 자리 표시자 키와 프롬프트를 자신의 것으로 바꾼 뒤 실행하세요.
curl -X POST "https://api.hiapi.ai/v1/models/seedream-4.5/text-to-image" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "해질녘 한적한 거리 카페, 따뜻한 창문 불빛, OPEN이라고 적힌 칠판 간판",
"aspect_ratio": "1:1"
}'
줄별 설명:
- URL은 해당 모델의 HiAPI 엔드포인트를 가리킵니다. 모델 식별자를 문서와 정확히 동일하게 유지하세요.
Authorization헤더는 API 키를 전달합니다. 환경 변수를 사용하면 키가 셸 기록과 소스 파일에 나타나지 않습니다.Content-Type: application/json은 서버에 요청 본문을 JSON으로 파싱하라고 알려줍니다.- JSON 본문에는 프롬프트와 선택적 가로세로 비율이 포함됩니다. 먼저 이미지 한 장과 프롬프트 하나로 시작하고, 옵션을 추가하기 전에 문구를 반복 개선하세요.
호출이 성공하면 응답에 이전 섹션에서 설명한 이미지 데이터가 포함됩니다. 출력을 파일로 저장하거나(또는 반환된 URL을 열어) 더 많은 것을 구축하기 전에 확인하세요. 인증 오류가 발생하면 키가 존재하는지, 헤더 철자가 올바른지 확인하세요. 파라미터 오류가 발생하면 모델 페이지와 대조해 필드 이름을 다시 확인하세요.
Python으로 동일한 요청 구현하기
Python 버전은 표준 requests 라이브러리를 사용합니다. SDK는 필요 없습니다.
import os
import requests
API_KEY = os.environ["HIAPI_API_KEY"]
URL = "https://api.hiapi.ai/v1/models/seedream-4.5/text-to-image"
payload = {
"prompt": "해질녘 한적한 거리 카페, 따뜻한 창문 불빛, OPEN이라고 적힌 칠판 간판",
"aspect_ratio": "1:1",
}
response = requests.post(
URL,
headers={"Authorization": f"Bearer {API_KEY}"},
json=payload,
timeout=60,
)
response.raise_for_status()
result = response.json()
print(result)
여기서 두 가지 세부 사항이 중요합니다. 첫째, 수동으로 만든 문자열이 아니라 json=payload를 전달하세요. requests가 콘텐츠 유형을 설정하고 올바르게 직렬화합니다. 둘째, 명시적인 timeout을 설정하세요. 이미지 생성은 일반적인 API 호출보다 오래 걸릴 수 있으므로, 명확한 실패 모드가 있는 넉넉한 타임아웃이 멈춰 있는 요청보다 낫습니다.
출력된 결과는 원시 응답입니다. 실제 코드에서는 엔드포인트가 반환한 이미지 필드(URL 또는 base64)를 추출한 뒤, 두 번째 요청으로 해당 URL을 다운로드하거나 base64를 바이트로 디코딩해 디스크에 기록하세요. 이 추출 로직을 작은 헬퍼 함수에 두면 테스트와 프로덕션 코드가 동일한 파싱 로직을 공유하게 됩니다.
사실적 효과와 읽을 수 있는 텍스트를 위한 프롬프트 작성
프롬프트 품질이 다른 어떤 파라미터보다도 출력 품질을 좌우합니다. 가장 자주 나타나는 두 가지 목표는 사진처럼 사실적인 장면과 이미지 안의 선명하게 읽을 수 있는 텍스트입니다.
사실적 효과
사진작가가 프레이밍하듯 장면을 묘사하세요: 피사체, 조명, 시간대, 렌즈 느낌, 환경. 구체적인 명사가 추상적인 형용사보다 낫습니다. "좋은 카페"라고 쓰지 말고 "큰 창문으로 정오의 빛이 들어오는 좁고 긴 카페 내부, 나무 카운터, 얕은 심도"라고 쓰세요. "photograph"나 "documentary photo" 같은 짧은 스타일 힌트를 추가해 모델이 일러스트 스타일에서 벗어나도록 유도하세요. 프롬프트마다 주요 피사체는 하나로 유지하세요. 서로 경쟁하는 피사체는 종종 혼란스러운 구도를 만듭니다.
읽을 수 있는 텍스트
이미지에 텍스트가 반드시 포함되어야 할 때는 정확한 텍스트를 따옴표로 감싸고 짧게 유지하세요. OPEN이라고 적힌 간판이나 FRESH BREAD라고 적힌 라벨이 긴 문단보다 훨씬 안정적입니다. 텍스트가 나타날 위치를 설명하세요. "카운터 위 OPEN이라고 적힌 칠판 간판"이라고 하면 모델이 해당 텍스트가 특정 물체에 속한다는 것을 알게 됩니다. 텍스트가 깨져 나오면 더 짧게 줄이고 주변 장면을 단순화한 뒤 다시 생성하세요. 문구를 조금씩 조정하는 것은 정상이며, 몇 번의 반복이 필요하다고 예상하세요.
반복
한 번에 변수 하나만 바꾸세요. 먼저 프롬프트, 다음 가로세로 비율, 마지막으로 스타일 옵션입니다. 좋은 결과를 낸 프롬프트와 설정을 저장하세요. 이 기록이 재생성 기준선이 되고 디버깅이 추측으로 흐르는 것을 막아 줍니다.
가로세로 비율과 출력 설정 선택
가로세로 비율은 모델이 무엇이든 그리기 전에 구도를 결정합니다. 기본값에 맞추기 위해서가 아니라 대상 용도에 맞춰 선택하세요.
- 정사각형(
1:1): 소셜 게시물, 아바타, 제품 타일. 단순하고 안전합니다. - 가로형(예:
16:9): 배너, 키 비주얼, 프레젠테이션 슬라이드. 지평선, 상점 정면, 넓은 실내 같은 넓은 장면을 장려합니다. - 세로형(예:
9:16): 모바일 화면, 스토리, 포스터. 서 있는 인물, 높은 건물처럼 명확한 수직 피사체가 있는 프롬프트가 가장 잘 맞습니다.
프롬프트가 넓은 장면을 묘사하는데 세로 캔버스를 요청하면 모델이 구도를 자르거나 왜곡해야 합니다. 설명과 화면 비율을 일치시키세요. 다운스트림 파이프라인이라면 가장 큰 사용 사례에 맞는 크기로 생성한 뒤 나중에 축소하세요. 작은 이미지를 확대하면 제대로 보이는 경우가 거의 없습니다. 여러 형식이 필요하면 한 이미지를 여러 레이아웃으로 자르지 말고 비율별로 각각 호출하세요.
가로세로 비율 외의 출력 설정(품질 힌트, 스타일 제어)은 모델 전용입니다. 모델 페이지에 기록된 것만 설정하고, 추가 파라미터는 그대로 복사할 기본값이 아니라 테스트해야 할 변수로 취급하세요.
오류와 속도 제한 처리
프로덕션 통합의 실패 원인은 예측 가능합니다: 잘못된 키, 유효하지 않은 파라미터, 타임아웃, 속도 제한입니다. 각 유형을 명시적으로 처리하세요.
파싱 전에 검증
먼저 HTTP 상태 코드를 확인하세요. 2xx는 성공이며, 그다음 응답 본문을 파싱합니다. 4xx는 보통 요청에 문제가 있음을 의미합니다: 키 미인증, JSON 형식 오류, 지원되지 않는 파라미터 값. 이런 문제는 재시도해도 저절로 해결되지 않습니다. 응답 본문을 기록하고 호출자에게 보고하며 요청을 수정하세요. 5xx는 서버 측 문제이며 보통 일시적입니다.
백오프를 포함한 재시도
나중에 성공할 가능성이 있는 실패만 재시도하세요: 429 응답, 타임아웃, 연결 오류, 대부분의 5xx 상태 코드입니다. 지터를 포함한 지수 백오프를 사용하세요. 짧은 기준 간격으로 기다리고 시도마다 두 배로 늘리며 총 시도 횟수에 상한을 두세요. 400이나 401은 절대 재시도하지 마세요. 할당량만 낭비할 뿐입니다.
import time, random
def generate(payload, max_attempts=5):
for attempt in range(max_attempts):
try:
r = requests.post(URL, headers=HEADERS, json=payload, timeout=60)
except requests.RequestException:
pass # 네트워크 오류: 아래에서 재시도
else:
if r.status_code == 200:
return r.json()
if r.status_code not in (429, 500, 502, 503, 504):
raise RuntimeError(f"복구 불가: {r.status_code} {r.text}")
time.sleep(min(2 ** attempt + random.random(), 30))
raise RuntimeError("재시도 횟수 소진")
제한 준수
요청량을 계정에 표시된 속도 제한 아래로 유지하고, 429는 더 세게 재시도하라는 신호가 아니라 속도를 늦추라는 신호로 취급하세요. 워커에 동시성 상한을 추가하고 시도마다 요청 ID를 기록해 나중에 속도 제한과 실패를 진단할 수 있게 하세요. 이미지 호출은 생성된 출력에 대해 과금되므로 이미지를 생성하는 재시도는 무료가 아닙니다. 요청을 보내기 전에 입력을 검증하세요.
테스트 호출에서 프로덕션으로 가는 체크리스트
출시 전에 다음 운영 요점을 확인하세요:
- 키 관리: 키는 환경 변수나 비밀 관리자에 보관하고 절대 소스 제어에 넣지 마세요. 정기적으로 키를 교체하고, 유출이 의심되면 즉시 교체하세요.
- 타임아웃: 모든 아웃바운드 호출에 명시적 타임아웃이 있고, 호출자가 타임아웃 발생 시 처리 방안을 갖추고 있습니다.
- 로깅: 호출마다 요청 ID, 프롬프트 버전, 파라미터, 상태, 지연 시간을 기록하세요. 필요할 때 키와 전체 페이로드를 마스킹하세요.
- 프롬프트 버전 관리: 승인된 출력을 낸 프롬프트와 설정을 저장해 재현과 롤백이 가능하게 하세요.
- 비용 인식: 생성은 출력에 대해 과금되므로 배치 크기를 제한하고 불필요한 재시도를 피하며 재사용할 결과를 캐시하세요.
- 우아한 성능 저하: 재시도 후에도 생성이 실패하면 페이지를 깨뜨리지 말고 캐시된 이미지나 자리 표시자로 폴백하세요.
이 가이드의 단일 curl 호출로 시작해 작은 Python 헬퍼 함수로 옮기고, 그다음에야 동시성과 배치 처리를 추가하세요. 통합을 확장할 때 필드 이름을 확인할 곳은 seedream-4.5/text-to-image의 모델 참조 페이지입니다.