Rivya API로 멀티모달 워크플로 구축하기

좋은 Rivya API 연동은 단순히 하나의 모델에 한 번 요청을 보내는 일이 아닙니다.

대부분의 실제 제품 워크플로에는 작은 사슬이 있습니다. 맞는 모델을 고르고, 입력을 준비하고, 필요할 때 참조 파일을 업로드하고, 작업을 제출하고, 상태를 확인하고, 크레딧을 처리하고, 결과가 준비되면 제품에 알려야 합니다.

이 글은 그 계획의 형태를 보여줍니다. 가장 짧은 실행 경로는 Rivya API Quickstart를 사용하고, 정확한 요청 필드는 API 문서를 기준으로 확인하세요.

제품 순간부터 시작하기

엔드포인트를 고르기 전에 제품 순간을 한 문장으로 설명하세요.

예시:

• 판매자가 listing brief를 제출하면 제품 이미지 초안을 생성한다.
• 캠페인 매니저가 정지 이미지 방향을 승인한 뒤 짧은 영상 콘셉트를 생성한다.
• 내부 리서치 도구 안에서 채팅 턴을 보내고 응답을 사용자에게 스트리밍한다.
• 참조 이미지를 업로드하고 지원되는 모델 요청을 제출한 뒤 결과가 준비되면 사용자에게 알린다.

이 문장은 연동이 느슨한 API 호출 묶음이 되는 일을 막아 줍니다.

코드를 쓰기 전에 워크플로 매핑하기

요청 스키마를 열기 전에 이 표를 사용하세요.

워크플로는 각 API 영역이 왜 필요한지 설명할 수 있을 만큼 분명해야 합니다.

1단계: 연동용 키 만들기

그 키를 사용할 특정 앱, 환경 또는 워크플로용 API 키를 만드세요.

하나의 키를 모든 곳에 쓰지 마세요. 목적별로 키 이름을 정하면 나중에 검토하기 쉽습니다.

• production-image-workflow
• staging-video-tests
• internal-chat-assistant
• webhook-smoke-test

키를 저장하기 전에 API 인증을 읽으세요. 전체 secret은 한 번만 표시되므로 팀은 즉시 올바른 서버 측 secret 저장소에 저장해야 합니다.

2단계: 공개 API 목록에서 모델 선택하기

수동 테스트에서 작동했다는 이유만으로 모델을 하드코딩하지 마세요.

API 모델과 모델 API 레퍼런스를 사용해 확인하세요.

• 공개 모델 ID
• API에서 사용할 수 있는지
• 지원되는 입력 모드
• 프롬프트와 파라미터 기대값
• Files API가 필요한지
• 크레딧 동작과 준비 상태 메모

많은 연동은 이 단계에서 더 깔끔해집니다. 수동 Studio 테스트에 완벽한 모델이 자동화된 제품 흐름의 첫 모델로도 맞는 것은 아닙니다.

3단계: 첫 버전에 Files API가 필요한지 결정하기

모델이 텍스트 입력만으로 실행될 수 있다면 첫 버전은 텍스트 전용으로 유지하세요.

워크플로에 참조 미디어가 정말 필요할 때만 Files API를 추가하세요.

추가한다면 다음을 정의하세요.

• 제품이 허용하는 파일 종류
• 파일 정리 단계를 누가 소유하는지
• 업로드가 실패하면 어떻게 되는지
• 반환된 파일 데이터를 모델 파라미터로 어떻게 전달하는지
• 같은 파일을 재사용할지 다시 업로드할지

이렇게 하면 취약한 파일 경험이 깔끔해 보이는 생성 버튼 뒤에 숨어 버리는 일을 막을 수 있습니다.

4단계: 생성 작업 하나 제출하기

이미지, 영상, 오디오 생성의 일반적인 패턴은 다음과 같습니다.

1. 모델 ID, 프롬프트, 지원되는 파라미터를 준비합니다.
2. 안전한 재시도를 위해 idempotency key를 추가합니다.
3. 생성 엔드포인트로 제출합니다.
4. 공개 task ID를 저장합니다.
5. 작업이 최종 상태에 도달할 때까지 상태를 폴링합니다.

요청 형태는 생성 작업 만들기를, 결과 처리는 생성 상태를 사용하세요.

제품은 queued, processing, succeeded, failed를 사용자에게 보이는 상태로 다루어야 합니다. 사용자가 시스템 세부 정보를 읽거나 작업이 느린 이유를 추측하게 만들지 마세요.

5단계: 채팅 모델에는 Chat API 사용하기

채팅 모델은 생성 엔드포인트가 아니라 Chat API를 사용해야 합니다.

이 차이가 중요한 이유는 채팅 작업의 동작이 다르기 때문입니다.

• 채팅 턴은 API가 만든 세션에 속할 수 있습니다
• 비스트리밍과 SSE 스트리밍은 사용자 경험이 다릅니다
• 이미지 첨부는 Files API의 file ID를 사용합니다
• 크레딧 정산은 일반 비동기 미디어 작업이 아니라 채팅 턴을 따릅니다

제품 자체 인터페이스 안에서 assistant 답변이 필요하다면 Chat API가 맞는 경로일 수 있습니다. 사용자가 아직 아이디어를 탐색 중이라면 Rivya Chat이나 Studio가 더 나을 수 있습니다.

6단계: 폴링으로 시작한 뒤 Webhook 추가하기

첫 버전에서는 폴링이 이해하기 더 쉽습니다.

다음 경우에 API Webhooks를 추가하세요.

• 제품에 비동기 작업이 많음
• 대기 중인 클라이언트가 직접 폴링하면 안 됨
• 다운스트림 시스템에 서명된 완료 이벤트가 필요함
• 재시도와 중복 처리 설계가 이미 되어 있음

Webhook 수신기는 단순하고 엄격해야 합니다. 서명을 검증하고, 중복에 안전한 이벤트를 받아들이고, 제품 레코드 하나를 업데이트하고, 기록해도 안전한 것만 로그로 남기세요.

7단계: 제품 안에서 크레딧을 보이게 만들기

Rivya API는 Studio와 같은 계정 크레딧을 사용합니다.

연동은 이 중 얼마를 보여 줄지 결정해야 합니다. 최소한 팀은 다음을 알아야 합니다.

• 어떤 계정이 API 키를 소유하는지
• 어떤 워크플로가 크레딧을 소비할 수 있는지
• 크레딧이 너무 적으면 어떻게 되는지
• 생성 실패 상태를 어떻게 설명하는지
• 크레딧과 청구 질문은 어디로 보내야 하는지

사용자에게 보이는 지갑 모델은 API Credits, Rivya의 크레딧과 청구, Rivya 크레딧, 팩, 플랜을 이해하는 법을 참고하세요.

작고 단단한 첫 버전

좋은 첫 버전은 의도적으로 제한되어 있습니다.

예를 들어:

1. API 키 하나
2. 선택한 이미지 모델 하나
3. 아직 파일 업로드 없음
4. 생성 요청 하나
5. 상태 폴링 경로 하나
6. 제품 안의 간단한 결과 미리보기 하나
7. 분명한 크레딧 오류 메시지 하나

이 버전은 더 많은 움직이는 부분을 추가하기 전에 연결이 작동함을 증명합니다.

더 완전한 버전

첫 버전이 작동한 뒤에는 더 완전한 워크플로에 다음을 추가할 수 있습니다.

• 참조 이미지 또는 영상을 위한 Files API
• 모델별 파라미터 제어
• 제품 레코드와 연결된 idempotency
• 완료를 위한 서명된 Webhook
• assistant 턴을 위한 Chat API
• 채팅에 실시간 출력이 필요할 때의 서버 측 이벤트 스트림
• 실패한 작업을 위한 관리자 또는 지원팀 뷰

각 추가 항목은 실제 제품 필요에 답해야 합니다. 데모를 더 크게 보이게 하는 것뿐이라면 빼 두세요.

흔한 연동 실수

다음 패턴을 피하세요.

• 처음부터 모든 API 기능으로 시작하기
• 계정 소유자에게 크레딧 사용량을 숨기기
• API 흐름에 Studio 전용 가정을 사용하기
• 파일 업로드를 나중에 붙이는 세부 사항으로 다루기
• idempotency 없이 생성 요청을 재시도하기
• 비동기 생성이어야 할 작업에 Chat API를 사용하기
• 채팅 턴에 생성 엔드포인트를 사용하기
• 전체 API 키, Webhook secret, 임시 파일 세부 정보를 로그로 남기기

가장 안전한 API 워크플로는 소유권, 상태, 실패 처리를 명확히 합니다.

다음에 볼 곳

• 공개 API 허브는 Developers에서 시작하세요.
• 첫 요청을 실행하려면 Rivya API Quickstart를 사용하세요.
• 모델 ID를 선택하기 전에 API 모델을 확인하세요.
• 모델에 참조 미디어가 정말 필요할 때만 Files API를 사용하세요.
• 채팅 턴과 스트리밍 채팅 응답에는 Chat API를 사용하세요.
• 폴링만으로 충분하지 않을 때 API Webhooks를 사용하세요.
• 워크플로에 아직 사람이 직접 탐색하는 단계가 필요하다면 자동화하기 전에 Studio 대신 Rivya API를 써야 하는 경우를 읽으세요.