이미지 입력·JSON 출력 에이전트 API: Agent Completions

Sume 에이전트 API에 이미지를 보내고 JSON을 돌려받으려면, 공개 HTTPS image_url을 담은 input_image 콘텐츠 파트(또는 최상위 attachments)와 함께 POST /v1/agent/completions를 호출하고, output_schema를 추가한 뒤, 실행이 완료되면 output을 읽으세요. 첨부와 output_schema는 함께 쓸 수 있습니다.

세부 내용은 2026-09-26에 확인한 Sume 문서 Agent Completions 페이지와, 이 페이지가 안내하는 첨부 규칙 (영문)에서 가져왔습니다. 엔드포인트 전반은 백엔드에서 Sume 영상 에이전트 실행하기를 참고하세요.

메시지에 이미지는 어떻게 넣나요?

messages[]에서 content는 문자열이나 OpenAI 형태의 { "type": "text" } 파트 배열을 받습니다. input_text는 text의 별칭이고, 이미지는 input_image 파트에 담습니다. 턴은 순서대로 이어 붙여 하나의 프롬프트가 됩니다. 이미지만 있는 턴도 괜찮습니다. 텍스트 파트를 생략하면 에이전트에게 첨부된 파일을 사용하라고 전달됩니다. 모든 completion은 새 스레드에서 실행되므로 assistant 턴은 거부됩니다.

같은 항목 형태를 최상위 attachments로 보내도 되며, 두 출처는 하나의 목록으로 합쳐집니다. 항목에는 image_url 또는 asset_id와, 선택 사항인 filename 라벨이 들어갑니다. asset_id가 쓰는 Assets 라우트는 공개 OpenAPI 문서에서 숨겨져 있으므로, 아래 예시는 image_url을 씁니다.

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: sku-4411-caption-v1" \
  -d '{
    "messages": [{
      "role": "user",
      "content": [
        { "type": "input_text", "text": "Describe this product shot." },
        { "type": "input_image", "image_url": "https://example.com/shot.jpg" }
      ]
    }],
    "output_schema": {
      "name": "caption",
      "schema": {
        "type": "object",
        "properties": { "caption": { "type": "string" }, "alt_text": { "type": ["string", "null"] } },
        "required": ["caption", "alt_text"],
        "additionalProperties": false
      }
    },
    "generation_spend_cap_usd": 2
  }'

텍스트 대신 JSON을 받으려면 어떻게 하나요?

output_schema를 바인딩하면 실행의 output이 지정한 스키마를 따릅니다. 이미지는 그대로 에이전트에 전달되고, output은 실행이 완료된 뒤 스키마에 맞춰 파싱됩니다. 스케줄 실행과 같은 계약이며, 스케줄 실행은 Format 실행의 구조화 출력 규칙을 공유합니다. 스키마가 없으면 output은 기본 sume/action-run-output/v1 형태를 쓰고, 에이전트의 마무리 텍스트는 output.text에 담깁니다.

스키마는 엄격한 부분집합에 맞아야 하며, 그렇지 않으면 실행이 시작되기 전에 거부됩니다.

• 루트는 객체이고, 모든 객체에 "additionalProperties": false를 설정합니다.
• 모든 속성이 required에 있어야 합니다. 필드를 선택 사항으로 두려면 "type": ["string", "null"] 같은 nullable 유니온을 쓰세요.
• 중첩은 최대 10단계, 속성은 5000개, enum 값은 1000개까지입니다.
• $ref는 #/$defs/<name> 또는 등록된 SumeMediaFile#만 가리킬 수 있습니다.

결과는 어떻게 읽나요?

생성 호출은 agent.run 영수증과 함께 202를 반환합니다. next_action이 더 이상 poll_status가 아닐 때까지 GET /v1/agent-runs/{run_id}나 영수증의 status_url을 폴링하거나, communication.webhook_url을 보내 서명된 agent.run.terminal POST를 한 번 받으세요. 완료된 실행은 output, artifacts, usage를 채웁니다. 실행이 만든 것 중 스키마를 만족하는 것이 없으면 output은 null이고 output_error가 이유를 알려 주며, API에서는 실행이 failed로 끝납니다. 스키마 설계는 Sume Format 구조화 출력에서 다룹니다.

curl -sS "https://api.sume.com/v1/agent-runs/$RUN_ID" \
  -H "Authorization: Bearer $SUME_API_KEY" \
  | jq '.data | {status, output, output_error}'

어떤 이미지를 보낼 수 있나요?

Sume는 실행을 만들 때 모든 이미지를 가져와 실제 타입과 크기를 확인하고 내구성 있는 저장소에 복사합니다. 그래서 깨졌거나 비공개인 이미지는 실행이 아니라 생성 요청을 실패시킵니다. image_url은 공개 HTTPS여야 하며 인증 없이 접근할 수 있어야 합니다. 이전 Sume 출력처럼 이미 media.sume.com에 있는 URL은 다시 복사하지 않습니다.

이미지 요청은 왜 거부됐나요?

다음 거부 응답은 생성 호출에서 돌아옵니다.

• 400 invalid_attachment: type이 틀렸거나, URL이 없거나 HTTPS가 아니거나, image_url과 asset_id를 둘 다 보냈거나, 허용되지 않는 이미지 출처입니다.
• 413 attachment_too_large: 이미지 하나가 30 MB를 넘거나 전체가 500 MB를 넘습니다.
• 502 attachment_fetch_failed: 호스트에 도달할 수 없거나, 핫링크 차단이 있거나, 2xx가 아닌 응답이 와서 Sume가 이미지를 가져오지 못했습니다.
• 400 invalid_request: generation_spend_cap_usd가 없거나, instruction과 messages를 둘 다 보내지 않았거나 둘 다 보냈거나, assistant 턴이 있습니다.
• 409 idempotency_conflict: 새 이미지 목록처럼 다른 페이로드로 Idempotency-Key를 재사용했습니다.

에이전트 API가 아직 받지 않는 것은 무엇인가요?

현재 첨부 타입은 input_image뿐이라 PDF와 그 밖의 파일은 아직 첨부할 수 없습니다. 스트리밍, 동기식 choices[] 응답 같은 이 엔드포인트의 다른 미지원 항목은 백엔드에서 Sume 영상 에이전트 실행하기에 정리돼 있습니다.