영상 API 미디어 입출력: 공개 URL 입력, Sume URL 출력

Sume 생성 API는 미디어 입력을 요청의 정해진 필드에 담긴 공개 HTTPS URL로 받습니다. 그래서 일반적인 연동에는 업로드 단계도, 미리 만들어 둘 에셋도 필요 없습니다. 완성된 미디어는 media.sume.com에 호스팅되는 산출물 객체로 돌아오며, 저장해야 하는 것은 원본 프로바이더 URL이 아니라 이 Sume URL입니다.

아래 내용은 Sume 문서의 미디어 입력과 핵심 개념 페이지, 그리고 Format API (영문) 문서의 첨부 섹션을 바탕으로 합니다.

미디어 URL은 어떤 요청 필드에 넣나요?

각 워크플로는 라이브 OpenAPI 스키마에 정의된 바로 그 필드에서 미디어를 읽습니다. 이 스키마는 api.sume.com이 /reference/json에서 제공합니다. 일반적인 Avatar 1.0, Avatar Video, 페이스 스왑, 자막 요청을 제출하기 전에 별도의 Sume 에셋을 만들 필요는 없습니다. 페이스 스왑은 베타입니다.

전체 요청 예시는 스크립트로 말하는 아바타 영상 만들기와 영상에 자막 입히기에 있습니다.

Format 실행에 이미지를 어떻게 첨부하나요?

Format 실행에는 에이전트가 볼 수 있는 이미지를 최대 30개까지 실행 생성 본문의 attachments[]로 실을 수 있습니다. 각 항목에는 현재 유일한 타입인 type: "input_image"와, image_url 또는 asset_id 중 하나가 들어갑니다.

• image_url은 공개 HTTPS URL입니다. Sume가 실행을 만들 때 이 URL을 가져오므로 인증 없이 접근할 수 있어야 합니다.
• asset_id는 Assets API로 업로드해 준비가 끝난, 같은 워크스페이스의 이미지입니다.
• filename은 선택 사항이며 에이전트에게 보이는 라벨입니다. 생략하면 URL의 파일 이름(basename)이 쓰입니다.
• Sume는 실행을 만들 때 모든 첨부를 가져와 실제 타입과 크기를 확인하고, 내구성 있는 스토리지로 복사합니다. 깨졌거나 비공개인 이미지가 있으면 몇 분 뒤에 실행이 중단되는 대신 생성 요청 자체가 실패합니다.
• asset_id나 이미 media.sume.com에 있는 URL은 다시 복사하지 않습니다. 같은 Idempotency-Key로 동일한 요청을 재전송하면 이미지를 다시 가져오지 않습니다.

curl -sS -X POST "https://api.sume.com/v1/formats/acme/product-hero/runs" \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: sku-8823-hero-v1" \
  -d '{
    "instruction": "Make a product hero from the attached photo.",
    "input": { "brand": "Acme" },
    "attachments": [
      { "type": "input_image", "image_url": "https://cdn.example.com/shot.jpg" },
      { "type": "input_image", "asset_id": "asset_…", "filename": "packshot.png" }
    ]
  }'

실행 하나에 미디어 파일을 몇 개까지 넣을 수 있나요?

host_image_url이나 product_image_urls[]처럼 input 안에 있는 미디어 URL도 attachments[]와 공유하는 하나의 예산에 포함됩니다. 기준은 필드 이름이 아니라 파일 형식입니다. input 안의 HTTPS URL은 아무리 깊이 중첩되어 있어도 파일 이름이 미디어 확장자로 끝나면 예산에 포함됩니다. 제품 페이지 URL은 포함되지 않고, 같은 URL이 반복되면 한 번만 세며, 실행 중에 에이전트가 직접 찾은 미디어는 포함되지 않습니다.

Sume가 미디어 URL을 거부하는 이유는 무엇인가요?

입력 이미지와 영상 URL은 가져올 수 있는 공개 HTTPS URL이어야 합니다. localhost, 사설 네트워크 URL, HTTPS가 아닌 URL, 서명된 URL이나 비공개 URL, 콘텐츠 타입이 맞지 않는 URL은 생성 제출 전에 거부됩니다. Format 실행에서 첨부에 문제가 있으면 생성 요청이 다음 코드 중 하나로 실패합니다.

• 400 invalid_attachment: type이 잘못됐거나, URL이 없거나 HTTPS가 아니거나, image_url과 asset_id를 둘 다 보냈거나, 항목이 너무 많거나, 원본이 허용된 이미지 타입이 아니거나, 미디어 예산을 넘은 경우입니다.
• 400 attachment_not_found: asset_id가 이 워크스페이스에 없는 경우입니다.
• 413 attachment_too_large: 이미지 하나가 30 MB를 넘거나 전체가 500 MB를 넘는 경우입니다.
• 502 attachment_fetch_failed: 호스트에 연결할 수 없거나, 핫링크 보호가 걸려 있거나, 2xx가 아닌 응답이 와서 Sume가 이미지를 가져오지 못한 경우입니다. details.index가 해당 첨부를 알려 줍니다.

Job이 끝나면 무엇이 돌아오나요?

완료된 Job에는 아래와 같은 산출물 객체가 포함될 수 있습니다. Sume는 생성 결과를 공개 결과로 노출하기 전에 media.sume.com의 Sume 소유 미디어 URL로 미러링하며, Job의 결과는 /v1/jobs/:id/result에서 가져올 수 있습니다.

공개 계약은 Sume 소유 산출물 URL이며, 원본 프로바이더 URL은 계약에 포함되지 않습니다. Format 실행의 영수증에는 보여 줄 결과물 하나를 가리키는 primary_output_url도 있고, 실행이 만든 모든 파일이 artifacts[]에 나열됩니다. 이 미디어 URL은 내구성 있는 공개 URL이므로 저장해 두세요. 실행 하나의 전 과정은 Sume Format이란?에서 살펴봅니다.

{
  "id": "artf_...",
  "url": "https://media.sume.com/artifacts/...",
  "type": "image",
  "content_type": "image/png"
}

미디어 API가 하지 않는 일은 무엇인가요?

문서에 적힌 한계는 다음과 같습니다.

• 서명된 업로드·다운로드 URL과 비공개 오브젝트 키는 출시 시점의 공개 API 계약에 포함되지 않습니다.
• 첨부 타입은 input_image뿐입니다. 문서는 input에 URL로 보내고, 영상이나 오디오 레퍼런스도 같은 방식으로 보내세요.
• 트렌딩 영상은 리서치용 공개 시청 URL을 반환합니다. MVP에서는 내려받을 수 있는 원본 파일을 미러링하지 않습니다.