Recraft V4.1 API 사용법? 5분 만에 배색 이미지 생성 실행하기

TL;DR

• Recraft V4.1 시리즈는 파라미터가 완전히 동일한 텍스트-이미지 모델 한 쌍입니다: recraft-v4.1/text-to-image는 디테일이 더 풍부한 최종본($0.05/장), recraft-v4.1-flash/text-to-image는 빠른 시안($0.01/장, 전체 가격은 가격 페이지 참조), 차이는 model 필드 하나뿐입니다. 모델 페이지 열기에서 바로 체험할 수 있고, 신규 사용자 가입 시 200 크레딧을 증정합니다.
• 특장점은 브랜드 배색입니다: colors에 RGB 세트를 전달하면 화면이 최대한 이 색상 안에 머물도록 합니다(Playground에서는 아직 제공되지 않으며 API로 사용).
• 호출은 HiAPI /v1/tasks 인터페이스를 사용합니다: 작업을 제출해 taskId를 받고, 결과를 조회한 뒤 성공 시 output[0].url에서 다운로드합니다.

무엇을 할 수 있나

• 사진, 일러스트, 포스터 모두 생성: 사실적 제품 이미지, 플랫 벡터 일러스트, 제목이 있는 포스터까지 한 문장 설명으로 바로 생성.
• 배색 제어 가능: colors로 팔레트를, background_color로 배경색을 지정해 브랜드 자료 제작 시 VI에 맞출 수 있습니다.
• 6가지 사이즈 프리셋: square_hd(기본), square, portrait_4_3, portrait_16_9, landscape_4_3, landscape_16_9, 사용자 지정 너비/높이는 불가.
• Flash 시안 + V4.1 확정: 파라미터는 같고 model만 교체, 시안 10장 + 확정 1장에 $0.15.

아래는 V4.1의 실제 결과물입니다:

Minimalist brand poster for a specialty coffee brand, huge bold headline "NORTH BEAN" in clean sans-serif, warm terracotta and cream palette, single coffee bean illustration, generous negative space, Swiss grid layout

(한국어 의미: 미니멀 스타일 스페셜티 커피 브랜드 포스터, 거대한 볼드 산세리프 제목 "NORTH BEAN", 따뜻한 테라코타와 크림 배색, 커피콩 하나 일러스트, 넉넉한 여백, 스위스 그리드 레이아웃. 사이즈는 portrait_4_3 선택.)

recraft-v4.1/text-to-image, portrait_4_3, 본문 예시 이미지 896×1216, $0.05.

이 프롬프트로 생성하기 →

두 모델 선택 기준

	recraft-v4.1-flash/text-to-image	recraft-v4.1/text-to-image
장당	$0.01	$0.05
용도	빠른 시안, 방향 탐색	디테일이 더 풍부한 최종본
파라미터	완전 동일(prompt / image_size / colors / background_color)	동일
적합	대량 탐색, SNS 이미지, 초안 단계	납품본, 브랜드 자료

두 모델은 같은 파이프라인입니다: Flash로 10가지 방향 $0.10, 선택한 방향을 model만 교체해 V4.1 최종본 $0.05로 재실행, 한 세트 $0.15. 반대로 초안만 생성할 경우 전부 Flash로 1,000장도 $10.00에 불과합니다. 시나리오별 프롬프트 선택은 프롬프트 모음을 참고하세요.

두 가지 시작 경로

브라우저 3단계: 모델 페이지 열기 → 프롬프트 붙여넣기, 사이즈 선택 → 생성 클릭, V4.1 장당 $0.05. (colors와 background_color는 API로 사용.) 처음에는 브라우저에서 한 장 실행해 스타일이 기대에 맞는지 확인한 후 코드를 작성하는 것을 권장합니다.

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": "recraft-v4.1-flash/text-to-image",
  "input": {
    "prompt": "Flat vector illustration of a cozy reading nook with an armchair, a tall plant and a round window showing a city skyline at dusk, clean geometric shapes, gentle grain",
    "image_size": "landscape_4_3",
    "colors": [
      {"r": 28, "g": 61, "b": 90},
      {"r": 240, "g": 128, "b": 60},
      {"r": 245, "g": 222, "b": 179}
    ],
    "background_color": {"r": 250, "g": 246, "b": 238}
  }
}'

이것은 Flash 사례의 실제 파라미터입니다: 딥 블루, 오렌지, 밀색 세 가지 톤 팔레트에 미색 배경. 최종본을 생성하려면 model을 recraft-v4.1/text-to-image로 교체하고 나머지는 그대로 둡니다.

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

import time, uuid, requests

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

payload = {
    "model": "recraft-v4.1/text-to-image",
    "input": {
        "prompt": "Minimalist brand poster for a specialty coffee brand, huge bold headline \"NORTH BEAN\" in clean sans-serif, warm terracotta and cream palette, single coffee bean illustration, generous negative space, Swiss grid layout",
        "image_size": "portrait_4_3",
    },
}

resp = requests.post(
    BASE,
    headers={**HEADERS, "Idempotency-Key": str(uuid.uuid4())},
    json=payload,
    timeout=30,
)
resp.raise_for_status()
task_id = resp.json()["taskId"]

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")

파라미터 표(두 모델 동일)

필드	필수	값	설명
prompt	예	1–10000자	화면 설명
image_size	아니오	square_hd(기본) / square / portrait_4_3 / portrait_16_9 / landscape_4_3 / landscape_16_9	6가지 프리셋, 사용자 지정 너비/높이 없음
colors	아니오	RGB 객체 배열, 각 채널 0–255	팔레트 강한 유도: 화면이 최대한 해당 색상군에 머물도록; Playground에서는 아직 제공되지 않음
background_color	아니오	단일 RGB 객체	배경색; Playground에서는 아직 제공되지 않음

각 RGB 객체는 r/g/b 세 키 모두 필수, 각각 0–255, 추가 키 불가. 요청 본문에 표에 없는 필드가 있으면 즉시 400.

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

한 행동	반환
prompt 미전달	400 invalid input: prompt: missing required field "prompt"
image_size에 너비/높이 객체 전달	400 invalid input: image_size: got object, want string
colors 특정 채널에 256 전달	400 invalid input: colors.0.r: maximum: got 256, want 255
colors에서 b 키 누락	400 invalid input: colors.0.b: missing required field "b"
colors를 문자열로 전달	400 invalid input: colors: got string, want array
RGB 객체에 키 추가 전달	400 invalid input: colors.0: additional properties 'a' not allowed
잔액 부족	402 insufficient account balance; top up and retry
동일한 Idempotency-Key로 중복 제출 시 409 또는 422 반환, 새 key로 재시도.

출시 전 주의사항

• 콜백: 요청 본문 최상위에 "callback": {"url": "https://..."}를 전달하면 종료 상태를 자동으로 통지합니다.
• 즉시 이전 저장: output[0].url은 임시 주소이므로 받는 즉시 다운로드해 자체 스토리지에 저장하고, 영구 링크로 사용하지 마세요.
• 배색은 유도이지 고정이 아님: 프롬프트에 colors와 충돌하는 색을 작성하면 결과가 둘을 혼합할 수 있습니다; 색을 엄격히 맞추려면 프롬프트에 다른 색을 쓰지 마세요.
• Flash→V4.1은 model만 교체: 나머지 파라미터는 그대로 유지, 구도 아이디어를 바로 재사용.

자주 묻는 질문

두 모델의 파라미터가 같나요?

완전히 같습니다. model 필드만 교체하면 코드 변경은 없습니다.

colors 파라미터는 어디서 설정하나요?

API로만 가능합니다. Playground에서는 colors와 background_color 두 파라미터를 아직 제공하지 않습니다.

colors로 지정한 색만 사용하도록 보장되나요?

아니요. 강한 유도이며 화면이 최대한 해당 색상군에 머물도록 하지만 강제 고정은 아닙니다.

한 번에 몇 장 생성되나요?

한 번에 1장. 여러 장은 작업을 여러 번 제출하거나 대기열에 넣으세요.

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

Flash는 장당 $0.01, $10로 1,000장. 실패 시 과금되지 않습니다.

다음 단계: NORTH BEAN 프롬프트로 모델 페이지에서 한 장 생성하기, 브랜드 색을 맞출 때는 colors를 API 요청에 추가하세요; 시나리오 템플릿은 프롬프트 모음을 참고하세요.