튜토리얼

krea-2-medium-turbo 텍스트 투 이미지 API 사용 방법(curl + Python)

Oct 21, 2026

krea-2-medium-turbo는 Krea가 hiapi에서 제공하는 빠르고 저렴한 텍스트 투 이미지 티어입니다. 프롬프트 하나를 보내고 가로세로 비율을 선택하기만 하면 비동기 작업 API를 통해 렌더링된 이미지 한 장을 받을 수 있습니다. 이 가이드에서는 /v1/tasks를 대상으로 바로 복사해 붙여넣을 수 있는 curl 및 Python 요청 예시와 정확한 입력 스키마, 그리고 제가 2026-10-21에 직접 측정한 소요 시간과 오류 동작을 제공합니다. 그중 한 가지 결과는 문서 설명과 상충합니다.

사전 준비 사항

hiapi API 키(sk-...) 하나. API Keys 콘솔에서 생성합니다. 모든 요청은 Authorization: Bearer sk-<your-key>로 인증됩니다. 이것이 유일한 전제 조건입니다. 모델은 서버에서 실행되므로 HTTP 클라이언트 외에는 아무것도 설치할 필요가 없습니다.

입력 스키마

krea-2-medium-turbo는 다섯 개의 필드를 받습니다. 이 중 prompt와 model만 필수입니다:

필드	필수	타입	기본값	설명
`model`	예	string	—	반드시 정확히 `krea-2-medium-turbo`여야 합니다.
`prompt`	예	string	—	1–5000자.
`aspect_ratio`	아니오	enum	`1:1`	`1:1`, `4:3`, `3:2`, `16:9`, `2.35:1`, `4:5`, `2:3`, `9:16` 중 하나.
`creativity`	아니오	enum	`low`	`raw`(가장 문자적) → `low` → `medium` → `high`(가장 창의적).
`seed`	아니오	integer	—	선택 사항. 이 값에 의존하기 전에 아래의 seed 주의 사항을 먼저 읽으세요.

input 객체는 엄격합니다(additionalProperties: false). 이 표에 없는 필드는 생성이 시작되기 전에 거부됩니다. n / num_images도 없고, resolution이나 size도 없으며, 네거티브 프롬프트 필드도 없습니다. 요청 한 번에 정확히 이미지 한 장을 반환하며, 출력 크기는 전적으로 aspect_ratio에 의해 결정됩니다. hiapi에서 resolution(Seedream, Qwen-Image)이나 size를 받는 다른 이미지 API를 사용해 본 적이 있다면 여기서는 해당 필드를 제거하세요. 그러지 않으면 400이 반환됩니다.

최소 동작 요청(curl)

작업 생성은 즉시 taskId를 반환하며, 이미지는 백그라운드에서 렌더링됩니다.

curl -s -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer sk-<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "krea-2-medium-turbo",
    "input": {
      "prompt": "A lighthouse on a rocky coast at golden hour, cinematic wide shot",
      "aspect_ratio": "2.35:1",
      "creativity": "medium",
      "seed": 42
    }
  }'

응답:

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

그런 다음 id로 작업을 폴링하여 종료 상태에 도달할 때까지 기다립니다:

curl -s "https://api.hiapi.ai/v1/tasks/tk-hiapi-01M5E4J4FQVJNSDKQ29BRSMD0A" \
  -H "Authorization: Bearer sk-<your-key>"

완료된 작업은 다음과 같습니다(명확성을 위해 일부 필드는 생략됨):

{
  "code": 200,
  "data": {
    "taskId": "tk-hiapi-01M5E4J4FQVJNSDKQ29BRSMD0A",
    "model": "krea-2-medium-turbo",
    "status": "success",
    "storage": "temp",
    "created": 1792549655,
    "completed": 1792549681,
    "output": [
      {
        "type": "image",
        "url": "https://temp.hiapi.ai/xxxxxxxx/01M5E4J4FQVJNSDKQ29BRSMD0A-0.png",
        "artifactId": "280334",
        "expireAt": 1793154481
      }
    ]
  },
  "message": "success"
}

이미지는 data.output[0].url에 있습니다.

Python에서의 동일한 흐름

import time
import requests

API = "https://api.hiapi.ai/v1/tasks"
HEADERS = {
    "Authorization": "Bearer sk-<your-key>",
    "Content-Type": "application/json",
}

def generate(prompt, aspect_ratio="1:1", creativity="low", seed=None):
    body = {
        "model": "krea-2-medium-turbo",
        "input": {"prompt": prompt, "aspect_ratio": aspect_ratio, "creativity": creativity},
    }
    if seed is not None:
        body["input"]["seed"] = seed

    created = requests.post(API, headers=HEADERS, json=body, timeout=30)
    created.raise_for_status()
    task_id = created.json()["data"]["taskId"]

    # 작업이 종료 상태에 도달할 때까지 폴링합니다.
    while True:
        data = requests.get(f"{API}/{task_id}", headers=HEADERS, timeout=30).json()["data"]
        status = data["status"]
        if status == "success":
            return data["output"][0]["url"]
        if status == "fail":                 # 참고: 여전히 HTTP 200입니다. 아래 참조
            raise RuntimeError(f"generation failed: {data}")
        time.sleep(3)

url = generate(
    "A lighthouse on a rocky coast at golden hour, cinematic wide shot",
    aspect_ratio="2.35:1",
    creativity="medium",
)
print(url)

프로덕션 환경 주의 사항

폴링 또는 콜백 사용. 위의 루프는 3초마다 폴링하며, 동시성이 낮은 환경에서는 문제가 없습니다. 프로덕션 환경에서는 생성 요청 시 callback.url을 함께 보내고 when: "final"을 설정하여 폴링 대신 hiapi가 완료된 작업을 여러분에게 POST하도록 할 수 있습니다. 콜백 규약은 task API 문서를 참조하세요.
생성 실패도 HTTP 200을 반환합니다. 폴링 엔드포인트의 HTTP 상태 코드는 요청의 성공 여부를 나타내며, 이미지의 성공 여부를 나타내지 않습니다. 렌더링 실패는 200과 data.status: "fail"로 반환됩니다. HTTP 상태 코드가 아니라 data.status를 기준으로 분기하세요. 그렇지 않으면 실패를 성공으로 처리하게 됩니다.
출력 URL은 임시입니다. 결과는 temp.hiapi.ai의 "storage": "temp"에 저장되며 expireAt 타임스탬프가 붙어 약 7일 후 만료됩니다(제 실행에서는 604,800초). 작업이 완료되면 즉시 바이트를 다운로드하여 다시 호스팅하세요(자체 버킷/CDN). 프로덕션 페이지에서 temp.hiapi.ai URL을 직접 핫링크하지 마세요.
가격은 이미지 한 장당 단일 고정 요금이며 가로세로 비율이나 창의성 수준과 무관합니다. 해상도 티어를 고려할 필요가 없습니다. 하드코딩하지 말고 가격 페이지에서 현재 수치를 확인하세요.

제가 실제로 테스트한 내용(2026-10-21)

아래 내용은 모두 문서가 아닌 실제 호출에서 나온 것입니다:

소요 시간과 해상도. 2.35:1 요청은 약 26초 만에 완료되었으며(created → completed 차이), 반환된 PNG는 1568 × 672 px였습니다. 따라서 2.35:1은 실제로 시네마스코프 와이드스크린 크롭이며, 정사각형에 가깝지 않습니다. 작업은 렌더링 후 파일을 임시 저장소로 이동하는 동안 중간 상태 handling → archiving → success를 거칩니다.
열거형 검증은 서버 측에서 강제됩니다. "aspect_ratio": "21:9"(그럴듯해 보이지만 지원되지 않는 값)를 보내면 즉시 400이 반환됩니다: invalid input: aspect_ratio: value must be one of '1:1', '4:3', '3:2', '16:9', '2.35:1', '4:5', '2:3', '9:16'. 오류 메시지가 필드를 명시하고 유효한 값을 나열하므로 프로그래밍 방식으로 처리하기 쉽습니다.
알 수 없는 필드는 무시되지 않고 400을 반환합니다. "resolution": "2K"는 invalid input: <root>: additional properties 'resolution' not allowed를 반환하며, "n": 2는 n에 대해 동일한 오류를 반환합니다. 이것이 additionalProperties: false 규칙이 작동하는 방식입니다. 다른 모델에서 요청 본문을 복사해 오면 불필요한 필드 때문에 호출 전체가 차단됩니다.
제 테스트에서 seed는 동일한 이미지를 재현하지 못했습니다. 동일한 프롬프트, seed: 42, aspect_ratio: 2.35:1, creativity: medium으로 연속 두 번 보냈습니다. 두 번 모두 유효한 1568 × 672 이미지를 반환했지만 명백히 다른 장면이었고(하나는 흰색 탑, 다른 하나는 빨간색과 흰색 줄무늬 탑), 파일 크기도 달랐으며(1.30 MB 대 1.51 MB) 해시도 달랐습니다. 이 필드는 허용되며 문서에서 재현 가능하다고 설명되지만, 정확한 픽셀 재현은 보장이 아닌 최선의 노력으로 간주하세요. 특정 장면이 필요하다면 seed로 다시 요청하지 말고 얻은 결과를 저장하세요.

FAQ

어떤 가로세로 비율을 요청할 수 있나요? 여덟 가지입니다: 1:1(기본값), 4:3, 3:2, 16:9, 2.35:1, 4:5, 2:3, 9:16. 다른 값은 400을 반환합니다.

한 번의 호출로 여러 이미지를 생성할 수 있나요? 아니요. n 필드가 없고 스키마가 알 수 없는 속성을 거부하므로 요청당 정확히 이미지 한 장이 생성됩니다. 일괄 생성을 하려면 요청을 반복해서 보내세요(선택적으로 다른 seed 사용).

creativity는 어떤 역할을 하나요? 모델이 프롬프트를 얼마나 문자적으로 따르는지 제어합니다: raw는 표현에 가장 충실하고, high는 가장 많은 해석의 자유를 가지며, low(기본값)와 medium은 그 사이입니다.

krea-2-medium-turbo는 이미지 투 이미지나 편집을 지원하나요? 아니요. 텍스트 투 이미지만 지원합니다. 스키마에 image_urls / 입력 이미지 필드가 없습니다. 기존 이미지를 변환해야 한다면 hiapi의 전용 편집/이미지 투 이미지 모델을 사용하세요.

출력 URL은 얼마나 유효한가요? 임시 저장소에서 제공되며 만료됩니다(제 테스트에서는 약 7일 후). 작업이 완료되면 즉시 이미지를 다운로드하여 다시 호스팅하세요.

핵심 요점

krea-2-medium-turbo는 텍스트 투 이미지만 지원합니다. prompt와 model은 필수이며, aspect_ratio, creativity, seed는 선택 사항입니다.
input 객체는 엄격합니다(additionalProperties: false). resolution, size, n은 모두 400을 반환하며, 호출당 정확히 이미지 한 장을 반환합니다.
aspect_ratio 2.35:1은 1568x672 px로 렌더링되며 약 26초가 걸립니다. 출력 URL은 temp.hiapi.ai에 있으며 약 7일 후 만료됩니다.
렌더링 실패도 HTTP 200과 data.status 'fail'을 반환합니다. HTTP 상태 코드가 아니라 상태 필드를 기준으로 분기하세요.
테스트에서 동일한 프롬프트와 seed가 서로 다른 이미지를 생성했습니다. 따라서 정확한 재현을 위해 seed에 의존하지 말고 원하는 결과를 저장하세요.