415 Unsupported Media Type 오류: 원인과 해결법
415 Unsupported Media Type 오류는 서버가 요청 본문의 형식을 거부했다는 뜻입니다. Content-Type 헤더를 고쳐 JSON은 application/json으로 보내세요.
415 Unsupported Media Type 오류는 보낸 본문의 형식을 서버가 받지 않아 요청을 거부했다는 뜻입니다. 해결하려면 엔드포인트가 받는 형식으로 본문을 보내고, 그에 맞는 Content-Type 헤더로 형식을 표시하세요. JSON API라면 JSON 본문과 Content-Type: application/json을 보내면 됩니다.
HTTP 정의는 MDN의 415 Unsupported Media Type 페이지에서, 각 클라이언트의 기본값은 그 클라이언트의 문서에서 인용했습니다. Sume의 동작은 오류와 비용 (영문)과 Format 호출하기 (영문) 문서에서 가져왔습니다. 모두 2026-09-27에 확인했습니다.
415 Unsupported Media Type 오류는 왜 나나요?
본문에 붙인 형식 표시나 인코딩 때문입니다. MDN은 요청의 Content-Type이나 Content-Encoding에서, 또는 서버가 콘텐츠 자체를 처리하는 과정에서 문제가 생길 수 있다고 설명합니다. MDN이 드는 예 두 가지가 일상적으로 겪는 경우입니다. Content-Type 헤더를 아예 붙이지 않고 보낸 JSON 본문, 그리고 application/x-www-form-urlencoded로 표시한 JSON 본문입니다.
정확한 값을 엄격하게 따지는 서버도 있습니다. MDN의 예를 들면, charset에 UTF-8 대신 UTF8을 쓰면 서버가 미디어 타입을 유효하지 않다고 볼 수 있습니다.
파일을 첨부하려고 multipart/form-data로 바꾸는 것도 JSON API에서는 같은 실수입니다. Sume에서는 생성 요청이 미디어를 파일 대신 JSON 본문 안의 공개 HTTPS URL로 받습니다.
curl, fetch, axios, Python Requests에서 415는 어떻게 고치나요?
직접 설정하지 않으면 클라이언트마다 Content-Type을 알아서 고르며, 서버가 보는 것은 그 기본값입니다.
| 클라이언트 | 따로 지정하지 않을 때 보내는 값 | JSON을 보내는 방법 |
|---|---|---|
curl -d | application/x-www-form-urlencoded | -H "Content-Type: application/json" 또는 --json(curl 7.82.0 이상) |
| 문자열 본문을 보내는 fetch | Content-Type을 설정하지 않으면 text/plain;charset=UTF-8 | headers: { "Content-Type": "application/json" } |
URLSearchParams나 FormData를 보내는 fetch | application/x-www-form-urlencoded;charset=UTF-8 또는 multipart/form-data | JSON.stringify(...)로 만든 문자열 본문과 위의 헤더 |
| axios | 일반 객체는 JSON, URLSearchParams는 폼 인코딩 | data에 일반 객체 전달 |
Python Requests data= | dict는 폼 인코딩, 문자열은 Content-Type 없음 | data= 대신 json=payload |
Sume의 415 응답은 무엇을 알려 주나요?
Sume API는 JSON 요청 본문을 받습니다. 모든 생성 요청에는 Content-Type: application/json이 필요하며, 문서는 application/json으로 보내지 않은 본문에 415 unsupported_media_type을 반환한다고 적고 있습니다. 이 오류는 서버가 받은 타입을 details.received_content_type에 그대로 담아 돌려주고, 현재는 API가 받는 타입도 details.supported에 나열합니다. 현재 코드에서 헤더 없이 curl -d로 호출하면 다음과 같은 응답을 받습니다(일부 생략).
{
"error": {
"code": "unsupported_media_type",
"message": "Send the request body as application/json.",
"retryable": false,
"next_action": "fix_input",
"details": {
"received_content_type": "application/x-www-form-urlencoded",
"supported": ["application/json"]
}
}
}415는 재시도해야 하나요?
그대로는 안 됩니다. 같은 헤더로 같은 본문을 보내면 같은 응답이 돌아오며, 현재 이 오류는 재시도할 수 없는 오류로 표시되고 next_action은 fix_input입니다. Format 실행 생성에서 4xx는 아무것도 실행되지 않았고 아무것도 청구되지 않았다는 뜻이므로, 헤더를 고친 뒤 다시 보내세요.
미디어 도구의 unsupported_media_type도 같은 오류인가요?
아닙니다. Sume의 트림, 필터, 오디오 분리 도구에서는 같은 error.code가 넘긴 video_url이 영상을 제공하지 않는다는 뜻입니다. 도구가 파일에 보낸 HEAD 확인에서 다른 타입이 나왔다는 것입니다. 현재 코드에서 이 거부는 415가 아니라 HTTP 400으로 돌아오며, 요청 헤더가 아니라 파일에 관한 문제입니다. 이 도구들은 이전 Sume Job의 출력처럼 Sume 미디어 호스트에 있는 영상을 받습니다. 다른 코드는 표면별 오류 코드 색인에, API가 읽는 모든 헤더는 헤더 레퍼런스에 정리되어 있습니다.
출처
관련 글
개발자 카테고리의 다른 글
- 일괄 전사 API: 여러 오디오 파일을 텍스트로 변환하기
API 일괄 전사는 파일마다 음성 인식 Job을 하나씩 보내는 루프입니다. 키는 파일 ID로 만들고, 결과는 웹훅이나 폴링으로 모읍니다. Sume에서 동작하는 방식을 설명합니다.
- AI 이미지 대량 생성 API: 스크립트로 수백 장 만들기
행마다 이미지 요청을 하나씩 보내되, 요청마다 고유한 Idempotency-Key와 async 모드를 쓰고 호출당 최대 네 장을 요청하세요. 속도는 요금제의 동시성이 정합니다.
- 여러 사람이 같은 API 키를 써도 되나요?
쓸 수는 있지만, 그러면 키의 요청 한도와 사용 기록, 폐기까지 함께 나누게 됩니다. 사람이나 서비스마다 키를 따로 주고, 그래도 공유되는 것이 무엇인지 알아 두세요.
- Python으로 말하는 아바타 만들기: Sume API 활용
Python Requests로 말하는 아바타를 만드세요. 아바타를 생성하고 Job을 폴링한 뒤, 말할 스크립트를 보내고 완성된 영상의 URL을 읽습니다.
작성자 Sume