AI 이미지 설명 생성 API: 대체 텍스트와 캡션 만들기

AI 이미지 설명 생성기는 이미지를 보고 그에 관한 텍스트를 쓰는 모델입니다. 스크린 리더용 대체 텍스트(alt text), 캡션, 상품 설명이 그런 텍스트입니다. 직접 작성한 코드에서 실행하려면 이미지를 받는 API에 이미지를 보내고, 텍스트마다 JSON 결과의 이름 있는 필드로 요청하세요. 그러면 코드가 대체 텍스트와 설명을 따로 저장할 수 있습니다.

Sume에서는 이미지를 input_image 파트로 넣고 필드 이름을 정한 output_schema를 붙여 POST /v1/agent/completions를 호출하면 됩니다. 문서에 실린 예시부터가 에이전트에게 "Describe this product shot."(이 제품 사진을 설명해 주세요)라고 요청합니다. 내용은 2026-09-27에 확인한 Agent Completions 문서와, 이 문서가 안내하는 첨부 규칙 (영문)에서 가져왔습니다. 이미지를 넣고 JSON을 받는 방식 자체는 이미지 입력·JSON 출력 에이전트 API에서 다룹니다.

API로 이미지 설명을 생성하려면 어떻게 하나요?

input_image 파트 하나와, 필드마다 속성이 하나씩 있는 스키마로 completion을 만드세요. generation_spend_cap_usd는 필수이며 기본값이 없습니다. Idempotency-Key를 쓰면 안전하게 재시도할 수 있습니다. 같은 키를 다시 보내면 idempotency_hit: true와 함께 원래 영수증이 돌아옵니다.

• 호출은 agent.run 영수증과 함께 202를 반환합니다. next_action이 더 이상 poll_status가 아닐 때까지 GET /v1/agent-runs/{run_id}를 폴링한 뒤 output에서 필드를 읽으세요. API에서는 출력이 스키마를 만족하지 못한 실행이 failed로 끝나며, 이유는 output_error에 담깁니다.
• 이미지는 실행을 만들 때 Sume가 인증 없이 가져올 수 있는 공개 HTTPS URL이어야 합니다.
• 웹훅과 거부 코드는 이미지 입력·JSON 출력 에이전트 API에서 다룹니다.

curl -sS -X POST "https://api.sume.com/v1/agent/completions" \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: describe-sku-4411-v1" \
  -d '{
    "messages": [{
      "role": "user",
      "content": [
        { "type": "input_text", "text": "Describe this product shot: short alt text, a product title, and a two-sentence description." },
        { "type": "input_image", "image_url": "https://example.com/catalog/sku-4411.jpg" }
      ]
    }],
    "output_schema": {
      "name": "image_description",
      "schema": {
        "type": "object",
        "properties": { "alt_text": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" } },
        "required": ["alt_text", "title", "description"],
        "additionalProperties": false
      }
    },
    "generation_spend_cap_usd": 1
  }'

여러 이미지를 한 번에 설명할 수 있나요?

네, 두 가지 방법이 있습니다. 실행 하나에 input_image 파트나 최상위 attachments로 이미지를 최대 30장까지 담을 수 있습니다. 이미지마다 항목이 하나씩 있는 배열을 요청하고, 각 첨부에 에이전트가 보는 라벨인 filename을 붙이세요. 또는 이미지마다 실행을 하나씩, 각각 고유한 Idempotency-Key로 보내세요. 그러면 설명 하나가 이미지 하나에 묶이고, 실패하더라도 영향은 이미지 한 장에만 미칩니다.

스키마는 Sume의 엄격한 부분집합에 맞아야 하며, 이 부분집합에서 array는 items를 선언합니다. 규칙은 Sume Format 구조화 출력에 있습니다.

이미지 설명 생성 비용은 얼마인가요?

completion은 하나하나가 정액 캡션 호출이 아니라 실제 에이전트 턴이므로, 가격은 그 실행이 쓴 만큼입니다. 설명 작업은 미디어가 아니라 텍스트를 요청하고, 상한은 생성 지출에만 적용되므로 에이전트 자체의 턴은 상한과 별도로 추가 과금됩니다. 상한 전반은 무인 AI 에이전트 지출 상한에서 다룹니다.

실행 한 번의 비용을 보려면 AI 영상 실행 한 번의 비용에서처럼 debited_usd를 읽으세요. 중요한 수치는 다음과 같습니다.

어떤 제한이 있나요?

• 이미지만 설명할 수 있습니다. 현재 첨부 타입은 input_image뿐이므로 PDF와 그 밖의 파일은 아직 설명할 수 없습니다.
• 30 MB를 넘는 이미지나 전체 크기가 500 MB를 넘는 이미지 세트는 413 attachment_too_large로 거부됩니다.
• 텍스트는 모델이 그림을 읽어 낸 결과입니다. 상품 페이지나 대체 텍스트에 넣기 전에 검토하세요.