이제 Fellowi API로 영상도: 키, 모델 선택, 첫 요청

얼마 전까지 Fellowi API가 하는 일은 하나였습니다. 텍스트를 넣으면 이미지가 나오는 것. 이제는 훨씬 많은 일을 합니다. 같은 키로 영상 클립을 만들고, 이미지와 영상 모두 모델을 고르며, API Console에는 모든 모델이 가격과 함께 나와 있어 짐작할 필요가 없습니다. 제품에 이미지나 짧은 움직임이 필요하지만 그걸 위해 GPU를 직접 운영하고 싶지 않다면 이 글이 도움이 될 겁니다.

무엇이 바뀌었나

• 같은 키로 영상. image-to-video, text-to-video, 참조 이미지 기반 클립을 이미지와 같은 잔액, 같은 요청 형태로.
• model 필드. 초안에는 빠르고 저렴한 모델, 최종본에는 더 강한 모델. 이미지는 생략해도 되며 예전 연동이 늘 받던 것을 같은 가격에 받습니다. 영상 요청은 항상 모델을 지정합니다.
• 코드로 읽는 카탈로그. GET /v1/api/models가 키로 호출할 수 있는 것과 가격을 돌려주므로, 금방 낡는 목록을 넣는 대신 앱에서 직접 모델 선택을 만들 수 있습니다.
• 연동 자체의 지름길.콘솔의 "Copy for ChatGPT/Claude" 버튼이 레퍼런스 전체를 한 번에 복사합니다. 코딩 어시스턴트에 붙여 넣고 원하는 언어로 클라이언트를 부탁하세요.

키 받기

무료 계정을 만들고 /api-console을 열어 키 이름을 정하고 생성합니다. 전체 키는 딱 한 번만 표시되고 그 뒤로는 미리보기만 남으니 바로 시크릿 저장소에 복사하세요. 모든 요청은 이를 bearer 헤더로 보냅니다.

Authorization: Bearer fk_live_your_key_here

환경마다, 제품마다 키를 나누세요. 키마다 하루 코인 상한을 둘 수 있어서, 스테이징 루프의 버그가 밤새 잔액을 다 써버리는 일을 막는 가장 쉬운 방법입니다.

첫 이미지

생성은 비동기입니다. 큐에 넣으면 바로 202가 오고, 이미지는 조금 뒤에 도착합니다.

POST /v1/api/images
Content-Type: application/json
Authorization: Bearer fk_live_your_key_here
Idempotency-Key: 7f1c2b90-order-4411

{
  "prompt": "a ceramic mug on a linen cloth, soft window light",
  "quality": "standard",
  "aspectRatio": "4:5"
}

Idempotency-Key 헤더는 보기보다 중요합니다. 네트워크는 응답을 잃기도 하는데, 이 헤더가 있으면 같은 시도를 다시 보내도 두 번 결제하지 않고 같은 생성을 돌려줍니다. 주문 ID 등으로 시도마다 하나씩 만드세요. 그다음 완료될 때까지 폴링하고 결과를 내려받습니다.

GET /v1/api/images/{id}          -> "queued" ... "succeeded"
GET /v1/api/images/{id}/content  -> the image bytes

quality, format, aspectRatio, 유료 프롬프트 개선은 모두 선택 사항이며, 각 기본값은 그 옵션이 생기기 전 API의 동작입니다. images에 참조 이미지 URL 몇 개를 넣으면 요청이 편집 모델로 처리되어, 캐릭터나 제품을 여러 이미지에서 같은 모습으로 유지할 수 있습니다.

모델 고르기

GET /v1/api/models

키로 쓸 수 있는 이미지·영상 모델을 코인 가격과 함께, 영상은 최대 클립 길이, 지원 해상도, 시작 프레임 필요 여부까지 돌려줍니다. 원하는 모델을 model에 넣으세요. 사용자가 이것저것 시도할 때는 저렴한 모델, 남길 버전에는 강한 모델을 쓰는 방식이 좋습니다. 최신 수치는 제품 페이지에도 있으며, 결제하는 코드와 같은 곳에서 읽어옵니다.

첫 클립

image-to-video는 정지 이미지에서 시작합니다. 한 번 업로드하고 ID를 보관하세요.

POST /v1/api/uploads
{ "imageBase64": "<your start frame, base64>" }

-> { "upload": { "id": "..." } }

그다음 이미지와 똑같이 클립을 큐에 넣습니다.

POST /v1/api/videos
Idempotency-Key: 7f1c2b90-clip-4411

{
  "model": "fellowi-image-to-video-turbo",
  "uploadId": "<id from /v1/api/uploads>",
  "prompt": "steam rises slowly from the mug, the camera drifts in",
  "durationSec": 5,
  "resolution": "720p",
  "generateAudio": false
}

GET /v1/api/videos/{id}를 succeeded가 될 때까지 폴링하고 videoUrl을 내려받습니다. 클립은 초가 아니라 분 단위로 걸리니 천천히 폴링하고 사용자에게도 알려 주세요. text-to-video 모델은 업로드가 아예 필요 없습니다. 가격은 선택한 해상도에서 클립 1초당이며, 소리와 추가 참조 이미지는 지원하는 모델에서 더해집니다. API 클립은 항상 코인으로 결제되며, Director 플랜 한도는 웹 영상 스튜디오에서 만든 클립에만 쓰입니다.

실제 제품에 연결하기

• 키는 서버에 두세요. 브라우저나 모바일 앱에 절대 넘기지 마세요. 백엔드가 우리를 부르고, 프런트엔드는 백엔드를 부릅니다.
• 작업 큐로 다루세요. 생성 ID를 자체 레코드와 함께 저장하고, 워커에서 폴링하고, 파일이 오면 자체 사본을 저장하세요. 우리 사본은 전달용이지 보관소가 아닙니다.
• 실패도 정상적인 결과로 다루세요. 실패한 생성은 스스로 코인을 환불하고 TIMEOUT, MODERATION_REJECTED, VENDOR_ERROR, UNKNOWN 중 하나의 코드를 알려 줍니다. 각각에 도움이 되는 안내를 보여 주고 다시 시도할 수 있게 하세요.
• 키별 요청 한도를 지키세요. 할당량이 아니라 남용 방지 장치이며 콘솔의 각 키 옆에 표시됩니다. 진짜 상한은 코인 잔액입니다.

가격과 환불 구조는 API가 코인으로 과금되는 이유에서, 같은 API의 성인 콘텐츠는 캐릭터 생성 이미지 API 가이드에서 더 자세히 다룹니다.

하지 않는 것

웹훅은 아직 없습니다. 폴링하세요. 무료 등급도 없습니다. 모든 호출에 스튜디오와 같은 가격으로 코인이 듭니다. 모더레이션이 거부한 것은 생성하지 않으며, 성인용 결과물은 앱이 무엇이든 공개 플랫폼에 맞지 않습니다. 또한 약관은 생성물의 상업적 이용을 제한하지 않지만, 이미지가 유일하다거나 모든 제3자 권리에서 자유롭다고 약속하지는 않습니다. 직접 찍지 않은 스톡 이미지처럼 다루세요. 만들려는 것에 맞는다면 콘솔에서 시작하면 됩니다.