Krea 3 API 사용법? 5분 만에 첫 이미지 생성하기

TL;DR

• Krea 3(krea-3/text-to-image)는 텍스트→이미지 모델입니다. 한 줄 설명만으로 사실적 사진, 일러스트, 콘셉트 이미지를 만들며, 이미지를 생성하기 전에 프롬프트를 이해하고 확장합니다. 두 가지 변형 berry(품질 우선, 기본값) / jam(속도 우선)을 같은 가격으로 전환할 수 있습니다. 모델 페이지를 열면 바로 시험해볼 수 있고, 신규 가입 시 200 크레딧을 지급합니다.
• 가격은 장당입니다: Krea 3 $0.036; 같은 패밀리의 더 저렴한 Krea 2 Medium Turbo(krea-2-medium-turbo) $0.0215 (전체 가격표는 가격 페이지 참고).
• 호출은 HiAPI /v1/tasks 인터페이스로 합니다: 작업을 제출해 taskId를 받고, 결과를 조회한 뒤 성공하면 output[0].url에서 이미지를 다운로드합니다.

무엇을 할 수 있나

• 한 줄 프롬프트로도 완성된 화면: 모델이 이미지 생성 전에 먼저 추론·확장을 하므로 a lighthouse만 써도 시간, 빛, 구도를 채워 넣습니다. 구체적으로 쓰면 그 설명대로 따라갑니다.
• berry / jam 두 변형을 하나의 ID로: variant로 전환하며 파라미터와 가격은 완전히 같습니다. 같은 seed에서 둘의 구도와 색조가 다르므로 각각 한 번씩 돌려 두 가지 안으로 골라보세요.
• 6가지 크기 프리셋, 최대 1K: 정방형, 세로형, 가로형 총 6가지(1024×1024부터 1024×576까지), 출력은 PNG 또는 JPEG.
• 제목 텍스트가 들어간 포스터도 생성: 텍스트를 따옴표로 감싸면 짧은 제목은 대개 정확합니다.

아래는 berry의 실제 결과물입니다:

Studio product photograph of a frosted glass perfume bottle with a brushed brass cap standing on a block of travertine, hard afternoon sunlight casting a long palm-leaf shadow across a warm beige wall, crisp reflections, high-end editorial look

(한국어 의미: 스튜디오 제품 사진: 브러시드 황동 캡이 달린 무광 유리 향수병이 트래버틴 돌 위에 서 있고, 오후의 강한 햇빛이 야자수 잎의 긴 그림자를 따뜻한 베이지색 벽면에 드리우며, 반사가 선명하고, 하이엔드 잡지 느낌. 크기는 기본값 square_hd 사용.)

krea-3/text-to-image, berry, square_hd, 1024×1024, $0.036.

이 프롬프트로 생성하기 →

두 모델 중 무엇을 선택할까

	krea-3/text-to-image (Krea 3)	krea-2-medium-turbo (Krea 2 Medium Turbo)
장당	$0.036	$0.0215
크기	6가지 프리셋(최대 1024×1024), 사용자 지정 불가	aspect_ratio 8가지 비율, 2.35:1 시네마 와이드 포함
특색 파라미터	variant(berry/jam), reasoning_level(추론 확장), negative_prompt(berry만)	creativity 4단계(raw/low/medium/high)
프롬프트 처리	생성 전 추론 확장, 짧은 문장도 완성된 화면을 생성	원문 그대로 반영, 쓴 만큼 자세하게 생성
적합한 용도	최종 이미지 생성, 짧은 프롬프트로 빠른 탐색, 텍스트가 들어간 포스터	대량 이미지 생성, 와이드 구도, 예산에 민감한 일상 생산

두 모델은 이어서 쓸 수 있습니다: Krea 2로 초안을 잡아 방향을 정하고 Krea 3로 최종본을 생성하면 초안 한 장 + 최종본 한 장에 $0.0575. 상황별 프롬프트 선택은 프롬프트 대전을 참고하세요.

두 가지 시작 경로

브라우저 3단계: 모델 페이지 열기 → 프롬프트 붙여넣기, 크기 선택 → 생성 클릭, 장당 $0.036.

API 3단계: POST /v1/tasks 제출 → taskId 수신 → GET /v1/tasks/<taskId>로 조회해 success 확인 후 다운로드.

curl: 첫 이미지

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: your-unique-key-001" \
  -d '{
  "model": "krea-3/text-to-image",
  "input": {
    "prompt": "Studio product photograph of a frosted glass perfume bottle with a brushed brass cap standing on a block of travertine, hard afternoon sunlight casting a long palm-leaf shadow across a warm beige wall, crisp reflections, high-end editorial look",
    "image_size": "square_hd",
    "variant": "berry",
    "reasoning_level": "medium"
  }
}'

Krea 2 Medium Turbo로 바꾸려면 model과 input 필드만 변경하면 됩니다:

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "krea-2-medium-turbo",
  "input": {
    "prompt": "Futuristic city skyline at dusk, neon reflections on wet streets, cinematic widescreen",
    "aspect_ratio": "2.35:1",
    "creativity": "low"
  }
}'

응답에 포함된 taskId가 조회 자격 증명입니다.

Python: 제출, 폴링, 다운로드

import time, uuid, requests

BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
}

payload = {
    "model": "krea-3/text-to-image",
    "input": {
        "prompt": "Studio product photograph of a frosted glass perfume bottle with a brushed brass cap standing on a block of travertine, hard afternoon sunlight casting a long palm-leaf shadow across a warm beige wall, crisp reflections, high-end editorial look",
        "image_size": "square_hd",
        "variant": "berry",
        "reasoning_level": "medium",
    },
}

# 제출: Idempotency-Key를 사용하면 네트워크 재시도 시 작업이 중복 생성되지 않습니다
resp = requests.post(
    BASE,
    headers={**HEADERS, "Idempotency-Key": str(uuid.uuid4())},
    json=payload,
    timeout=30,
)
resp.raise_for_status()
task_id = resp.json()["taskId"]

# 폴링: queued -> handling -> archiving -> success / fail
while True:
    task = requests.get(f"{BASE}/{task_id}", headers=HEADERS, timeout=30).json()
    print(task["status"])
    if task["status"] in ("success", "fail"):
        break
    time.sleep(3)

if task["status"] == "success":
    image_url = task["output"][0]["url"]   # 임시 주소이므로 가능한 한 빨리 다운로드해 저장하세요
    img = requests.get(image_url, timeout=60)
    with open("output_image", "wb") as f:  # 확장자는 실제 반환된 포맷에 맞춰 지정하세요
        f.write(img.content)
    print("saved")

파라미터 표 (krea-3/text-to-image)

필드	필수	값	설명
prompt	예	1–5000자	화면 설명; 구체적으로 쓸수록 설명대로 따라감
image_size	아니오	square_hd / square / portrait_4_3 / portrait_16_9 / landscape_4_3 / landscape_16_9, 기본값 square_hd	크기 프리셋, 최대 1024×1024; auto 및 사용자 지정 너비/높이 지원 안 함
variant	아니오	berry / jam, 기본값 berry	berry는 품질 우선, jam은 속도 우선; 동일 가격
reasoning_level	아니오	low / medium, 기본값 medium	프롬프트 추론 확장 정도; 짧은 프롬프트에는 medium, 구체적으로 쓴 경우 low
negative_prompt	아니오	≤1024자	원하지 않는 내용; berry에만 적용
output_format	아니오	png / jpeg, 기본값 png	출력 포맷
seed	아니오	정수 0–2147483647	동일 변형 내에서 재현; berry와 jam은 서로 재현되지 않음

Krea 2 Medium Turbo의 필드는 다릅니다: prompt(필수), aspect_ratio(8가지, 기본값 1:1), creativity(raw/low/medium/high, 기본값 low), seed. 요청 본문에 표에 없는 필드가 있으면 바로 400이 발생합니다.

마주치게 될 에러 (인터페이스 원문)

한 일	반환
image_size에 auto 전달	400 invalid input: image_size: value must be one of 'square_hd', 'square', 'portrait_4_3', 'portrait_16_9', 'landscape_4_3', 'landscape_16_9'
표에 없는 필드 전달(예: num_images)	400 invalid input: <root>: additional properties 'num_images' not allowed
prompt가 비어 있음	400 invalid input: prompt: minLength: got 0, want 1
variant 오타	400 invalid input: variant: value must be one of 'berry', 'jam'
잔액 부족	402 insufficient account balance; top up and retry

파라미터 검증을 통과하지 못한 요청은 과금되지 않습니다. 같은 Idempotency-Key로 다시 제출하면 409(처리 중) 또는 422(파라미터 불일치)가 반환되며, 새 key로 다시 시도하세요.

출시 전 주의사항

• 콜백: 요청 본문 최상위에 "callback": {"url": "https://..."}를 전달하면 작업이 종료 상태에 도달할 때 서비스에 알림이 가므로 폴링을 생략할 수 있습니다.
• 즉시 이전 저장: output[0].url은 임시 주소이므로 받자마자 다운로드해 자체 스토리지에 저장하세요.
• 크기는 6가지뿐: 2.35:1 시네마 와이드나 더 많은 비율이 필요하면 Krea 2 Medium Turbo의 aspect_ratio를 사용하세요.
• seed는 변형 내에서만 재현: berry와 jam이 같은 seed를 사용하면 서로 다른 이미지가 나오므로, 시리즈 이미지를 만들 때는 variant + seed를 고정하세요.

자주 묻는 질문

짧은 프롬프트로도 이미지가 나오나요?

네. 모델이 추론·확장하므로 a lighthouse 한 문장으로도 완성된 화면이 나옵니다. 세부를 제어하고 싶다면 프롬프트를 구체적으로 쓰세요.

berry와 jam은 속도만 다른가요?

속도만 다르지 않습니다. 같은 seed에서 둘의 구도와 색조가 다르고 화질은 비슷하므로, 두 가지 안으로 각각 한 번씩 돌려보고 고르세요.

negative_prompt는 두 변형 모두에 적용되나요?

berry에만 적용되며, jam에 전달해도 효과가 없습니다.

한 번에 몇 장을 생성할 수 있나요?

한 번에 1장만 생성됩니다. 여러 장이 필요하면 작업을 여러 번 제출하거나 seed를 바꿔 다시 실행하세요.

$10으로 몇 장을 생성할 수 있나요?

Krea 3는 장당 $0.036으로 약 277장입니다. 신규 가입 시 200 크레딧을 지급합니다(1달러 = 2,000 크레딧).

다음 단계: 향수병 프롬프트로 모델 페이지에서 한 장 시험해보고, 상황별로 프롬프트 대전의 템플릿을 참고하세요.