hiapi API로 grok-imagine 이미지-투-이미지 사용하는 방법: curl, Python 그리고 실제 동작하는 요청

grok-imagine/image-to-image는 하나 이상의 참조 이미지와 텍스트 프롬프트를 받아 편집된 이미지를 반환합니다. 제품 사진의 스타일을 바꾸거나 배경을 교체하거나, 최대 세 장의 참조 이미지를 하나의 출력으로 융합할 수 있습니다. hiapi에서는 통합 작업 API를 통해 실행됩니다: 작업 생성, 폴링(또는 콜백 수신), 결과 다운로드. 이 가이드는 정확한 요청 구조를 안내하고 바로 복사해 쓸 수 있는 curl 및 Python 예제를 제공합니다.

무엇을 만들게 되나 + 사전 준비

목표: 참조 이미지 한 장과 프롬프트를 제출하고, 편집된 이미지의 URL을 받아 다운로드합니다. 먼저 폴링으로 대화형으로 처리한 다음, 콜백을 사용하는 프로덕션 버전을 사용합니다.

필요한 것은 하나뿐입니다: hiapi API 키. 대시보드에서 받으세요. sk-... 형태이며, 모든 호출에서 Authorization: Bearer 헤더에 넣습니다.

참조 이미지는 공개적으로 접근 가능한 URL이어야 합니다(모델이 서버 측에서 가져옵니다). 그러니 먼저 CDN이나 오브젝트 스토리지에 호스팅하세요.

최소 실행 예제(curl)

작업 생성:

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine/image-to-image",
    "input": {
      "prompt": "Turn this product photo into a clean studio shot on a seamless white background with soft shadows",
      "image_urls": ["https://your-cdn.com/product.jpg"]
    }
  }'

필수 필드는 두 개뿐입니다. prompt와 image_urls가 있으면 완전한 요청입니다. 응답에는 data.taskId 아래에 작업 ID가 포함됩니다:

{
  "data": {
    "taskId": "<task-id>"
  }
}

결과 폴링:

curl https://api.hiapi.ai/v1/tasks/<task-id> \
  -H "Authorization: Bearer sk-<your-key>"

작업이 실행되는 동안 data.status가 진행 상황을 보고합니다. success가 되면 이미지 URL은 data.output[0].url에 있습니다. fail이면 data.error에 오류 코드와 메시지가 있습니다.

중요한 세부 사항: 출력 URL은 서명되어 있으며 만료됩니다(페이로드에 expireAt 포함). 작업이 성공하면 즉시 파일을 다운로드해야 합니다. 원본 출력 URL을 저장하거나 핫링크하지 마세요.

curl -o result.png "<data.output[0].url>"

Python에서의 동일한 예제

import time
import requests

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

payload = {
    "model": "grok-imagine/image-to-image",
    "input": {
        "prompt": (
            "Turn this product photo into a clean studio shot "
            "on a seamless white background with soft shadows"
        ),
        "image_urls": ["https://your-cdn.com/product.jpg"],
        "aspect_ratio": "auto",
        "resolution": "1k",
        "output_format": "png",
    },
}

# 1. Create the task
resp = requests.post(API, json=payload, headers=HEADERS, timeout=60)
resp.raise_for_status()
task_id = resp.json()["data"]["taskId"]
print("task:", task_id)

# 2. Poll until it reaches a terminal state
while True:
    task = requests.get(f"{API}/{task_id}", headers=HEADERS, timeout=30).json()["data"]
    if task["status"] == "success":
        image_url = task["output"][0]["url"]
        break
    if task["status"] == "fail":
        raise RuntimeError(f"task failed: {task.get('error')}")
    time.sleep(5)

# 3. Download immediately — output URLs expire
with open("result.png", "wb") as f:
    f.write(requests.get(image_url, timeout=120).content)
print("saved result.png")

전체 입력 스키마

필드	필수	유형	설명
prompt	✅	string	무엇을 바꿀지 / 목표 외관
image_urls	✅	URL 배열	1–3장의 참조 이미지, 공개적으로 접근 가능해야 함
aspect_ratio	선택	enum	auto, 2:1, 20:9, 19.5:9, 16:9, 4:3, 3:2, 1:1, 2:3, 3:4, 9:16, 9:19.5, 9:20, 1:2
resolution	선택	enum	1k 또는 2k — 소문자
output_format	선택	enum	jpeg, png 또는 webp

이 스키마는 엄격합니다: 인식하지 못하는 필드는 400으로 거부됩니다. size, seed, n은 없습니다. 픽셀 크기를 사용하는 모델 코드(예: size: "1024x1024")를 이식 중이라면 여기서는 aspect_ratio + resolution을 사용하세요. 각 작업은 이미지 한 장을 반환합니다. 변형을 얻으려면 여러 작업을 제출하세요.

다중 참조 이미지: 최대 3장의 입력 이미지

image_urls는 최대 세 장의 참조 이미지를 받으며, 모델이 이를 융합합니다. 예를 들어 제품 이미지 한 장, 배경 판 한 장, 스타일 참조 이미지 한 장입니다. 세 장을 초과해 보내면 API가 요청을 바로 거부합니다:

invalid input: image_urls: maxItems: got 4, want 3

가장 중요한 이미지(보통 주 피사체)를 첫 번째에 두고, 프롬프트에서 각 참조 이미지가 무엇을 기여하는지 설명하세요.

자동 가로세로 비율

aspect_ratio: "auto"는 모델이 고정 프레임을 강제하지 않고 참조 이미지에서 출력 비율을 유추하게 합니다. 제품 사진과 구도를 유지하고 싶은 편집에 적합한 기본값입니다. 대상 시나리오에 명확한 요구가 있을 때만 명시적 비율을 설정하세요(예: 스토리 슬롯용 9:16, 키 비주얼 배너용 16:9).

프로덕션 환경 고려 사항

폴링 대신 콜백 사용

배치 처리나 서버 측 워크로드의 경우 폴링 루프를 건너뛰세요. 작업 생성 시 콜백을 등록하면 hiapi가 최종 결과를 엔드포인트로 POST합니다:

{
  "model": "grok-imagine/image-to-image",
  "input": {
    "prompt": "...",
    "image_urls": ["https://your-cdn.com/product.jpg"]
  },
  "callback": {
    "url": "https://your-server.com/hooks/hiapi",
    "when": "final"
  }
}

when은 "final"만 지원합니다. 작업이 success 또는 fail에 도달하면 한 번 호출을 받으며, 중간 진행 이벤트는 받지 않습니다.

경험 법칙: 대화형 도구에는 폴링(사용자가 지켜보고 있으며 5초 sleep 루프면 충분), 파이프라인에는 콜백(수십 개의 작업이 실행 중이며 작업마다 폴링기를 두고 싶지 않음). 콜백 핸들러도 출력을 즉시 다운로드해야 합니다. 받은 URL은 다른 URL과 마찬가지로 만료됩니다.

멱등성과 재시도

작업 API는 "제출"과 "결과"를 분리하므로 안전한 재시도가 간단합니다:

• create가 반환되는 즉시 taskId를 영구 저장하세요. 이후 프로세스가 충돌하면 저장된 ID를 폴링하여 복구하세요. 다시 생성하지 마세요.
• create 호출이 실패하고 taskId를 반환하지 않은 경우에만 재시도하세요(네트워크 오류, 5xx). 이미 ID를 반환한 요청을 다시 제출하면 두 번째로 별도 과금되는 작업이 생성됩니다.
• status: "fail"은 종료 상태로 간주하세요. 입력을 수정하고(또는 대체 방안으로 라우팅하고) 새 작업을 제출하세요. 실패한 작업은 다시 시작되지 않습니다.

일반적인 오류

보이는 것	의미	수정 방법
401 — permission_denied	키가 잘못되었거나 키에 이 모델 접근 권한이 없음	대시보드에서 키 확인
400 INVALID_REQUEST — missing required field "prompt" / "image_urls"	필수 입력 누락	두 필드 모두 필수
400 INVALID_REQUEST — additional properties '...' not allowed	알 수 없는 필드(예: size, seed, n)	엄격한 스키마 — 위 표의 필드만 사용
400 INVALID_REQUEST — image_urls: maxItems	참조 이미지가 3장 초과	3장으로 줄이기
404 — task not found	GET 시 taskId가 잘못되었거나 다른 계정 소속	저장된 ID 확인
폴링 중 status: "fail"	수락되었지만 생성 실패	data.error를 읽고 입력 조정 후 다시 제출

인증 실패는 401이며 오류 본문에 "code": "permission_denied"가 있습니다. 키가 존재하지만 이 모델에 대한 접근 권한이 없는 경우도 포함하므로 명시적으로 매칭할 가치가 있습니다.

다음 단계

• 모델 상세 및 온라인 체험: grok-imagine/image-to-image
• 더 높은 충실도가 필요하신가요? 품질 티어는 동일한 요청 구조를 사용합니다: grok-imagine-quality/image-to-image
• 프롬프트만으로 시작(참조 이미지 없음): grok-imagine 텍스트-투-이미지
• 두 티어의 이미지당 비용: 가격
• 전체 작업 API 참조: 문서

자주 묻는 질문

참조 이미지를 몇 장까지 전달할 수 있나요? image_urls에 최대 3장까지 가능합니다. API는 그 이상을 하드 거부합니다(maxItems: got N, want 3).

픽셀로 출력 크기를 설정할 수 있나요? 아니요. size 필드는 없습니다. aspect_ratio(14개 열거 값)로 모양을, resolution(1k 또는 2k, 소문자)으로 선명도를 제어합니다. 그 외의 것은 400을 반환합니다.

aspect_ratio: "auto"는 무엇을 하나요? 모델이 고정 프레임을 강제하지 않고 참조 이미지의 비율을 따르게 합니다. 구도를 유지해야 하는 편집에 흔히 선택됩니다.

결과 URL은 얼마나 유효한가요? 서명된 URL이며 유효 기간이 있습니다(출력 페이로드의 expireAt). 작업 성공 후 가능한 한 빨리 바이트를 다운로드하세요. 핫링크하지 마세요.

폴링을 해야 하나요, 콜백을 사용해야 하나요? 대화형 사용에는 약 5초마다 폴링하면 충분합니다. 배치 파이프라인의 경우 callback: {"url": ..., "when": "final"}을 전달하고 작업당 한 번 POST를 처리하세요. "final"이 유일하게 지원되는 트리거입니다.

한 번의 호출로 여러 변형을 얻을 수 있나요? 아니요. n 파라미터는 없습니다. 변형마다 작업을 하나씩 제출하세요. 어차피 병렬로 실행됩니다.

grok-imagine-quality/image-to-image와의 차이는 무엇인가요? 요청 구조는 동일하며 충실도가 더 높은(비용도 더 높은) 렌더링 티어입니다. 표준 티어에서 프로토타이핑한 뒤 유지할 항목을 품질 티어에서 다시 실행하세요. 이미지당 비용은 가격 페이지에서 비교하세요.