AI 생성 미디어 저장과 서빙: 렌더부터 CDN까지

미디어 생성은 누구나 계획하는 절반이에요. 뒤통수를 치는 건 나머지 절반, 그러니까 그다음 90초 동안 벌어지는 일이에요. 받은 게 바이트인지 링크인지, 그 링크가 얼마나 오래 살아 있는지, 파일은 어디로 가는지, 그리고 금요일 밤에 그 파일을 10만 명에게 서빙하는 비용은 누가 내는지요.

이 글에서는 eroq API가 미디어 유형별로 무엇을 반환하는지, 무료 창작물 라이브러리와 유료 Store가 어떻게 다른지, 그리고 무엇을 선택하든 내 쪽에 꼭 보관해야 할 몇 가지를 정리해요.

API가 실제로 돌려주는 것

엔드포인트는 세 개, 답도 세 가지예요.

이미지 — POST /v1/images/generations는 기본적으로 이미지를 b64_json에 base64로 인라인 반환하고, 엔진이 URL로 응답하면 URL을 돌려줘요. response_format으로 URL 형식을 요청할 수도 있어요. 자세한 내용은 /docs/images에 있어요.

{
  "created": 1756118400,
  "model": "eroq-image-one",
  "data": [{ "b64_json": "UklGRl4jAABXRUJQ…" }],
  "usage": { "credits_spent": 10, "credits_remaining": 987 }
}

동영상 — 비동기예요. 요청을 제출하고 폴링하면, 완료된 작업에 클립이 base64 MP4로 인라인으로 담겨 와요. 이 페이로드는 24시간 동안 보관돼요. 그 뒤로 작업은 파일이 아니라 기록으로만 남아요. /docs/video를 참고하세요.

음성 — POST /v1/audio/speech는 JSON을 아예 반환하지 않아요. 응답 본문 자체가 MP3(audio/mpeg)라서 그대로 파일이나 오디오 요소로 파이프하면 돼요. 보이스 파라미터는 /docs/speech에 있어요.

이 섹션에서 딱 한 문장만 가져간다면 이거예요. 직접 요청하지 않는 한, 여기 있는 것 중 영구 URL은 하나도 없어요. base64 페이로드는 저장소가 아니라 전달 수단이고, 24시간은 파이프라인이 조치를 취하라고 주는 유예 기간이지, 그 위에 제품을 쌓을 수 있는 보관 정책이 아니에요.

창작물 라이브러리: 무료지만 저장 계층은 아니에요

/v1로 만든 이미지, 동영상, 음성 렌더는 모두 창작물 라이브러리에도 자동으로, 무료로 저장되고, meta에 전체 레시피가 함께 담겨요. 모델, 세부 설정 값, 초, 레퍼런스까지 똑같이 재현하는 데 필요한 모든 것이요. 생성된 항목마다 library_id가 붙어요.

curl https://eroq.ai/v1/creations \
  -H "Authorization: Bearer $EROQ_API_KEY"

{
  "folders": [{ "id": "…", "name": "Campaign A" }],
  "creations": [{
    "id": "…", "kind": "video", "url": "https://…", "model": "eroq-motion-one",
    "prompt": "slow pan over the rooftop", "meta": { "seconds": 10, "shot": "push-in" }
  }]
}

GET /v1/creations/{id}는 전체 레시피와 함께 항목 하나를 가져오고, PATCH는 항목을 다른 폴더로 옮기고, DELETE는 항목과 파일을 함께 삭제해요. 폴더용 CRUD도 짝을 맞춰 준비돼 있어요. 스튜디오에 보이는 것과 같은 라이브러리라서, 백엔드가 만든 렌더는 팀에게 보이고 팀이 만든 렌더는 백엔드에서 보여요.

라이브러리는 제품의 CDN이 아니라 레시피 로그이자 공유 작업 공간으로 쓰세요. “이걸 만들려고 정확히 뭘 보냈더라?”라는 질문의 답이 여기 있어요. 생각보다 자주 묻게 되는 질문이에요. 보통은 클라이언트가 어떤 룩을 승인한 다음 주, 같은 느낌으로 40개가 더 필요해질 때요.

eroq Store: CDN 위의 영구 URL

요청이 끝난 뒤에도 살아 있는 링크가 필요하면 업로드하세요.

curl -X POST https://eroq.ai/v1/storage/objects \
  -H "Authorization: Bearer $EROQ_API_KEY" \
  -F [email protected] \
  -F name="poster.webp"

{
  "id": "0b52…",
  "object": "storage.object",
  "url": "https://store.eroq.ai/acc_…/8c1f2-poster.webp",
  "bytes": 482133,
  "content_type": "image/webp",
  "usage": { "credits_spent": 2, "credits_remaining": 880 }
}

URL은 바로 활성화되고 글로벌 CDN으로 서빙돼요. 파일은 객체당 최대 100 MB까지 올릴 수 있고, GET /v1/storage/objects는 활성 객체를 URL과 함께 나열하며, DELETE /v1/storage/objects/{id}는 객체 하나를 삭제해요. 오리진에서는 즉시 지워지고, 엣지 캐시는 몇 분 안에 비워져요.

요금은 일회성으로, 10 MB 블록이 새로 시작될 때마다 2 크레딧이에요. 핵심은 “새로 시작될 때마다”예요. 1024×1024 이미지는 블록 하나라서 2 크레딧이에요. 4 MB 클립도 블록 하나예요. 11 MB 클립은 블록 두 개라서 4 크레딧이에요. 요금은 업로드할 때 한 번만 청구되고, 그 뒤로는 계정이 유지되는 동안 저장이 계속되며 공정 사용 범위 안에서 서빙 비용도 포함돼요. 저장 공간은 이미 사용된 것이라 삭제해도 환불되지 않아요.

호출 한 번으로 끝내는 방법도 있어요. 두 생성 엔드포인트 모두 store: true를 받는데, 이 값을 넣으면 렌더를 영구 저장하고 base64 대신 영구 CDN URL로 응답해요. Store 요금은 별도로 추가되고 사용 내역에도 따로 항목으로 표시돼요.

curl -X POST https://eroq.ai/v1/videos/generations \
  -H "Authorization: Bearer $EROQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "eroq-motion-one",
    "prompt": "Rain crawls down a diner window while a waitress refills a cup without looking up, street neon bleeding through the glass. Static shot, 35mm film, practicals, neon noir palette, calm tempo.",
    "seconds": 5,
    "aspect": "9:16",
    "store": true
  }'

출력물을 항상 보관하는 파이프라인이라면 왕복이 두 번에서 한 번으로 줄고, 렌더가 메모리에만 존재하는 틈도 사라져요.

호스팅이 생성과 같은 정책을 따르는 이유

생성과 호스팅은 보통 서로 다른 두 업체에서 와요. 이용 정책도 두 개, 청구서도 두 개, 키도 두 세트예요. 그리고 그 둘 사이의 이음새에서 렌더가 사라지거나, 다른 회사 제품을 위해 쓰인 규칙으로 다시 한번 심사를 받게 돼요.

Store는 그 이음새를 없애요. 생성에 내장된 객체 스토리지이자 CDN이고, 모델 자체와 똑같은 서면 이용 정책을 따라요. 정책 범위 안에서 API가 생성해 주는 것이라면 Store도 호스팅해요. 이게 Store가 존재하는 진짜 이유이고, CDN은 기본 사양일 뿐이에요.

게다가 기본값은 비공개예요. 렌더는 창작물 라이브러리에 저장되고, 게시하기 전까지는 내 워크스페이스에서만 보여요. 프라이빗 모드(스튜디오의 토글, 또는 이미지·동영상 엔드포인트의 private: true)를 쓰면 그 단계마저 건너뛰어요. 파일도, 라이브러리 항목도 남지 않고, 사용 내역의 프롬프트는 별표로 바뀌어요. 무검열 제품을 위한 인프라를 고르고 있다면 무검열 AI API 가이드에 장단점을 정리해 뒀어요.

내 쪽에 보관해야 할 것

바이트를 어디에 두든, 아래 항목은 내 데이터베이스에 보관하세요. 모두 저장하기는 싸고 나중에 복원하기는 비싸요.

• 요청 페이로드 전체. 프롬프트, 모델, 초, 비율, 모든 세부 설정 파라미터. 라이브러리도 레시피를 보관하지만, 공급자를 옮겨도 살아남는 건 내 쪽 기록이에요.
• 작업 ID와 그 작업의 고객. 공유 지갑에서 고객별 비용을 계산하는 건 내 몫이고, 이 조인은 나중에 사후로 할 수 없어요.
• 렌더별 usage.credits_spent. 응답에서 그대로 복사해 두세요. 나중에 가격표로 지출을 재구성하는 데서 청구 분쟁이 시작돼요.
• 시드(시드를 지원하는 엔진이라면). “그런 테이크를 하나 더 만들 수 있어요”와 “한 번 운이 좋았어요”의 차이가 바로 시드예요. 자세한 내용은 /glossary/seed에 있고, 엔진별 기능 플래그는 /models에서 볼 수 있어요.
• 바이트 사본, 그 미디어가 누군가에게 넘겨야 할 납품물이라면요. 특정 URL이 깨질 것 같아서가 아니라, 클라이언트가 돈을 낸 파일이 딱 한 곳에만 있어서는 안 되기 때문이에요.

비용을 두 번 내지 않고 서빙하기

<img>와 <video> 태그가 CDN URL을 직접 가리키게 하세요. 미디어를 애플리케이션 서버로 프록시하지 마세요. 대역폭 비용을 두 번 내고, 지연 시간이 한 단계 늘고, 정적 에셋이 오토스케일러가 신경 써야 하는 요청으로 바뀌어요.

동영상에 관한 실용적인 팁이 두 가지 있어요. 모든 클립에 포스터 이미지를 지정하세요. 포스터가 없는 비디오 요소는 첫 프레임이 디코딩될 때까지 회색 사각형이라, 피드에서는 깨진 페이지처럼 보여요. 그리고 렌더가 도착하는 순간 영구 URL을 설정하세요. 복사하거나 저장하기에 알맞은 곳은 웹훅 핸들러나 폴링 루프예요. 24시간 기간이 이미 끝난 뒤에 도는 야간 작업이 아니라요.

자주 묻는 질문

eroq는 생성된 동영상을 얼마나 오래 보관하나요?

완성된 클립은 작업에 인라인으로 24시간 동안 제공돼요. 영구 URL이 필요하다면 그 전에 저장하세요. 생성 호출에 store: true를 넣거나, 나중에 eroq Store에 업로드하면 돼요.

eroq Store에 미디어를 호스팅하는 비용은 얼마인가요?

10 MB 블록이 새로 시작될 때마다 2 크레딧이 업로드 시점에 한 번만 청구돼요. 일반적인 1024×1024 이미지는 블록 하나, 11 MB 클립은 블록 두 개예요. CDN 서빙은 공정 사용 범위 안에서 포함되고, 객체를 삭제해도 업로드 비용은 환불되지 않아요.

창작물 라이브러리와 Store는 같은 건가요?

아니요. 라이브러리는 모든 렌더를 전체 레시피와 함께 자동으로, 무료로 저장하고, 다시 찾아보고 리믹스하는 용도예요. Store는 유료 영구 객체 호스팅으로, 사용자에게 바로 보여 줄 수 있는 CDN URL을 제공해요.

/docs에서 스토리지와 미디어 엔드포인트를 읽어 보고, 렌더하기 전에 각 렌더를 어디에 둘지 먼저 정하세요.