REST API

미디어

이미지 한 장을 붙이는 데 세 번.

파일은 우리 API 를 거치지 않고 저장소로 바로 갑니다. 큰 업로드가 요청 안에 앉아 있지 않습니다.

POST`/v1/media/presign`

업로드 주소와 미디어 id 를 받습니다.

이름	타입	설명
`fileName`필수	string	Original file name.
`contentType`필수	string	image/jpeg, image/png, image/webp, image/gif
`bytes`필수	number	File size in bytes.
`width`	number	Pixel width, if you know it.
`height`	number	Pixel height, if you know it.
`altText`	string	What the image shows, for screen readers. Applied to carousel items.
`aiGenerated`	boolean	AI 로 만들었거나 AI 로 크게 고친 파일이면 true. 네이버 블로그 사진에는 「AI 활용 설정」 표시가, 인스타그램·유튜브·틱톡에는 AI 선언이 붙습니다 (글에서 false 로 정했으면 그대로 둡니다).

돌려주는 것

이름	타입	설명
`id`	string	Pass this to publish as a mediaId.
`uploadUrl`	string	One-time PUT target.
`contentType`	string	Send exactly this on the PUT.
`expiresIn`	number	Seconds the uploadUrl stays valid.
`mediaExpiresAt`	string	ISO 8601. After this the media id is reclaimed if it was never published.

# 1. ask for a slot
curl -X POST https://api.uplika.com/v1/media/presign \
  -H "authorization: Bearer $UPLIKA_KEY" \
  -H "content-type: application/json" \
  -d '{"fileName":"cover.jpg","contentType":"image/jpeg","bytes":184320,"altText":"A cat on a windowsill"}'
# -> { "id": "med_01H...", "uploadUrl": "https://...", "mediaExpiresAt": "2026-08-12T..." }

# 2. send the bytes straight to storage (no auth header)
curl -X PUT "$UPLOAD_URL" -H "content-type: image/jpeg" --data-binary @cover.jpg

# 3. confirm
curl -X POST https://api.uplika.com/v1/media/med_01H.../complete \
  -H "authorization: Bearer $UPLIKA_KEY"

파일 올리기

선언한 것과 같은 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 활용 설정」 표시가, 인스타그램·유튜브·틱톡에는 AI 선언이 붙습니다 (글에서 false 로 정했으면 그대로 둡니다).

파일이 이미 웹에 있으면?

셸이 없는 에이전트는 바이트를 PUT 할 수단이 없어서 세 단계 업로드를 못 씁니다. 대신 주소를 주면 우리가 받아서 저장소에 복사하고 media id 를 돌려줍니다. 남의 주소를 채널에 그대로 넘기지 않습니다. https 만 받고, 구글드라이브·드롭박스 공유 링크는 파일이 아니라 HTML 미리보기를 주기 때문에 동작하지 않습니다.

POST`/v1/media/from-url`

공개 주소의 파일을 한 번의 호출로 워크스페이스에 복사합니다.

이름	타입	설명
`url`필수	string	Public https URL of the file itself.
`altText`	string	What the image shows, for screen readers.
`aiGenerated`	boolean	AI 로 만들었거나 AI 로 크게 고친 파일이면 true. 네이버 블로그 사진에는 「AI 활용 설정」 표시가, 인스타그램·유튜브·틱톡에는 AI 선언이 붙습니다 (글에서 false 로 정했으면 그대로 둡니다).

받는 것

이름	타입	설명
`types`	image	image/jpeg, image/png, image/webp, image/gif
`size`	image	up to 20MB
`aspect ratio`	image	up to 20:1 (any pixel width)
`count`	image	up to 20 per post on Threads
`types`	video	video/mp4, video/quicktime, video/webm
`size`	video	up to 8192MB
`length`	video	up to 43200 seconds
`width`	video	up to 4096px
`carousel`	mixed	2-20 items on Threads, images and video can be mixed

자주 묻는 것

이미지 한 장에 몇 번 부르나요?

세 번입니다. presign 으로 id 와 업로드 주소를 받고, 그 주소에 파일을 PUT 하고, complete 로 확인합니다. 세 번째가 끝나야 publish 가 그 id 를 받습니다.

파일이 API 를 거쳐 가나요?

아닙니다. 서명된 주소로 저장소에 바로 갑니다. 큰 업로드가 우리 요청 안에 앉아 있는 일이 없습니다.

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

Threads 는 됩니다. 2~20개짜리 캐러셀에 섞을 수 있습니다. 못 섞는 채널은 영상만 남기고 이미지를 빼며, 그 사실은 대상의 warning 에 남습니다. 어느 채널이 섞는지는 제약 엔드포인트가 알려 줍니다.