HiAPI
Ko
블로그

튜토리얼

hiapi API로 flux-2/image-to-image 사용하는 방법: curl, Python 및 사용 가능한 요청 예제

통합 /v1/tasks 인터페이스로 다중 참조 이미지 편집 — schema, 코드 및 프로덕션 실무 설명

Jul 11, 2026
hiapi API로 flux-2/image-to-image 사용하는 방법: curl, Python 및 사용 가능한 요청 예제

요약

  • 무엇인가: hiapi에서 flux-2/image-to-image API를 호출하는 사용 가능한 방안 — 작업 생성, 상태 폴링, 결과 다운로드.
  • 엔드포인트: POST https://api.hiapi.ai/v1/tasks를 사용하고 "model": "flux-2/image-to-image"를 지정한 다음, 작업이 최종 상태에 도달할 때까지 GET /v1/tasks/<taskId>를 호출합니다.
  • 필수 입력 필드(네 가지 모두): prompt, image_urls(1–8개의 공개 URL — 이것이 다중 참조 이미지 기능입니다), aspect_ratio 및 resolution(1K 또는 2K).
  • schema는 엄격합니다. strength 또는 fidelity 같은 필드는 존재하지 않으며 400으로 거부됩니다. 충실도는 참조 이미지, 프롬프트 및 resolution으로 제어됩니다 — 별도의 조절 장치로 제어하는 것이 아닙니다.

구축할 내용과 준비할 것

목표: flux-2에 하나 이상의 참조 이미지와 텍스트 프롬프트를 보내고, 다운로드 가능한 편집/재생성된 이미지를 받아오기 — curl 또는 Python으로, SDK 없이.

사전 조건:

  1. hiapi API 키 — hiapi 콘솔에서 생성합니다. 키는 sk-... 형태이며 Authorization: Bearer 요청 헤더에 넣습니다.
  2. 참조 이미지로 사용할 공개적으로 접근 가능한 이미지 URL이 최소 하나 필요합니다. API가 서버 측에서 image_urls를 가져오므로 localhost 링크나 프라이빗 버킷 URL은 사용할 수 없습니다 — 공개 버킷, CDN 또는 미리 서명된 URL을 사용하세요.
  3. curl, 또는 Python 3.8+ 및 requests(pip install requests).

요청 schema

flux-2/image-to-image는 hiapi의 통합 작업 인터페이스에서 실행됩니다. input 객체는 정확히 다음 필드만 받습니다:

필드 타입 필수 설명
prompt string 예 수정하거나 생성할 내용. 최소 3자.
image_urls string[] 예 1–8개의 공개 이미지 URL. 한 장 이상 = 다중 참조 이미지: flux-2가 모든 참조 이미지 사이에서 정체성, 제품 또는 스타일 단서를 융합합니다.
aspect_ratio string 예 1:1, 4:3, 3:4, 16:9, 9:16, 3:2, 2:3 또는 auto(참조 이미지 따름) 중 하나.
resolution string 예 1K 또는 2K.

다른 필드는 모두 거부됩니다. 예를 들어 strength 또는 fidelity 필드를 보내면 다음이 반환됩니다:

{
  "code": 400,
  "error_code": "INVALID_REQUEST",
  "message": "invalid input: <root>: additional properties 'fidelity', 'strength' not allowed"
}

이 점은 명심할 가치가 있습니다: flux-2의 이미지-투-이미지 모드에는 디노이즈 강도 조절 장치가 없습니다. 출력이 참조 이미지에 얼마나 충실한지("고충실도" 편집 vs. 느슨한 재생성)는 프롬프트를 어떻게 작성하느냐에 달려 있습니다 — 예를 들어 "제품과 그 라벨 및 비율을 참조 이미지와 완전히 동일하게 유지하고; 배경만 교체" — 그리고 디테일이 중요한 작업에는 resolution: "2K"를 사용하세요.

최소 동작 예제: curl

1단계 — 작업 생성:

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-2/image-to-image",
    "input": {
      "prompt": "Place this product on a white marble countertop with soft morning light, keep the product itself unchanged",
      "image_urls": ["https://your-cdn.example.com/product.jpg"],
      "aspect_ratio": "1:1",
      "resolution": "2K"
    }
  }'

생성에 성공하면 data.taskId에 작업 ID가 반환됩니다.

2단계 — 완료될 때까지 폴링:

curl -s https://api.hiapi.ai/v1/tasks/TASK_ID \
  -H "Authorization: Bearer sk-YOUR_KEY"

data.status가 최종 상태가 아닌 한 몇 초마다 계속 폴링하세요. "status": "success"이면 이미지 URL은 data.output[0].url에 있습니다.

3단계 — 결과를 즉시 다운로드:

curl -s -o result.jpg "OUTPUT_URL"

출력 URL에는 expireAt 타임스탬프가 있습니다 — 임시입니다. 작업이 성공하면 즉시 바이트를 다운로드하거나(또는 자체 스토리지에 복사) 하세요; 프로덕션 환경에서 작업 출력을 직접 핫링크하지 마세요.

최소 동작 예제: Python

requests만 사용하는 완전한 스크립트 — 생성, 폴링, 다운로드:

import time
import requests

API_KEY = "sk-YOUR_KEY"
BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

def create_task() -> str:
    resp = requests.post(BASE, headers=HEADERS, json={
        "model": "flux-2/image-to-image",
        "input": {
            "prompt": ("Combine the person from the first image with the jacket "
                       "from the second image, studio lighting, neutral backdrop"),
            "image_urls": [
                "https://your-cdn.example.com/person.jpg",
                "https://your-cdn.example.com/jacket.jpg",
            ],
            "aspect_ratio": "3:4",
            "resolution": "2K",
        },
    }, timeout=30)
    body = resp.json()
    task_id = (body.get("data") or {}).get("taskId")
    if not task_id:
        raise RuntimeError(f"create failed: {body}")
    return task_id

def wait_task(task_id: str, timeout_s: int = 600, poll_s: int = 5) -> dict:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        task = requests.get(f"{BASE}/{task_id}", headers=HEADERS,
                            timeout=30).json().get("data") or {}
        status = task.get("status")
        if status == "success":
            return task
        if status == "fail":
            err = task.get("error") or {}
            raise RuntimeError(f"task failed: {err.get('code')} {err.get('message')}")
        time.sleep(poll_s)
    raise TimeoutError(f"task {task_id} still running after {timeout_s}s")

task_id = create_task()
print("task:", task_id)
task = wait_task(task_id)
url = task["output"][0]["url"]          # 임시 URL — 즉시 저장하세요
img = requests.get(url, timeout=120).content
with open("result.jpg", "wb") as f:
    f.write(img)
print("saved result.jpg,", len(img), "bytes")

여기서는 두 장의 이미지를 image_urls에 사용했습니다 — 이것이 다중 참조 이미지의 실제 사용법입니다. 최대 8개의 참조 이미지를 받습니다; 모델은 이들 사이에서 조합합니다(인물 + 의상, 제품 + 배경 스타일, 캐릭터 + 포즈 참조 등).

프로덕션 실무 설명

폴링 대신 콜백을 사용하세요. 스크립트를 넘어서는 모든 상황에서는 작업 생성 시 콜백을 등록하여 hiapi가 최종 상태 결과를 서비스로 푸시하게 하세요:

{
  "model": "flux-2/image-to-image",
  "input": { "...": "..." },
  "callback": { "url": "https://your-app.example.com/hooks/hiapi", "when": "final" }
}

"when": "final"을 사용하면 작업이 최종 상태에 도달할 때 POST를 한 번만 받습니다. 경험칙: 폴링은 CLI, 배치 처리 및 수명이 짧은 모든 시나리오에 적합합니다; 콜백은 사용자 대면 애플리케이션에 더 적합합니다. 이미지마다 워커가 폴링 루프를 점유하는 방식은 확장되지 않기 때문입니다. 공개 콜백 엔드포인트를 노출할 수 없다면 폴링하세요 — 다만 간격을 5초 이상으로 백오프하세요.

재시도를 안전하게 만드세요. 작업 생성을 그 본연의 부작용으로 취급하세요: 결과에 따라 행동하기 전에 반환된 taskId를 자체 작업 레코드에 저장하고; 재시도 시에는 무작정 새 작업을 생성하는 대신 저장된 작업의 상태를 다시 확인하세요(성공한 생성은 매번 별도로 과금됩니다). 작업 러너가 두 번 트리거될 수 있다면 자체 작업 ID를 기준으로 먼저 중복 제거하세요.

실제로 마주치게 될 오류를 처리하세요:

  • 401 permission_denied — 키가 잘못되었거나 키에 해당 모델을 사용할 권한이 없습니다. 응답 본문은 다음과 같습니다:

    {"error": {"code": "permission_denied",
           "message": "This API key cannot use the selected model. ...",
           "type": "hiapi_error"}}

    콘솔에서 키를 확인하세요; 저희 유효하지 않은 API 키 점검 목록에서 일반적인 원인을 다룹니다.

  • 400 INVALID_REQUEST — schema 위반입니다. message는 모든 위반 필드(필수 필드 누락, 잘못된 열거 값, 알 수 없는 추가 필드)를 한 번에 나열하므로, 재시도할 때마다 필드 하나씩만 고치지 말고 전체를 읽으세요.

  • 작업 status: "fail" — 작업이 수락되었지만 생성에 실패했습니다; 오류는 data.error에 있습니다. 생성 시점이 아니라 폴링/콜백 경로에서 처리하세요.

  • 출력 URL 만료 — 성공 후 몇 분 뒤 다운로드가 4xx를 반환하면 너무 오래 기다린 것입니다. expireAt을 다시 확인하고 항상 즉시 다운로드하세요.

관련 읽기

FAQ

flux-2 이미지-투-이미지에 참조 이미지를 몇 장 전달할 수 있나요? 1~8장이며, image_urls에 공개 URL로 넣습니다. 8장을 초과하면 검증이 실패합니다(maxItems: got N, want 8).

strength 또는 fidelity 매개변수가 있나요? 없습니다. 입력 schema는 prompt, image_urls, aspect_ratio, resolution만 받으며; 알 수 없는 필드는 400으로 거부됩니다. 프롬프트 문구로 충실도를 제어하고(무엇을 반드시 변경하지 않아야 하는지 명확히 명시), 디테일이 중요할 때는 2K를 사용하세요.

어떤 해상도와 화면 비율이 지원되나요? resolution은 1K 또는 2K입니다. aspect_ratio는 1:1, 4:3, 3:4, 16:9, 9:16, 3:2, 2:3 또는 auto 중 하나입니다 — auto는 참조 이미지를 따르며, 편집 시 보통 원하는 옵션입니다.

URL 대신 base64 이미지를 보낼 수 있나요? 아니요 — image_urls는 URL을 받으며, API가 가져올 수 있도록 공개적으로 접근 가능해야 합니다. 먼저 버킷이나 CDN에 업로드한 뒤 생성된 URL을 전달하세요(미리 서명된 URL은 사용 가능).

flux-2 이미지-투-이미지는 이미지당 얼마인가요? 가격은 해상도에 따라 다릅니다 — 현재 이미지당 요율은 flux-2/image-to-image 모델 페이지와 가격 페이지를 확인하세요.

생성된 이미지 URL은 얼마나 유효한가요? 출력 URL은 임시이며 expireAt 필드를 포함합니다. 작업 성공 후에는 이미지 바이트를 즉시 다운로드하여 직접 저장해야 합니다.

flux-2/image-to-image와 flux-2/text-to-image의 차이는 무엇인가요? 동일 모델 시리즈의 다른 모드입니다: 텍스트-투-이미지는 프롬프트만으로 생성하는 반면, 이미지-투-이미지는 1–8장의 참조 이미지를 필요로 하며 이를 기반으로 편집 또는 조합합니다. 입력 schema가 다르므로 요청 본문을 서로 교환할 수 없습니다.

태그이미지 API이미지 투 이미지튜토리얼

관련 글

모든 아티클 보기 →

영구 AI 아티팩트로 빌드 시작하기

API 키를 받아 태스크 기반의 하나의 API로 이미지, 비디오, 오디오 모델을 호출하세요.

API 문서 보기