OpenAPI 청구 및 오류
공급자: Felo · 플랫폼 잔액으로 결제
이 페이지는 /api/v1/data/*, 즉 Felo OpenAPI 플랫폼 전용 API에 적용됩니다. 호출은 USD로 표시되는 서비스 크레딧 잔액인 플랫폼 잔액을 사용합니다. Felo Pro 크레딧은 소모하지 않습니다. /v2 아래의 기존 Felo API는 Pro 크레딧을 사용합니다.
현재 가격 읽기
curl -sS https://openapi.felo.ai/api/v1/data/prices이 공개 엔드포인트는 키가 필요하지 않습니다. 항목을 작업 ID로 일치시키고 현재 요율과 청구 단위를 읽으세요. 모든 작업이 같은 비용이라고 가정하거나, 예시의 요율을 애플리케이션에 고정하지 마세요.
| 작업 ID | 청구 단위 |
|---|---|
web.search, web.read, chat | 요청 |
x.user.info, x.user.search, x.user.tweets, x.tweet.search, x.tweet.replies | 반환 결과 |
ppt.generate | 생성된 페이지 |
ppt.export | 내보내기 요청 |
ppt.generate.status, ppt.generate.historical, ppt.export.status, ppt.delete | 새 요금 없음 |
무료 상태 조회가 기본 생성이나 내보내기를 무료로 만드는 것은 아닙니다. X의 경우 페이지네이션과 중첩 반환 레코드가 과금 대상 사용량을 늘릴 수 있습니다.
잔액과 예약
실행 전에 서비스는 작업에 충분한 잔액을 예약할 수 있습니다. 성공한 작업은 해당 예약분으로 정산되며, 확인된 실패는 예약을 해제합니다. 비동기 작업의 경우 ID를 반환했다고 해서 청구가 이미 최종 확정되었다는 뜻은 아닙니다.
PPT 페이지 가격은 생성 시 10페이지를 예약합니다. 성공적인 생성은 실제 출력을 정산하고 남은 자금을 해제합니다. 생성과 내보내기는 별도 요금입니다. 반복 내보내기 동작은 PPT 워크플로를 참조하세요.
실행 또는 정산이 불확실한 경우, 서비스가 조정하는 동안 예약이 보류 상태로 남을 수 있습니다. 모든 타임아웃이나 5xx를 작업이 없었다거나 반복 요청이 무료라는 증거로 간주하지 마세요.
Console Billing에서 가용 잔액과 사용량을 검토하세요. 계정 수준 충전 안내는 Billing and Credits를 참조하세요.
API를 통해 지갑 사용량 조회하기
계정 소유자는 Felo 로그인 토큰을 사용하여 지갑 호출 기록을 확인할 수 있습니다. 이 자격 증명은 Data API 호출에 사용하는 API Key와 다릅니다. FELO_API_KEY를 대체하지 마세요.
curl -sS 'https://openapi.felo.ai/api/wallet/usage?call_type=data' \
-H 'Authorization: Bearer YOUR_FELO_LOGIN_TOKEN'기록은 data.items 아래에 있으며, call_type=data는 기능 호출을 필터링합니다. 사용량을 계정의 현재 가격과 비교하세요. 기록을 읽는다고 해서 또 다른 생성 작업이 제출되지는 않습니다. 계정 검토와 충전을 위해 Console Billing은 계속 사용할 수 있습니다.
오류를 방어적으로 읽기
먼저 HTTP 상태를 확인하세요. 오류는 아래 두 형태 중 하나를 사용할 수 있으며, 값은 예시입니다:
{"error":{"code":"invalid_parameter","message":"Check the request fields"},"request_id":"example-request-id"}{"status":402,"code":"INSUFFICIENT_BALANCE","message":"Insufficient balance","request_id":"example-request-id"}존재하면 error.code / error.message를 읽고, 그렇지 않으면 code / message를 읽으세요. 반환되면 request_id를 보존하세요. 성공 응답은 작업별로 다릅니다. 모두 같은 오류 또는 data 엔벨로프로 강제하지 마세요.
다음에 무엇을 할지 결정하기
| HTTP 상태 | 일반적인 원인 | 다음 단계 |
|---|---|---|
| 400 | 누락되었거나 잘못된 매개변수 | 재시도 전에 요청을 수정하세요 |
| 401 | 키 누락, 잘못됨, 폐기됨 또는 만료됨 | 키와 인증 헤더를 확인하세요 |
| 402 | 플랫폼 잔액 부족 | 가용 잔액과 보류 중인 예약을 확인하고 필요하면 충전하세요 |
| 404 | 이 계정에서 리소스를 찾을 수 없거나 접근할 수 없음 | ID와 생성 계정을 확인하세요 |
| 409 | 현재 작업 상태와 작업이 충돌하거나, 실행이 확인되지 않음 | 오류 코드를 읽고 기존 작업을 조회하세요. 즉시 중복 제출하지 마세요 |
| 410 | 리소스 만료 또는 삭제됨 | 저장된 파일을 사용하세요. 필요할 때만 새 작업을 만드세요 |
| 429 | 속도 제한 또는 API 키 할당량 초과 | 재설정 정보를 확인하고, 속도를 늦추거나 할당량 재설정을 기다리세요 |
| 502 / 503 / 504 | 상위 시스템, 가용성, 타임아웃 또는 정산 실패 | 유료 작업을 재시도하기 전에 작업이 이미 존재하는지 확인하세요 |
execution_unconfirmed(409)와 billing_settlement_pending(503)은 특별히 주의해야 합니다. 유료 작업을 즉시 재제출하지 마세요. 알려진 작업을 조회하거나 요청 ID와 함께 지원팀에 문의하세요. 성공적인 HTTP 상태와 빈 결과는 오류 응답과 다릅니다.
중복 작업 없이 재시도하기
- 읽기 전용 작업과 export-status 조회에는 제한된 백오프를 사용하고,
Retry-After가 있으면 이를 따르세요. - 저장된
task_id가 있는 실패한 생성 요청은 다른 작업을 만들기 전에 해당 작업을 조회하세요. - ID를 받기 전에 연결이 실패했다면 결과를 알 수 없습니다. 다시 보내면 요청이 중복 제거될 것이라고 가정하지 마세요.
- 429의 경우 짧은 속도 제한과 API 키 할당량 창을 구분하세요. 반복 재시도로는 할당량을 재설정할 수 없습니다.
- 구성한 데드라인 이후에는 재시도를 중단하고 호출자에게 실행 가능한 오류를 보여주세요.
지원이 필요하면 엔드포인트, 대략적인 시간, HTTP 상태, 요청 ID를 제공하세요. 전체 API 키는 절대 포함하지 마세요.