문서

미디어

이미지 한 장을 글에 넣으려면 호출이 세 번 필요해요.

파일은 포샌디 API 서버를 거치지 않고 저장소로 바로 올라가요. 그래서 큰 파일을 올려도 API 요청이 오래 붙잡혀 있지 않아요.

POST /v1/media/presign

업로드할 주소와 미디어 id를 받아요.

이름	타입	설명
`fileName` (필수)	string	원래 파일 이름
`contentType` (필수)	string	`image/jpeg`, `image/png`, `image/webp`, `image/gif`
`bytes` (필수)	number	파일 크기(바이트)
`width`	number	가로 픽셀. 알면 넣어요.
`height`	number	세로 픽셀. 알면 넣어요.
`altText`	string	화면 낭독기용 이미지 설명. 캐러셀 항목에도 들어가요.
`aiGenerated`	boolean	AI로 만들었거나 AI로 크게 고친 파일이면 true. 네이버 블로그 사진에는 'AI 활용 설정' 표시가, Instagram, YouTube, TikTok(준비 중)에는 AI 사용 표시가 붙어요. 글에서 false로 정했으면 글 설정을 따라요.

돌려주는 값

이름	타입	설명
`id`	string	발행할 때 `mediaIds`에 넣는 값
`uploadUrl`	string	한 번만 쓸 수 있는 PUT 주소
`contentType`	string	PUT 요청에 이 값을 그대로 보내요.
`expiresIn`	number	`uploadUrl`을 쓸 수 있는 시간(초)
`mediaExpiresAt`	string	ISO 8601 시각. 이때까지 발행에 안 쓰인 미디어 id는 회수돼요.

올릴 자리를 받아요. 응답으로 { "id": "med_01H...", "uploadUrl": "https://...", "mediaExpiresAt": "2026-08-12T..." } 모양이 와요.

curl -X POST https://api.posendy.com/v1/media/presign \
  -H "authorization: Bearer $POSENDY_KEY" \
  -H "content-type: application/json" \
  -d '{"fileName":"cover.jpg","contentType":"image/jpeg","bytes":184320,"altText":"A cat on a windowsill"}'

파일을 저장소로 바로 보내요. 인증 헤더는 넣지 않아요.

curl -X PUT "$UPLOAD_URL" -H "content-type: image/jpeg" --data-binary @cover.jpg

다 올렸다고 알려요.

curl -X POST https://api.posendy.com/v1/media/med_01H.../complete \
  -H "authorization: Bearer $POSENDY_KEY"

파일 올리기

presign 때 적은 것과 같은 Content-Type으로 uploadUrl에 PUT 요청을 보내요. 인증 헤더는 넣지 않아요. 주소 안에 서명이 이미 들어 있고, 정해진 시간이 지나면 만료돼요.

POST /v1/media/{id}/complete

업로드가 끝났다고 알려요. 포샌디가 저장소에 파일이 실제로 있는지 확인해요.

DELETE /v1/media/{id}

잘못 올린 미디어를 지워요. 아직 글에서 쓰고 있는 파일, 또는 다른 워크스페이스의 복사본이 같이 쓰는 원본은 409로 거절해요.

PATCH /v1/media/{id}

'AI로 만든 파일' 표시를 켜거나 꺼요. 같은 파일을 쓰는 다른 워크스페이스의 복사본도 같이 바뀌어요. 이미 올라간 글은 바뀌지 않아요.

이름	타입	설명
`aiGenerated` (필수)	boolean	AI로 만들었거나 AI로 크게 고친 파일이면 true. 네이버 블로그 사진에는 'AI 활용 설정' 표시가, Instagram, YouTube, TikTok(준비 중)에는 AI 사용 표시가 붙어요. 글에서 false로 정했으면 글 설정을 따라요.

파일이 이미 웹에 있을 때

터미널을 쓸 수 없는 AI는 파일을 PUT으로 보낼 방법이 없어서 세 단계 업로드를 못 써요. 이때는 파일 주소만 주면 돼요. 포샌디가 그 파일을 받아 저장소에 복사하고 미디어 id를 돌려줘요. 받은 주소를 채널에 그대로 넘기지 않아요.

https 주소만 받아요.
Google Drive, Dropbox 공유 링크는 안 돼요. 그 링크는 파일이 아니라 미리보기 웹페이지(HTML)를 돌려주기 때문이에요.

POST /v1/media/from-url

공개된 주소의 파일을 호출 한 번으로 워크스페이스에 복사해요.

이름	타입	설명
`url` (필수)	string	파일 자체를 가리키는 공개 https 주소
`altText`	string	화면 낭독기용 이미지 설명
`aiGenerated`	boolean	AI로 만들었거나 AI로 크게 고친 파일이면 true. 네이버 블로그 사진에는 'AI 활용 설정' 표시가, Instagram, YouTube, TikTok(준비 중)에는 AI 사용 표시가 붙어요. 글에서 false로 정했으면 글 설정을 따라요.

발행에는 ready 상태 미디어만 쓸 수 있어요. complete를 건너뛰면 publish가 media_not_uploaded로 거절해요. 이 확인 덕분에 깨진 이미지가 든 글이 올라가지 않아요.

받는 파일

항목	종류	제한
형식	이미지	`image/jpeg`, `image/png`, `image/webp`, `image/gif`
크기	이미지	20MB까지
비율	이미지	100:1까지 (가로 픽셀 수는 제한 없음)
개수	이미지	Threads는 글 하나에 20개까지
형식	영상	`video/mp4`, `video/quicktime`, `video/webm`
크기	영상	8192MB까지
길이	영상	43200초까지
가로	영상	4096px까지
캐러셀	섞어서	Threads는 2~20개, 이미지와 영상을 섞을 수 있어요.

자주 묻는 것

이미지 한 장에 몇 번 불러요?

세 번이에요. presign으로 id와 업로드 주소를 받고, 그 주소에 파일을 PUT하고, complete로 알려요. 세 번째까지 끝나야 publish가 그 id를 받아요.

파일이 API 서버를 거쳐 가요?

아니요. 서명된 주소로 저장소에 바로 올라가요. 큰 파일을 올리는 동안 API 요청이 붙잡혀 있지 않아요.

한 글에 이미지와 영상을 같이 넣을 수 있어요?

Threads는 돼요. 2~20개짜리 캐러셀에 섞어 넣을 수 있어요. 섞을 수 없는 채널에서는 영상만 남기고 이미지는 빼요. 뺀 사실은 그 대상의 warning에 남아요. 어느 채널이 섞을 수 있는지는 플랫폼에서 확인해요.

이전답글과 지표 다음자동화