HiAPI API로 seedream-5.0-lite/text-to-image를 호출하는 방법: curl 및 Python 가이드

이 통합이 실제로 하는 일

HiAPI에서 텍스트-이미지 호출을 시작하는 것은 당신의 코드와 비동기 작업 큐 사이의 짧은 대화입니다. 원하는 이미지를 설명하는 요청을 보내면, 플랫폼이 요청을 검증하고 작업을 수락한 뒤 식별자를 반환합니다. 이미지는 첫 응답에 포함되지 않습니다—이후에 생성됩니다. 그다음 코드가 작업이 완료를 보고할 때까지 모니터링하고, 마지막으로 작업이 노출한 URL에서 이미지를 다운로드합니다.

이 형태가 중요한 이유는 통합 작성 방식을 결정하기 때문입니다. 세 가지 구분되는 순간이 있습니다: 제출, 폴링, 가져오기. 각각 고유한 실패 모드가 있습니다. 제출은 페이로드 형식이 잘못되었거나 모델 경로가 유효하지 않을 때 실패합니다. 폴링은 루프를 잘못 작성했을 때 실패합니다—너무 빠르거나, 너무 짧거나, "아직 실행 중"과 "완료됨"을 구분하지 못할 때입니다. 가져오기는 출력 URL을 영구 주소로 취급하거나 바이트를 디스크에 쓰는 것을 잊었을 때 실패합니다.

내부적으로 seedream-5.0-lite/text-to-image는 HiAPI 플랫폼의 범용 텍스트-이미지 모델입니다. 정확한 모델 식별자로 호출합니다. 보내는 매개변수는 이런 호출의 일반적인 매개변수입니다: 모델 이름, 프롬프트, 그리고 엔드포인트 문서에 명시된 출력 크기나 수량 제어 매개변수. 특별한 SDK는 필요 없으며, 일반 HTTPS 클라이언트로 충분합니다.

이 실습을 마치면 curl로 재현할 수 있는 요청, 그 주변의 Python 함수, 렌더링된 텍스트를 선명하고 읽기 쉽게 만드는 프롬프트 작성 요령, 그리고 실제로 종료되는 폴링 루프를 갖게 됩니다. 모든 것이 동일한 HiAPI 엔드포인트를 통해 실행되므로, 한 번 호출이 성공하면 나머지는 매개변수 조정입니다.

curl로 요청 구성하기

명령줄에서 시작하세요. 실행 가능한 curl 호출이 페이로드의 기준입니다—한 번 성공하면 다른 모든 언어는 번역 연습에 불과합니다.

첫 호출 전에 두 가지가 필요합니다: HiAPI API 키와 API의 기본 URL. 키는 Authorization 헤더에 bearer 토큰으로 들어갑니다. 가능하면 셸 기록에 남지 않게 하세요; 환경 변수가 가장 간단한 습관입니다.

export HIAPI_API_KEY="your_api_key_here"

요청 자체는 JSON 본문이 있는 POST입니다. 모델 식별자는 호출할 경로 세그먼트이고, 프롬프트는 이미지를 설명합니다:

curl -sS -X POST "$HIAPI_BASE_URL" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5.0-lite/text-to-image",
    "prompt": "A minimalist poster for a coffee shop called North Roast, warm cream background, bold dark lettering"
  }'

HIAPI_BASE_URL을 플랫폼 문서에 표시된 텍스트-이미지 제출 엔드포인트로 설정하세요; 경로는 제품 인터페이스에 따라 다르므로 추측하지 말고 복사하세요.

더 많은 코드를 작성하기 전에 응답을 읽으세요. 성공적인 제출은 작업 식별자와 상태 필드가 포함된 JSON 객체를 반환합니다. 상태는 일반적으로 작업이 대기 중이거나 처리 중임을 나타냅니다—아직 완료되지 않았습니다. 이는 예상된 동작입니다. 반환된 필드 이름을 정확히 기록하세요; 다음 두 섹션에서 참조하게 됩니다.

curl 수준의 두 가지 오류가 대부분의 첫 실패를 만듭니다. 첫째는 키 누락 또는 잘못된 범위입니다: 응답은 모델 오류가 아닌 인증 오류입니다. 둘째는 본문 형식 오류입니다—프롬프트 내 이스케이프되지 않은 따옴표, 끝 쉼표, JSON이 큰따옴표를 요구하는 곳에 작은따옴표 사용. 플랫폼이 페이로드를 거부하면 jq로 예쁘게 출력해 별도로 검증한 후 모델을 탓하세요.

제출이 식별자를 반환하면 유효한 요청이 있습니다. 그 이후의 모든 것은 기다림과 가져오기입니다.

Python으로 이식하기

Python 버전은 단일 프롬프트를 하드코딩한 스크립트가 아니라 작고 재사용 가능한 함수여야 합니다. requests(또는 선호한다면 httpx)를 사용하세요; 호출 자체에는 특별한 클라이언트가 필요 없습니다.

import os
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = os.environ["HIAPI_BASE_URL"]

HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

def submit_image(prompt: str, **params) -> dict:
    payload = {
        "model": "seedream-5.0-lite/text-to-image",
        "prompt": prompt,
        **params,
    }
    response = requests.post(BASE_URL, headers=HEADERS, json=payload, timeout=30)
    response.raise_for_status()
    return response.json()

여기에는 세 가지 의도된 선택이 있습니다. 키와 기본 URL은 환경에서 가져오므로 함수가 안전하게 제출할 수 있습니다. **params 만능 매개변수를 사용하면 함수를 편집하지 않고도 출력 크기나 기타 문서화된 옵션을 전달할 수 있습니다. 그리고 raise_for_status()는 HTTP 오류를 즉시 예외로 변환하는데, 이것이 바로 원하는 동작입니다—제출 시의 4xx는 절대 유효한 작업이 될 수 없으므로 혼란스러운 응답 본문을 검사하는 것보다 빠른 실패가 낫습니다.

반환된 사전이 작업 기록입니다. 개발 중에 한 번 출력하여 식별자와 상태의 정확한 키 이름을 파악하세요. 맹목적으로 인덱싱하지 마세요; 작은 접근자 하나가 나머지 코드를 읽기 쉽게 유지합니다:

job = submit_image("A flat illustration of a paper plane over a city map")
print(job)

대기 중인 작업이 출력되면 curl에서의 이식이 올바른 것입니다. 예외가 발생하면 raise_for_status()의 예외 메시지가 인증 문제인지 페이로드 문제인지 알려줍니다—셸에서 마주칠 동일한 두 가지 범주입니다.

세계 지식과 렌더링된 텍스트를 위한 프롬프트 작성

텍스트-이미지 모델은 프롬프트가 보여야 할 내용을 설명할 때 가장 강력하고, 모델이 추론해야 할 지식을 암시할 때 가장 약합니다. seedream-5.0-lite/text-to-image는 일반적인 세계 맥락—인식 가능한 물체, 일반적인 디자인 관례, 타이포그래피 스타일—을 활용할 수 있지만, 해당 맥락을 고정할 충분한 내용을 여전히 제공해야 합니다.

장면 프롬프트의 경우 주제, 구도, 시각적 스타일을 설명하세요. 'A cozy reading nook by a window, soft afternoon light, three-quarter view, muted earth tones'는 모델에게 무엇을 그릴지와 스타일을 어떻게 디자인할지 모두 알려줍니다. 모호한 프롬프트는 평범한 이미지를, 구체적인 프롬프트는 사용 가능한 이미지를 만듭니다.

렌더링된 텍스트는 프롬프트가 일반적으로 실패하는 지점입니다. 이미지 내에 텍스트가 필요하면 몇 가지 규칙을 따르세요:

• 정확한 문자열을 인용하세요. 원하는 텍스트를 따옴표 안에 작성하여 설명이 아닌 리터럴임을 명확히 하세요.
• 짧게 유지하세요. 짧은 제목이나 브랜드 이름은 안정적으로 렌더링되지만 단락은 그렇지 않습니다.
• 위치와 스타일을 명시하세요. 'The word "North" centered at the top in a bold sans-serif'가 'some text at the top'보다 낫습니다.
• 경쟁하는 텍스트를 피하세요. 한 이미지에 여러 개의 서로 다른 텍스트 요소가 있으면 깨진 글자가 생기기 쉽습니다. 여러 개가 필요하면 짧게 유지하고 서로 멀리 배치하세요.
• 한 번에 하나의 변수만 반복하세요. 문구, 레이아웃, 스타일을 동시에 바꾸지 말고 문구만 바꾸세요. 그렇지 않으면 무엇이 문제를 해결했는지 알 수 없습니다.

인식 가능한 맥락이 관련된 모든 것—제품 범주, 포스터 유형, 표지판 유형—은 명시적으로 이름을 지정하세요. 프롬프트가 훅을 제공할 때 모델의 사전 지식이 가장 유용합니다. 'A vintage travel poster for a coastal town'은 'a poster'보다 더 많은 사용 가능한 맥락을 담고 있습니다.

매개변수를 발명하지 마세요. 프롬프트가 원하는 텍스트 위치를 생성하지 않으면 먼저 프롬프트 자체의 문구를 조정한 후 문서화되지 않은 옵션을 시도하세요.

비동기 작업 처리 및 출력 다운로드

폴링은 통합이 조용히 잘못되는 지점입니다. 작업은 비동기이므로 상태를 확인하고, 확인 사이에 기다리고, 결국 포기하며, 어떤 상태 값이 "완료"를 의미하는지 정확히 알아야 하는 루프가 필요합니다.

import time

def wait_for_job(job_id: str, poll_interval: float = 3.0, timeout: float = 180.0) -> dict:
    deadline = time.monotonic() + timeout
    while time.monotonic() < deadline:
        response = requests.get(
            f"{BASE_URL}/{job_id}", headers=HEADERS, timeout=30
        )
        response.raise_for_status()
        job = response.json()

        status = job.get("status")
        if status in {"succeeded", "completed"}:
            return job
        if status in {"failed", "error", "cancelled"}:
            raise RuntimeError(f"Job {job_id} ended with status {status}")

        time.sleep(poll_interval)
    raise TimeoutError(f"Job {job_id} did not finish within {timeout}s")

플랫폼 문서에 표시된 내용에 따라 폴링 경로와 상태 문자열을 조정하세요—이 두 세부 사항이 위 스케치와 가장 다를 가능성이 높습니다. 구조가 핵심입니다: 단조 마감 시간, 확인 사이의 수면, 명시적인 성공 및 실패 집합, 그리고 반쯤 완료된 작업을 반환하는 대신 예외를 던지는 타임아웃.

작업이 성공을 보고하면 응답에 출력 URL이 포함됩니다. 해당 URL을 임시로 취급하세요. 링크를 저장하지 말고 바이트를 즉시 다운로드하세요:

def download_image(url: str, path: str) -> None:
    response = requests.get(url, timeout=60)
    response.raise_for_status()
    with open(path, "wb") as f:
        f.write(response.content)

job = wait_for_job(job_id)
download_image(job["output"]["url"], "out.png")

계속하기 전에 파일이 실제 이미지인지 확인하세요—열어보거나, 크기를 확인하거나, 최소한 바이트 길이가 비정상적으로 작지 않은지 확인하세요. 서버가 정상적으로 연결을 닫으면 잘린 다운로드가 requests에게는 성공으로 보입니다.

일반적인 오류와 해결 방법

첫 통합의 대부분의 실패는 네 가지 범주로 나뉩니다. 순서대로 처리하세요.

제출이 거부됨

첫 호출이 4xx를 반환하면 응답 본문을 출력하세요. 인증 오류는 키가 누락되었거나, 만료되었거나, bearer 토큰으로 전송되지 않았음을 의미합니다. 스키마 오류는 페이로드 형식 오류를 의미합니다—모델 필드 오류, 프롬프트 누락, 문서화된 매개변수 철자 오류. JSON을 별도로 검증하고 실행 가능한 curl 예제와 차이를 비교하세요.

작업이 완료되지 않음

루프가 무한히 회전하거나 타임아웃됩니다. 먼저 폴링 간격을 확인하세요: 수면 없이 엔드포인트를 계속 두드리면 속도 제한이 발생하여 정상 작업이 멈춘 것처럼 보일 수 있습니다. 그다음 상태 비교를 확인하세요—플랫폼이 success를 반환하는데 succeeded와 일치시키면 모든 작업이 미완료로 보입니다. 추측하지 말고 원시 상태 값을 한 번 기록하세요.

출력 URL이 404 또는 403 반환

출력 URL은 서명되었으며 시간 제한이 있습니다. 오래 폴링한 후 가져오면 링크가 만료되었을 수 있습니다. 완료 직후 가져오세요. 결과를 보존해야 한다면 링크 대신 파일을 저장하세요.

이미지가 렌더링되지만 텍스트가 깨짐

이것은 코드 문제가 아니라 프롬프트 문제입니다. 텍스트를 짧게 하고, 정확히 인용하고, 텍스트 요소 수를 줄이고, 스타일 지시를 더 명확하게 하세요. 어떤 조정이 도움이 되었는지 알 수 있도록 한 번에 하나의 변경만 하여 다시 실행하세요.

요청이 멈추거나 타임아웃됨

제출 및 폴링 호출에 항상 명시적 타임아웃을 설정하세요. 타임아웃이 없는 요청은 작업 프로세스를 무기한 차단할 수 있으며, 마감 시간이 없는 폴링 루프는 일시적 중단을 멈춘 프로세스로 바꿉니다.

예상치 못한 동작이 발생하면 여전히 실패하는 최소한의 curl 호출로 축소하세요. 원시 HTTP 요청이 비정상적으로 동작하면 Python 계층이 문제가 아닙니다—curl이 다시 작동하면 Python으로의 이식은 기계적입니다. seedream-5.0-lite/text-to-image의 모델 페이지에는 현재 매개변수와 응답 형태가 나열되어 있으므로 필드 이름을 가정하기 전에 먼저 확인하세요.