GPT Image 2.5 is live — OpenAI's newest image model, targeted edits that leave the rest of the frame alone
모든 가이드

· reAPI Team

fal API 상태: COMPLETED인데 결과가 없을 때

COMPLETED인데 결과가 없는 fal API 상태를 이해합니다. 생성 요청을 재시도하기 전에 결과 응답, 오류, 출력 필드 및 Webhook을 확인하세요.

fal API 상태: COMPLETED인데 결과가 없을 때

COMPLETED에서 확인을 멈추면 문제를 놓치기 쉽습니다. fal의 큐 API에서 이 상태는 실패하거나 취소된 요청을 포함하여 요청이 종료되었다는 뜻입니다. 사용 가능한 이미지나 동영상이 생성되었다는 뜻은 아닙니다.[1]

다음 호출은 원래 요청의 결과 엔드포인트로 보내야 합니다. 해당 응답에는 모델의 HTTP 상태와 본문이 담겨 있습니다.[2] 앱의 진행 표시가 초록색으로 바뀌었지만 파일을 찾을 수 없다면, 다른 생성을 제출하기 전에 그 결과를 따라가며 확인하세요. 조회 단계 하나가 빠졌거나, 잘못된 JSON 객체를 읽고 있거나, 실제 모델 오류가 발생했을 수 있습니다.

상태는 결과를 가져올 시점을 알려줍니다

fal의 큐 상태는 IN_QUEUE, IN_PROGRESS 및 COMPLETED를 거칩니다. COMPLETED에 도달하면 결과를 읽으세요. metrics.inference_time 같은 필드와 확인 가능한 오류 정보는 유용한 맥락이지만, 모델 응답을 대신하지는 않습니다.[1]

이러한 구분은 fal 자체 API 예제에서도 볼 수 있습니다. 요청을 제출하고 상태를 조회한 다음, 결과를 가져와 모델의 Output Schema를 확인합니다. JavaScript 클라이언트의 fal.queue.status()와 fal.queue.result()는 서로 다른 작업을 수행합니다. Python에서는 완료 상태 이후에 handler.get()을 호출합니다.[3][4]

애플리케이션이 이미지 컴포넌트에 전달하는 변수를 확인하세요. 큐 상태가 들어 있다면 아직 컴포넌트에 필요한 객체에 도달하지 못한 것입니다. 먼저 결과를 가져오세요. JavaScript SDK 결과 래퍼가 들어 있다면 모델의 출력 스키마를 적용하기 전에 data 속성을 읽으세요.[3] 시행착오로 images를 image로 바꾸기보다 실제로 어떤 응답을 가지고 있는지 확인하는 편이 더 유용합니다.

여기서는 호출 방식이 중요합니다. subscribe()는 요청 제출과 큐 대기를 대신 수행하지만, submit()은 애플리케이션이 수명 주기를 관리하도록 제어권을 돌려줍니다. 직접 호출하는 run()은 큐를 사용하지 않습니다.[4] 따라서 한 방식용 예제에는 코드에서 아직 필요한 대기 또는 래퍼 해제 단계가 있거나, 이미 수행한 단계가 포함되어 있을 수 있습니다.

원래 제출에서 반환된 URL을 사용하세요

제출에 성공하면 request_id, status_url 및 response_url을 저장하세요. fal 큐 가이드는 반환된 URL 사용을 권장합니다. 쿼리 URL을 직접 구성하는 경우, 가이드는 owner/app 경로와 작업 제출에 사용하는 전체 모델 엔드포인트 경로를 구분합니다.[3] 모든 모델 접미사를 요청 상태 경로에 덧붙이면 잘못된 곳을 조회할 수 있습니다.

재시작될 수 있는 워커에서는 대기 전에 이 값들을 프로세스 외부에 저장하세요. 그러면 로컬 작업은 동일한 요청을 읽으며 계속 진행할 수 있습니다. 이는 애플리케이션 설계 권장 사항입니다. 결과가 존재하는지 확인하기 위해서만 재시도 버튼이 원래 제출을 재구성해야 해서는 안 됩니다.

다음 JavaScript는 사용자의 서버에 저장된 요청을 읽습니다. URL은 임의의 브라우저 입력이 아니라 사용자의 서버가 신뢰할 수 있는 fal 제출 응답에서 가져와야 합니다. 요청에는 사용자의 API 자격 증명이 첨부되기 때문입니다.

async function inspectFalRequest(saved, key) {
  async function read(url) {
    const response = await fetch(url, {
      headers: { Authorization: `Key ${key}` },
      redirect: "error",
    });
    const raw = await response.text();
    let body;
    try {
      body = JSON.parse(raw);
    } catch {
      body = raw;
    }
    return { http: response.status, ok: response.ok, body };
  }

  const state = await read(saved.status_url);
  const lifecycle = state.body?.status;
  if (!state.ok || !["IN_QUEUE", "IN_PROGRESS", "COMPLETED"].includes(lifecycle)) {
    return { stage: "status-read-error", ...state };
  }
  if (lifecycle !== "COMPLETED") {
    return { stage: "pending", ...state };
  }

  const result = await read(saved.response_url);
  return { stage: "result", ...result };
}

이 헬퍼는 JSON이 아닌 응답을 의도적으로 텍스트로 보존합니다. 그렇지 않으면 JSON 파싱 실패가 유용한 오류를 다른 예외로 대체할 수 있습니다. 연결 실패는 여전히 호출자에게 예외를 던집니다. 다음 복구 단계에서 같은 작업을 확인할 수 있도록 저장된 요청을 유지하세요. 이 함수는 생성 POST 요청을 하지 않습니다.

ok 플래그는 읽기의 HTTP 결과이며, 제품에 사용 가능한 자산이 있다는 의미가 아닙니다. 여전히 본문을 확인해야 합니다. 마찬가지로 status-read-error는 이번 조회에서 큐 상태를 확인하지 못했다는 뜻이지, 원격 생성이 실패했다는 뜻이 아닙니다.

Python에서는 handler.get() 호출 자체뿐 아니라 주변 예외 처리도 확인하세요. 모든 예외에 None을 반환하는 포괄적인 핸들러는 앱의 다음 부분에 설명 없는 빈 값을 남깁니다. 진단을 위해 예외 정보를 보존하고 애플리케이션에 별도의 오류 경로를 제공하세요. 아직 대기 중인 요청, 거부된 입력 및 생성은 성공했지만 아직 다운로드하지 않은 파일을 동일한 빈 값으로 표현하지 마세요.

JavaScript 디버깅 중에는 민감한 정보를 제거한 응답 필드 이름 기록이 잘못된 객체 경로를 드러낼 수 있습니다. 자격 증명과 비공개 입력 내용을 공유 로그에 남기지 마세요. 경로를 확인한 뒤에는 결과를 이미지나 동영상 컴포넌트에 전달하기 전에 필수 필드를 검증하세요.

인증이 문제라면 작업을 만든 계정을 확인하세요. fal 키는 대시보드의 Keys 영역에서 생성되며 선택된 계정에 속합니다. 자격 증명은 사용자의 서버에 보관하며, 일반적으로 FAL_KEY에 둡니다. 원시 요청은 Authorization: Key ...를 사용합니다.[5] 다른 계정에서 키를 생성해도 기존 요청이 그 계정으로 이동하지 않습니다. 디버깅을 편하게 하려고 유효한 키를 브라우저 코드에 넣지 마세요.

실패가 발생한 위치에서 오류를 읽으세요

결과 응답은 완료된 요청에 미디어가 없는 이유를 설명할 수 있습니다. fal은 다음 결과 상태를 문서화하고 있습니다.[2]

결과 응답확인할 내용
400, 요청이 아직 진행 중저장된 상태 URL로 돌아가 해당 요청을 계속 관찰합니다
401조회에 사용한 자격 증명, 헤더 및 계정
404요청 ID, 쿼리 URL, 계정 및 적용되는 보존 규칙
422반환된 검증 오류 또는 모델 오류
499기록된 취소
500 또는 다른 서버 오류실제 응답 본문 및 요청 ID

마지막 행을 연결 시간 초과로 뭉뚱그리지 마세요. 결과 엔드포인트에서 모델 오류를 받았다면 확인할 응답이 있습니다. 엔드포인트에 도달하지 못했다면 그 응답이 없습니다. 복구 결정도 달라집니다.

예를 들어 no_media_generated는 문서화된 422 모델 오류로, 예상한 미디어를 생성하지 못한 채 생성이 종료되었음을 뜻합니다. fal은 이를 재시도 불가로 표시합니다.[6] 반환된 오류가 그렇게 명시할 때 내릴 수 있는 구체적인 진단입니다. 이미지 컴포넌트가 비어 있다는 것만으로 직접 그 진단을 내려서는 안 됩니다.

오류 구조를 그대로 유지하세요. 요청 오류에는 문자열 detail과 error_type이 있을 수 있고, 모델 검증 오류에는 타입이 있는 항목으로 구성된 detail 배열이 포함될 수 있습니다. fal은 일부 엔드포인트가 더 새로운 모델 오류 형식을 아직 채택하지 않았다고도 설명합니다.[6][7] 모든 오류가 한 가지 구조라고 가정하는 파서는 가장 필요한 메시지를 숨길 수 있습니다.

결과에서 파일 입력 오류를 보고하면 원본 파일도 확인하세요. 로그인된 브라우저에서 작동하는 URL이라도 서비스가 공개적으로 가져올 수 없을 수 있습니다. fal 파일 가이드는 접근 가능한 입력 URL을 요구하며 호스트가 요청을 차단하거나 속도를 제한할 수 있다고 설명합니다.[8] 출력 파서를 바꾸기 전에 이 조건을 확인하세요. 입력 가져오기 실패와 출력 필드 오류는 서로 다른 단계에서 발생합니다.

따라서 앱의 “API 호출 실패”는 조사 출발점이지 설명이 아닙니다. 어떤 호출이 실패했는지 기록하고 상태와 본문을 보존하세요. 실패에 크레딧이 부과되었어야 하는지 판단한다면 실제 요청 결과를 파악한 뒤 실패한 요청 과금 가이드를 참고하세요.

성공한 JSON 응답에도 미디어 확인은 필요합니다

실제로 제출한 정확한 엔드포인트의 Output Schema를 여세요. 일부 이미지 모델은 images 배열을 반환하지만 다른 모델은 다른 구조를 사용합니다. 일부는 sync_mode를 제공하여 미디어를 data URI로 반환하고 요청 기록에서 출력을 생략할 수 있습니다.[8] 이는 모델별 세부 사항입니다. 모든 결과에 다운로드 가능한 video.url 하나가 있다고 가정하는 범용 핸들러는 이를 모두 처리하지 못합니다.

이번에는 모델 응답에 예상한 출력 URL이 있지만 스토리지 업로드가 실패했다고 가정해 보겠습니다. 이는 가상의 복구 사례입니다. URL과 원래 요청 ID를 보존하고 파일이 여전히 사용 가능한 동안 파일 전송 단계를 재시도하며 저장한 바이트를 읽을 수 있는지 검증하세요. 생성을 다시 실행하면 원래 파일에 무슨 일이 있었는지는 설명하지 못한 채 새로운 작업이 만들어집니다.

API 마이그레이션에도 여기서 명시적인 필드 매핑이 필요합니다. 일반적인 reAPI 미디어 작업은 하나의 작업 응답에서 비즈니스 상태와 미디어 배열을 반환하며 output.image_urls 또는 output.video_urls를 사용합니다. 작업 레퍼런스와 오류 레퍼런스는 미디어 결과 누락과 생성 파일 저장 실패를 구분합니다.[9][10] 여기서도 HTTP 200만으로는 부족합니다. 작업 상태를 읽고 애플리케이션에 필요한 내용을 검증하세요. 제공업체를 바꿔도 파일 처리 단계는 사라지지 않습니다.

Webhook에서는 구분할 객체가 하나 더 생깁니다

fal Webhook 상태는 큐 수명 주기 값 대신 OK와 ERROR를 사용합니다. 결과를 JSON으로 표현할 수 없으면 OK 알림에 payload: null과 payload_error가 있을 수 있습니다. 문서는 복구를 위해 큐 결과로 돌아가도록 안내합니다.[11]

Webhook으로 구동되는 워크플로라면 결과가 없다고 판단하기 전에 전체 알림을 확인하세요. 큐의 status 필드용으로 작성한 파서를 Webhook 상태와 페이로드에 수정 없이 재사용해서는 안 됩니다. 알림을 기존 요청과 연결한 다음, 해당 필드가 요구하는 경우 결과를 가져오세요.

긴 작업에는 차단 호출을 무기한 유지하는 대신 큐 상태와 Webhook을 사용하도록 fal은 권장합니다.[3] 콜백이 일반적인 경로이더라도 자체 워크플로에 조회 경로를 유지하세요. 알림을 놓쳐도 조사할 ID가 남아야 하며, 워크플로를 다시 진행하려고 새 생성을 강요받아서는 안 됩니다.

완료된 결과는 즉시 저장하세요. 큐 결과의 가용성, 요청 기록의 페이로드 저장 및 미디어 파일 보존은 별개의 문제이며 결과 크기와 스토리지 설정이 각각 다르게 영향을 줄 수 있습니다.[2][11][12] 나중에 파일이 필요하면 직접 관리하는 스토리지에 복사하고 복사 성공 여부를 기록하세요. URL만 저장하는 것은 보관이 아닙니다.

장애를 확인할 시점

원래 결과를 가져올 수 없다면 실패 시각과 영향을 받은 서비스를 fal 공식 상태 페이지 및 사고 이력과 비교하세요. 페이지는 구성 요소를 구분하므로 어떤 알림이든 모든 오류의 설명으로 여기지 말고 요청과 관련된 부분을 살펴보세요.[13] 이 글은 실시간 가동 상태 평가를 제공하지 않습니다.

완료 상태인데 파일이 표시되지 않는다는 사실만으로 fal이 다운되었다고 판단할 수 없습니다. 상태 알림이 없다고 해서 코드가 잘못되었다고 증명되는 것도 아닙니다. 다음으로 유용한 증거는 여전히 원래 결과 응답의 HTTP 코드, 본문, 엔드포인트 및 요청 ID입니다. 이를 확보하면 조회 수정, 입력 교정, 파일 복구 또는 해결되지 않은 서비스 오류의 상위 지원 요청 중 무엇을 할지 결정할 수 있습니다.

참고 자료

  1. fal. 요청 상태 가져오기. 큐 API 레퍼런스. 2026년 11월 15일 열람.
  2. fal. 요청 결과 가져오기. 큐 API 레퍼런스. 2026년 11월 15일 열람.
  3. fal. 큐. 모델 API 추론 가이드. 2026년 11월 15일 열람.
  4. fal. 추론 방법: fal 모델 호출 방법. 2026년 11월 15일 열람.
  5. fal. API 키 가져오기. 2026년 11월 15일 열람.
  6. fal. 모델 오류. no_media_generated 항목 포함. 2026년 11월 15일 열람.
  7. fal. 요청 오류. 모델 API 가이드. 2026년 11월 15일 열람.
  8. fal. FLUX.1 [dev] API. Files 및 Schema 섹션. 2026년 11월 15일 열람.
  9. reAPI. 작업. reapi.ai/docs/api/tasks. 2026년 11월 15일 열람.
  10. reAPI. 오류. reapi.ai/docs/api/errors. 2026년 11월 15일 열람.
  11. fal. Webhook. 모델 API 추론 가이드. 2026년 11월 15일 열람.
  12. fal. 데이터 보존. 모델 API 가이드. 2026년 11월 15일 열람.
  13. fal. fal 상태. 2026년 11월 15일 공식 상태 페이지 인터페이스 확인. 여기서는 가동 상태를 평가하지 않습니다.
모든 가이드