미디어

참조용 이미지·영상·오디오를 URL, 인라인, 업로드로 보내는 방법과 작업이 만든 파일 내려받기.

많은 모델이 파일을 입력으로 받습니다. 움직이게 할 사진, 이어 만들 클립, 목소리 샘플, 노래 같은 것들입니다. 넘기는 방법은 네 가지, 결과를 받는 방법은 한 가지입니다.

파일을 보내는 네 가지 방법

가진 것	보내는 방법	알맞은 경우
공개 HTTPS 링크	URL 그대로. 예: `"image_url": "https://…/photo.jpg"`	이미 호스팅 중인 파일
메모리에 있는 작은 이미지	data URI. 예: `"image_url": "data:image/png;base64,…"`	빠른 테스트, 1 MiB 미만 이미지
로컬 파일	업로드한 뒤 `"image_url": "popnow://f/fil_…"`	그 밖의 모든 경우. 영상과 오디오 포함
에셋 라이브러리의 파일	`"image_url": "popnow://a/ast_…"`	여러 작업에서 다시 쓰는 파일. 에셋 참고

어떤 방법이든 파일은 모델 스키마가 그 용도로 선언한 필드(image_url, image_urls, video_url, audio_url …)에 넣습니다.

공개 링크

링크는 파일 자체를 돌려줘야 하고, 작업이 실행되는 동안 로그인 없이 받을 수 있어야 합니다. 클라우드 드라이브나 SNS의 공유 페이지는 파일이 아니라 웹 페이지를 돌려주므로 작업이 invalid_asset으로 실패합니다. 그럴 때는 파일을 내려받아 업로드하세요.

이미지는 MIME 형식을 붙인 표준 Base64 data URI로 보낼 수 있습니다. JPEG, PNG, WebP, GIF이며, 한 장당 디코딩 후 1 MiB·한 변 8,192픽셀까지, 요청당 16장까지, JSON 본문 전체는 2 MiB 미만입니다. 접두사 없는 Base64, SVG, 인라인 영상·오디오는 받지 않습니다. 인라인 이미지는 계정의 업로드로 저장되므로, 작업의 input에는 원래 바이트 대신 popnow:// URI가 보입니다.

파일 업로드

업로드는 세 번의 호출로 끝납니다. 업로드 티켓을 받고, 바이트를 PUT하고, 커밋합니다.

티켓 받기

FILE=reference.png
CONTENT_TYPE=image/png
BYTES=$(wc -c < "$FILE" | tr -d ' ')

TICKET=$(curl -s -X POST "https://api.popnow.ai/api/v1/common/upload-url" \
  -H "Authorization: Bearer $POPNOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"contentType\": \"$CONTENT_TYPE\", \"bytes\": $BYTES}")
UPLOAD_URL=$(echo "$TICKET" | jq -r .data.uploadUrl)
FILE_ID=$(echo "$TICKET" | jq -r .data.fileId)

응답에는 fileId, uploadUrl, 그대로 보내야 할 headers, expiresAt(약 20분 뒤), maxBytes가 들어 있습니다. 파일 이름은 없습니다. 저장 경로는 항상 서버가 정합니다.

바이트 PUT하기

curl -s -o /dev/null -w "%{http_code}\n" -X PUT "$UPLOAD_URL" \
  -H "Content-Type: $CONTENT_TYPE" \
  -H "Content-Length: $BYTES" \
  --data-binary @"$FILE"

티켓의 헤더는 모두 받은 그대로 보내세요. 모두 서명에 포함돼 있습니다. Authorization 헤더는 보내지 마세요. 브라우저에서는 Content-Length를 빼고 선언한 크기와 정확히 같은 File이나 Blob을 보내면 브라우저가 알아서 설정합니다.

커밋하기

curl -s -X POST "https://api.popnow.ai/api/v1/files/$FILE_ID/commit" \
  -H "Authorization: Bearer $POPNOW_API_KEY"

커밋은 크기, 형식, 파일 시그니처를 확인하고 쓸 수 있는 URI를 돌려줍니다.

{
  "code": 200,
  "msg": "success",
  "data": {
    "fileId": "fil_01k3m8x9q2z4v7n5p6r8s0t1w3",
    "status": "ready",
    "uri": "popnow://f/fil_01k3m8x9q2z4v7n5p6r8s0t1w3",
    "contentType": "image/png",
    "bytes": 402118,
    "width": 1024,
    "height": 1024,
    "expiresAt": "2026-10-17T09:12:00Z"
  },
  "request_id": "req_…"
}

uri를 모델 필드에 넣으세요. 예: "image_url": "popnow://f/fil_…". popnow:// URI는 내 계정의 키로만 쓸 수 있습니다. 커밋을 여러 번 해도 안전합니다.

업로드 제한

유형	`contentType`	최대 크기	최대 길이
이미지	`image/jpeg`, `image/png`, `image/webp`, `image/gif`	10 MiB	—
영상	`video/mp4`, `video/webm`	90 MiB	600초
오디오	`audio/mpeg`, `audio/wav`	90 MiB	600초
LoRA 가중치	`application/octet-stream`(`.safetensors` 파일)	2 GiB	—

모델에 따라 이보다 적게 받기도 하며, 스키마의 필드마다 적혀 있습니다. 업로드한 파일은 임시이고 커밋 응답의 expiresAt에 삭제 시각이 있으니, 작업을 만들기 직전에 업로드하세요. 여러 번 쓸 파일은 에셋 라이브러리에 저장하세요.

커밋이 40003을 돌려주면 보낸 바이트가 티켓과 맞지 않는 것입니다(크기, 형식, 내용 중 하나). 새 티켓을 받아 다시 업로드하세요.

결과 내려받기

완료된 작업은 output.assets에 파일을 나열하고, 각 파일에는 바로 쓸 수 있는 url이 있습니다.

curl -L -o result.mp4 "$(curl -s "https://api.popnow.ai/api/v1/jobs/recordInfo?taskId=$TASK_ID" \
  -H "Authorization: Bearer $POPNOW_API_KEY" | jq -r '.data.output.assets[0].url')"

링크는 서명돼 있고 약 20분 동안 유효합니다(expiresAt). 링크는 저장하지 말고 taskId를 저장했다가 필요할 때 작업을 다시 읽어 새 링크를 받으세요.
내려받을 때 API 키를 붙이지 마세요. 링크 자체가 권한이며, 가진 사람은 만료 전까지 누구나 내려받을 수 있습니다.
작업 전체를 읽지 않고 링크만 새로 만들려면 POST /api/v1/common/download-url에 { "taskId": "…" }(필요하면 에셋의 key도)를 보내세요.

파일 자체는 작업의 retention.outputsExpireAt 시각까지, 또는 작업을 삭제할 때까지 보관됩니다. 그 뒤에도 필요한 파일은 내 저장소나 에셋 라이브러리로 복사해 두세요.

이 페이지에서