Flux Tasks API를 사용하여 비동기 이미지 작업 폴링하는 방법

비동기(Async) 이미지 생성은 데모하기는 쉽지만, 실제로 배포하기에는 놀라울 정도로 어렵습니다. 보통 부족한 부분은 생성 요청 자체가 아니라, “이 작업이 완료되었는지, 그리고 정확히 무슨 일이 일어났는지?”를 물어볼 수 있는 신뢰할 수 있는 방법입니다.

이 가이드는 Ace Data Cloud의 Flux Tasks API를 사용하여 실제 폴링(polling) 워크플로우를 안내합니다. 이 API는 Flux 이미지 또는 비디오 생성 요청을 통해 반환된 작업 ID의 실행 상태를 조회하도록 설계되었습니다. 우리는 문서 예제가 Flux Images Generation API를 중심으로 구축되어 있기 때문에, 이미지 스타일의 작업 레코드에 초점을 맞출 것입니다.

목표는 이미지 제품에서 지루하지만 중요한 부분, 즉 작업 상태 추적, 최종 응답 읽기, 유용한 오류 표시 및 중복 작업 방지 기능을 구축하는 것입니다.

할 수 있는 것들

Flux Tasks API를 사용하면 Flux 생성 요청이 이미 플랫폼 작업 ID를 반환한 후 작업 세부 정보를 검색할 수 있습니다.

주요 세부 정보는 다음과 같습니다:

• 기본 URL (Base URL):
• 엔드포인트 (Endpoint):
• 인증 (Authentication):
• 헤더 (Headers): 및
• 단일 작업 액션 (Single task action):
• 배치 작업 액션 (Batch task action):

단일 작업을 위한 요청 본문(request body)에는 다음이 포함됩니다:

• uid=1000(sandbox) gid=1000(sandbox) groups=1000(sandbox): 생성된 작업 ID
• : 설정 값

여러 작업을 위한 요청 본문에는 다음이 포함됩니다:

• : 작업 ID 배열
• : 설정 값

반환되는 작업 객체는 , , , , 원래의 , 그리고 최종 . 완료되지 않은 작업은 또는 아직을 포함하지 않을 수 있습니다.

먼저 단일 작업을 폴링하기

백엔드에서 단일 작업 폴링 엔드포인트부터 시작하세요. UI가 결국 한 번에 많은 이미지를 표시하더라도, 단일 작업 폴링이 이해하고 테스트하기 더 쉽습니다.

{"error": {"message": "The token is invalid, please make sure your token is correct.", "code": "invalid_token"}, "trace_id": "37dbc369-cef6-46c3-b12f-f1730be9d856"}

문서화된 응답에는 실행 메타데이터와 최종 생성 결과가 모두 포함됩니다:

제품 백엔드에서 가장 중요한 규칙은 간단합니다. is_present 필드가 존재하고 is_available 필드가 제공될 때까지 작업을 완료된 것으로 간주하지 마십시오. 그 전까지는 대기(pending) 또는 실행 중(running) 상태로 유지해야 합니다.

나중에 디버깅할 것처럼 작업 기록 저장하기

좋은 폴링 워크플로는 이미지 URL보다 더 많은 것을 저장합니다. 최소한 다음을 보관하십시오:

• platform task uid=1000(sandbox) gid=1000(sandbox) groups=1000(sandbox)
• 사용자 또는 프로젝트의 내부 ID
• 원래 프롬프트 또는 요청 요약
• , , 및 사용 가능한 경우 최종 결과
• 결과가 반환된 경우의 정보

request_id 필드는 특히 유용합니다. 왜냐하면 작업을 시작한 것이 무엇인지 기록하기 때문입니다. 문서에는 prompt, user_id, task_id와 같은 필드가 포함되어 있습니다. 사용자가 “잘못된 이미지가 나왔다”고 말할 때, 로그를 검색할 필요 없이 정확한 생성 요청 정보를 제공합니다.

UI에 많은 카드가 있을 때 배치 폴링하기

단일 작업 버전이 안정화되면 배치 폴링을 추가하십시오. 이는 갤러리 페이지, 대시보드 또는 프론트엔드가 한 번에 여러 작업 카드를 새로 고쳐야 하는 다중 이미지 생성 흐름에 유용합니다.

{"error": {"message": "토큰이 유효하지 않습니다. 토큰이 올바른지 확인하십시오.", "code": "invalid_token"}, "trace_id": "7451fbf0-bdbd-47e6-941a-19bcbe576441"}

배치 응답에는 items와 next_cursor가 포함됩니다. 각 항목은 단일 작업 결과와 동일한 구조를 따르므로, 파서가 대부분의 코드 경로를 공유할 수 있습니다.

실용적인 접근 방식은 서버에서 몇 초마다 대기 중인 작업을 폴링하고, 데이터베이스를 업데이트하며, 프론트엔드가 자체 정규화된 작업 상태를 읽도록 하는 것입니다. 이렇게 하면 API 토큰이 브라우저에 노출되는 것을 방지하고, 열려 있는 모든 탭이 독립적으로 상위 API를 폴링하는 것을 막을 수 있습니다.

API 오류를 제품 상태로 변환하기

문서에는 몇 가지 일반적인 오류 코드가 나열되어 있습니다:

• invalid_parameters: 누락되었거나 유효하지 않은 매개변수
• invalid_request_path: 유효하지 않거나 지원되지 않는 요청 경로
• unauthorized: 누락되었거나 유효하지 않은 인증 토큰
• rate_limit_exceeded: 속도 제한 초과
• server_error: 서버 측 실패

오류 형태에는 , 객체, 그리고 :가 포함됩니다.

이 모든 것을 동일한 일반 실패로 보여주지 마십시오. A는 통합 또는 구성 문제입니다. A는 백오프(backoff)를 유발해야 합니다. A는 일반적으로 요청 빌더에 주의가 필요함을 의미합니다. A는 조사하거나 보고할 수 있도록 로깅되어야 합니다.

간단한 폴링 루프 설계

제가 보통 사용하는 형태는 다음과 같습니다:

1. 생성 요청은 작업 ID를 반환합니다.
2. 작업을 .으로 저장합니다.
3. .을 사용하여 폴링합니다.
4. 만약 값이 없다면, 작업을 보류 상태로 유지합니다.
5. 만약이 참이라면, 저장하고 완료로 표시합니다.
6. 오류가 반환되면, , , 그리고를 저장합니다.

배치 뷰(batch views)의 경우, 3단계를 .으로 대체하되, 각 반환된 항목에 대해 동일한 상태 전환을 유지하십시오.

최종 생각

작업 폴링은 화려하지 않지만, 이미지 생성 제품이 신뢰할 수 있게 느껴지기 시작하는 지점입니다. Flux Tasks API는 필요한 필드들(작업 ID, 타임스탬프, 경과 시간, 원본 요청 데이터, 최종 응답 데이터, 실패에 대한 추적 ID)을 제공합니다.

전체 참조 예제가 필요하면 Flux Tasks API 문서를 읽어보십시오: [https://platform.acedata.cloud/documents/flux-tasks-integration]