LlamaIndex 이미지 생성 도구: Sume Image API

LlamaIndex 이미지 생성 도구를 만들려면 Sume의 POST /v1/images를 호출하는 Python 함수를 FunctionTool.from_defaults()로 감싸 FunctionAgent에 넘기세요. 이 함수는 model: "sume/auto"와 프롬프트를 보냅니다. 200이면 data[].url에 이미지 URL이 담겨 오고, 202이면 Job 봉투가 오며, 두 번째 도구가 그 id로 GET /v1/jobs/{id}/status를 확인합니다.

LlamaIndex 관련 내용은 LlamaIndex의 도구와 에이전트 가이드에서, Sume 관련 내용은 Image API (영문), Job과 결과 (영문), 인증 페이지와 Sume API 레퍼런스에서 가져왔습니다. 모두 2026-09-27에 확인했습니다. Sume에는 LlamaIndex 전용 연동이나 패키지가 없으며, 이 도구는 requests로 HTTPS를 직접 호출할 뿐입니다. 레퍼런스 이미지와 모델 선택은 레퍼런스 이미지 기반 이미지 생성 API에서 다룹니다.

이미지 생성 도구는 어떻게 작성하나요?

FunctionTool은 동기든 비동기든 어떤 Python 함수든 감쌀 수 있습니다. 기본적으로 도구 이름은 함수 이름이고 설명은 docstring입니다. LlamaIndex는 이름과 설명이 모델이 도구를 호출하는 방식에 큰 영향을 준다고 설명하므로, 둘 다 모델이 읽는다는 점을 염두에 두고 작성하세요. FunctionAgent는 LLM 공급자의 도구 호출(tool calling) 기능으로 도구를 실행하므로, 이 기능을 지원하는 LLM을 넘기세요. SUME_API_KEY는 에이전트가 실행되는 서버 환경에 두세요. Sume 문서는 키를 신뢰할 수 있는 서버에 두고, 프론트엔드 JavaScript에는 절대 넣지 말라고 안내합니다.

import os, requests
from llama_index.core.agent.workflow import FunctionAgent
from llama_index.core.tools import FunctionTool
API = "https://api.sume.com/v1"
AUTH = {"Authorization": f"Bearer {os.environ['SUME_API_KEY']}"}

def generate_image(prompt: str) -> str:
    """Generate an image from a text prompt. Returns image URLs, or a job id to check later."""
    r = requests.post(f"{API}/images", headers=AUTH, timeout=45,  # Sume holds up to 30 s
                      json={"model": "sume/auto", "prompt": prompt})
    r.raise_for_status()  # 4xx, and 502 when the generation failed inside the wait
    if r.status_code == 202:  # still rendering: a job envelope, not images
        return f"Still rendering. Call check_image_job with job_id {r.json()['data']['job']['id']}."
    return "\n".join(image["url"] for image in r.json()["data"])

def check_image_job(job_id: str) -> str:
    """Check an image job started by generate_image. Returns its status, or image URLs."""
    s = requests.get(f"{API}/jobs/{job_id}/status", headers=AUTH, timeout=30).json()["data"]
    if not s["result_ready"]:
        return f"Job status: {s['sume_status']}"
    res = requests.get(s["result_url"], headers=AUTH, timeout=30).json()["data"]
    return "\n".join(a["url"] for a in res["result"]["artifacts"])

tools = [FunctionTool.from_defaults(generate_image), FunctionTool.from_defaults(check_image_job)]
agent = FunctionAgent(tools=tools, llm=llm)  # llm: any LlamaIndex LLM with tool calling

도구는 왜 200과 202로 분기하나요?

POST /v1/images는 요청을 최대 30초 동안 붙잡아 두며, 대부분의 카탈로그 모델은 그 안에 끝나 이미지 본문과 함께 200으로 응답합니다. 그 예산이 끝났을 때 생성이 아직 진행 중이면 Sume는 대신 Job 봉투와 함께 202로 응답합니다. 4K, 높은 quality, 큰 n은 202를 받을 가능성이 가장 큰 느린 설정입니다. Sume의 규칙은 본문 형태가 아니라 상태 코드를 확인하라는 것입니다.

• requests 타임아웃은 30초보다 길게 설정하세요. Requests는 timeout을 넘기지 않으면 절대 타임아웃되지 않으며, 그보다 작은 값을 주면 Sume가 응답하기 전에 예외가 발생할 수 있습니다.
• 202를 받으면 result_ready가 true가 될 때까지 GET /v1/jobs/{id}/status를 폴링한 뒤 result_url을 읽으세요. 이미지는 이미지 본문이 아니라 표준 Job 결과 형태로, result.artifacts[] 아래에 담겨 옵니다.
• 대기 중에 실패한 생성은 502를 반환하며, raise_for_status()는 모든 4xx와 5xx를 HTTPError로 바꿉니다.
• 이 라우트는 선택 사항인 Idempotency-Key 헤더도 받습니다. 같은 페이로드로 키를 재사용한 재시도는 두 번째 Job 비용을 내는 대신 첫 번째 Job을 이어받습니다.

도구는 어떤 요청 필드를 보낼 수 있나요?

이 도구는 본문을 필드 두 개로만 구성합니다. 나머지 필드는 대부분 카탈로그에 따라 허용 여부가 정해지므로, 에이전트에 노출하기 전에 GET /v1/images/models에서 모델의 supported_parameters를 확인하세요.

에이전트는 이미지 URL을 어떻게 다뤄야 하나요?

Image API 문서는 data[].url을 Sume가 호스팅하는 서명된 URL로 설명하며, Sume 인증 문서는 서명된 다운로드 URL을 임시 시크릿으로 취급하라고 안내합니다. 그러니 이 URL을 공개하거나 기록으로 보관하지 말고, 남겨 둘 이미지는 내려받으세요. Sume 결과물별 URL 유형은 AI 생성 영상 URL은 만료되나요?에서 비교합니다.

과금은 전부 아니면 전무 방식입니다. 완료된 생성은 전액 청구되고, 200 본문의 usage.cost가 청구된 USD 금액이며, 실패한 생성은 청구되지 않습니다. 에이전트 스택이 원격 MCP를 지원한다면 Sume의 호스팅 MCP 서버도 동작하지만, Sume 문서는 호스팅 MCP가 현재 주 경로가 아니라고 설명합니다. 이 도구가 REST API를 호출하는 이유입니다.