hiapi API로 seedream-5.0-pro/image-to-image 사용하는 방법: curl, Python 및 실행 가능한 요청 예제

Seedream 5.0 Pro는 바이트댄스의 플래그십 이미지 모델로, image-to-image 엔드포인트는 하나 이상의 참조 이미지와 텍스트 지시문을 받아 편집된 결과를 반환합니다. 스타일 재현, 배경 교체, 제품 사진 정리, 다중 이미지 합성 등이 가능합니다. hiapi에서 이 모델은 통합 비동기 tasks API 위에서 동작합니다. 먼저 작업을 생성하고, 이후 폴링(또는 콜백 수신)한 뒤, 마지막으로 출력을 다운로드합니다. 이 가이드의 모든 파라미터, 열거형 값 및 오류 메시지는 게시 전에 실제 API와 대조하여 검증되었습니다.

무엇을 만들고, 무엇을 준비해야 할까요

목표: seedream-5.0-pro/image-to-image에 참조 이미지 한 장과 편집 지시문을 보내고, 편집된 이미지를 받아 로컬에 저장합니다.

두 가지를 준비해야 합니다:

1. hiapi API 키 —— 콘솔에서 발급받으세요. Authorization: Bearer sk-... 요청 헤더에 넣어야 합니다.
2. 공개적으로 접근 가능한 이미지 URL —— API가 서버 측에서 참조 이미지를 가져오므로 HTTPS로 접근 가능해야 합니다. 자체 스토리지 버킷에서 생성한 미리 서명된 URL은 문제없이 사용할 수 있지만, localhost나 비공개 경로는 안 됩니다. URL을 가져올 수 없으면 조용히 실패하는 대신 정규화된 오류가 반환됩니다.

파라미터 (검증됨)

모델 ID는 seedream-5.0-pro/image-to-image이며, GET /v1/models가 반환하는 값과 정확히 일치합니다. 네 가지 입력 필드는 모두 필수입니다:

필드	타입	필수	값 / 설명
prompt	string	예	편집 지시문.
image_urls	문자열 배열	예	공개적으로 접근 가능한 이미지 URL 1–10개. 이미지가 한 장이어도 항상 배열이어야 합니다.
aspect_ratio	string	예	match_input_image, 1:1, 4:3, 3:4, 16:9, 9:16, 3:2, 2:3, 21:9
resolution	string	예	1K 또는 2K

실수하기 쉬운 두 가지 지점:

• 스키마는 엄격합니다. 알 수 없는 필드는 거부됩니다. n, size, seed를 보내면 400과 함께 additional properties ... not allowed가 반환됩니다. hiapi에서 각 모델의 입력 스키마는 서로 다르므로(어떤 모델은 size, 어떤 모델은 aspect_ratio 사용) 모델 계열 간에 필드를 복사해서는 안 됩니다.
• 여기서 resolution은 1K/2K만 지원합니다. 다른 seedream 엔드포인트는 다른 해상도 집합을 받으므로, 당연하게 여기지 말고 엔드포인트별로 확인하는 것이 좋습니다.

최소 실행 예제: curl

작업 생성:

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5.0-pro/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-bucket.example.com/product.jpg"],
      "aspect_ratio": "match_input_image",
      "resolution": "2K"
    }
  }'

생성에 성공하면 작업 ID가 data.taskId에 반환됩니다(응답은 간소화됨):

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

작업이 종료 상태에 도달할 때까지 폴링합니다:

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

data.status가 최종적으로 success가 되면 이미지 URL은 data.output[0].url에 있습니다. 또는 fail이 되며, 상세 정보는 data.error.code와 data.error.message에 있습니다.

전체 Python 스크립트: 생성, 폴링, 다운로드

표준 라이브러리만 사용하므로 아무것도 설치할 필요가 없습니다:

import json
import time
import urllib.request

API = "https://api.hiapi.ai/v1/tasks"
KEY = "sk-YOUR_KEY"


def call(url, payload=None):
    req = urllib.request.Request(
        url,
        data=json.dumps(payload).encode() if payload is not None else None,
        headers={
            "Authorization": f"Bearer {KEY}",
            "Content-Type": "application/json",
        },
        method="POST" if payload is not None else "GET",
    )
    with urllib.request.urlopen(req) as resp:
        return json.load(resp)


# 1. Create the edit task
create = call(API, {
    "model": "seedream-5.0-pro/image-to-image",
    "input": {
        "prompt": "Restyle this living room as a Scandinavian interior, keep the layout and window positions",
        "image_urls": ["https://your-bucket.example.com/room.jpg"],
        "aspect_ratio": "match_input_image",
        "resolution": "2K",
    },
})
task_id = create["data"]["taskId"]
print("task created:", task_id)

# 2. Poll until terminal state
while True:
    task = call(f"{API}/{task_id}")["data"]
    if task["status"] == "success":
        break
    if task["status"] == "fail":
        err = task.get("error") or {}
        raise RuntimeError(f"task failed: {err.get('code')} {err.get('message')}")
    time.sleep(5)

# 3. Download immediately -- output URLs expire
image_url = task["output"][0]["url"]
urllib.request.urlretrieve(image_url, "edited.png")
print("saved edited.png")

프로덕션 환경 유의사항

서버에서는 폴링보다 콜백을 우선 사용하세요. 작업 생성 시 최상위 callback 객체를 추가하면, hiapi가 종료 상태에 진입할 때 엔드포인트로 한 번 POST합니다:

{
  "model": "seedream-5.0-pro/image-to-image",
  "input": { "...": "..." },
  "callback": { "url": "https://your-server.example.com/hiapi-hook", "when": "final" }
}

핸들러에서는 콜백을 신호로 취급하고 사실의 출처로 삼지 마세요. 콜백에서 작업 ID를 꺼낸 뒤 직접 GET /v1/tasks/<id>를 다시 요청하고, 그 결과에 따라 조치하세요. 스크립트, notebook, 일회성 작업에는 폴링이 여전히 적합합니다. 간격은 약 5초로 유지하세요.

재시도를 멱등하게 만드세요. 작업 생성 시 자신의 원본 이미지 → taskId 매핑을 저장하세요. 프로세스가 폴링 도중 중단되면 편집을 다시 제출하지 말고 저장된 taskId에 다시 연결해야 합니다. 다시 제출하면 두 번째 과금 작업이 생성됩니다.

출력을 즉시 다운로드하세요. data.output[0].url의 URL은 시간 제한(만료 시간 포함)이 있습니다. 바이트를 다운로드하여 자신의 스토리지 버킷에 저장하세요. 사용자 대상 콘텐츠에서 작업 출력 URL을 직접 핫링크하지 마세요.

실제로 마주치게 될 오류:

• 401과 permission_denied —— API 키가 없거나 형식이 잘못되었습니다. 요청 헤더가 정확히 Authorization: Bearer sk-...인지 확인하세요.
• 400과 INVALID_REQUEST —— 입력 스키마 위반입니다. 오류 메시지는 매우 구체적입니다. 예: resolution: value must be one of '1K', '2K' 또는 image_urls: maxItems: got 11, want 10.
• image_urls must be an array —— 문자열을 그대로 전달한 경우입니다. 이미지가 한 장이어도 목록으로 감싸야 합니다.

다음 단계

• 모델 페이지: seedream-5.0-pro/image-to-image —— 기능과 현재 상태.
• 이미지당 가격은 가격 페이지에 나와 있습니다.
• 고동시성 파이프라인을 위한 더 저렴한 편집 옵션: seedream-5.0-lite image-to-image 사용 방법.
• 모델 간 선택: 2026년 최고의 image-to-image API에서 세 모델에 대해 동일한 편집 작업을 비교했습니다.
• 전체 API 참조: hiapi 문서.

자주 묻는 질문

참조 이미지는 최대 몇 장까지 보낼 수 있나요? image_urls에 최대 10개의 URL을 넣을 수 있습니다. 이 제한은 서버 측에서 강제되며, 11장을 보내면 maxItems: got 11, want 10이 반환됩니다.

출력이 입력 이미지의 종횡비를 유지할 수 있나요? 예 —— aspect_ratio를 match_input_image로 설정하세요. 편집과 스타일 재현에서는 보통 이것을 원하게 됩니다. 의도적으로 구도를 다시 잡을 때만 16:9와 같은 명시적 비율을 선택하세요.

seedream-5.0-pro image-to-image는 4K를 지원하나요? 아니요. 이 엔드포인트는 1K와 2K만 허용합니다. 다른 값을 요청하면 허용되는 값 목록과 함께 400이 반환됩니다.

이미지 URL은 공개되어야 하나요? hiapi 서버가 HTTPS를 통해 가져올 수 있어야 합니다. 미리 서명된 URL(S3, R2, GCS)은 잘 동작하며 스토리지 버킷 자체는 비공개로 유지할 수 있습니다.

seedream-5.0-pro image-to-image의 이미지당 비용은 얼마인가요? 가격은 성공적으로 생성된 이미지 기준으로 과금되며 해상도에 따라 달라집니다. 현재 요금은 실시간 가격 페이지에서 확인하세요.

seedream-5.0-lite image-to-image와 어떻게 다른가요? Pro는 더 어렵고 고충실도 편집을 위한 플래그십 계층이고, lite는 더 빠르고 저렴한 대량 처리 옵션입니다. 요청 구조가 비슷하므로 가장 명확한 판단 방법은 동일한 편집 작업을 각각 실행해 보는 것입니다. lite 가이드부터 시작하여 자신의 참조 이미지로 결과를 비교해 보세요.