Skip to main content
이 페이지는 자체 제품에 이미지 생성을 통합하는 개발팀을 위한 기술 공유 / 자문용 문서입니다. 여기서는 엔지니어링 관행만 다루며, 이 내용으로 인해 APIYI 측에서 변경해야 할 사항은 없습니다. 기존의 동기식 API 위에서 모두 구현할 수 있습니다.

​
동기식인가, 아니면 비동기식인가? 먼저 APIYI의 API 모델을 이해하십시오

APIYI 이미지 생성 API는 모두 동기식입니다: /v1/images/generations 같은 엔드포인트는 요청이 제출되면 “완료될 때까지” 처리됩니다. 클라이언트가 중간에 연결을 끊더라도 서버는 생성 작업을 끝까지 수행합니다. 즉, “먼저 task_id를 받고, 그다음 결과를 조회하는” 식의 비동기 작업 API가 아닙니다.
게이트웨이 계층에서 APIYI는 이미 상위의 비동기 폴링(일부 제공자는 기본적으로 polling_url 루프를 사용합니다)을 동기식 OpenAI 이미지 API로 감싸고 있습니다. 사용자 입장에서는 언제나 “한 번 제출하고, 한 번 결과를 받는” 방식이며, 직접 폴링 루프를 작성할 필요가 없습니다.
많은 팀이 곧바로 이렇게 묻습니다. “그렇다면 비동기 작업 관리는 어떻게 해야 합니까?” 사실 이는 서로 다른 두 가지입니다.
  • 동기식 — APIYI API의 형태입니다(HTTP 요청 수준: 요청 1회, 결과 1회).
  • 비동기 큐 — 사용자 측의 엔지니어링 관행입니다(비즈니스 작업 수준: 즉시 반환하고 백그라운드에서 실행).
이 둘은 서로 충돌하지 않습니다. 다음 내용은 동기식 API 위에 비동기 큐를 직접 감싸는 방법입니다.

​
왜 Dev Teams는 여전히 “작업 단위” 관리가 필요한가

이미지 API를 사용자의 요청 스레드 안에서 동기적으로 호출하는 것은 데모에서는 괜찮습니다. 그러나 실제로 최종 사용자를 위한 제품을 만들기 시작하면, 거의 확실히 “비즈니스 작업”과 “단일 HTTP 호출”을 분리해야 합니다. 이유는 네 가지입니다:

성공 ≠ 한 번의 호출

“성공한 작업”은 종종 여러 번의 동기 호출을 엮어서 완성됩니다. 초기 타임아웃이나 가끔 발생하는 429/503은 재시도가 필요합니다. 작업과 호출이 분리되면 재시도, 백오프, 타임아웃이 모두 최종 사용자에게는 투명하게 처리되며 — 사용자는 오직 “이 이미지는 결국 성공했다”만 보게 됩니다.

투명 포워딩, 저장 없음

APIYI는 투명 포워딩만 수행하며 사용자 입력이나 출력을 저장하지 않습니다(prompt, 참고 이미지, 생성 결과는 보관되지 않습니다). 사용자에게 이력, 상태 조회, 결과 저장을 제공하려면 반드시 직접 저장해야 합니다 — 제품 측에서 피할 수 없는 단계입니다.

최종 사용자에게 더 친화적인 UX

사용자는 제출 시 task_id를 받고, 프런트엔드는 긴 연결을 유지하는 대신 작업 상태를 폴링합니다. 페이지를 새로고침하거나 잠깐 네트워크가 끊겨도 작업은 사라지지 않으며, 배치 생성은 대기열에 쌓였다가 하나씩 채워집니다.

다중 제공자 사용이 가능해집니다

자체 작업 추상화가 생기면 Worker 계층은 필요할 때마다 여러 제공자 사이에서 전환 / 장애 조치 / 가격 비교를 할 수 있습니다. 적어도 “한 바구니에 모든 달걀을 담지 않기”를 가능하게 만듭니다.

​
비동기 큐로 동기 호출을 감싸는 참조 아키텍처

핵심 아이디어는 한 문장입니다. API 레이어는 “작업을 수신하고, 큐에 넣고, task_id를 반환”만 하며; 실제 동기 호출은 백그라운드 Worker가 수행합니다.
1

즉시 반환

프론트엔드는 생성 요청을 자체 API 레이어로 보냅니다. API 레이어는 작업 레코드(상태 pending)를 생성한 뒤 큐에 넣고, task_id를 프론트엔드에 즉시 반환합니다. 사용자는 절대 대기 상태로 묶이지 않으며, 밀리초 단위로 반환됩니다.
2

큐에 넣기

큐는 가볍게 구성할 수 있습니다. Redis List / Stream, RabbitMQ / Kafka, 또는 status 컬럼을 주기적으로 스캔하는 데이터베이스 테이블도 가능합니다. 선택은 규모에 따라 달라지며, 처음부터 무거운 미들웨어를 도입할 필요는 없습니다.
3

Worker: 동기 호출 + 재시도

백그라운드 Worker가 작업을 가져와 상태를 running로 설정한 뒤, APIYI 이미지 API를 동기적으로 호출합니다. 재시도 가능한 오류가 발생하면 지수 백오프로 재시도합니다(“Retry & Billing”은 아래 참조). 이 모든 과정은 사용자에게 투명하게 처리됩니다.
4

저장

성공하든 실패하든 결과를 데이터베이스에 다시 기록합니다. 성공 시 출력 이미지 URL, 레이턴시, 과금 메타데이터를 저장하고 상태를 succeeded로 설정합니다. 실패 시 오류를 저장하고 상태를 failed로 설정합니다. 이 부분은 정확히 APIYI가 대신 처리해 주지 않는 부분이며, 반드시 직접 구현해야 합니다.
5

프론트엔드 폴링

프론트엔드는 주기적으로 task_id로 작업 상태를 확인합니다(또는 WebSocket / SSE로 푸시할 수 있습니다). 작업이 완료되면 결과를 표시하고, 실패하면 친절한 메시지를 보여줍니다. 사용자의 브라우저가 긴 연결을 유지할 필요는 없습니다.

​
작업 상태 머신 및 데이터 모델

다음과 같이 명확한 상태 머신으로 각 작업의 생명주기를 설명합니다: 작업 테이블에는 최소한 다음 필드를 기록해야 합니다(타입은 스택에 따라 달라집니다):
생성된 결과를 자체 오브젝트 스토리지(OSS / S3 등)로 재호스팅하고 해당 URL을 저장하십시오. 장기적으로 제3자의 임시 링크에 의존해서는 안 됩니다. 임시 링크는 만료될 수 있으므로, 자체 사본을 보관하는 편이 최종 사용자에게 더 안정적입니다.

​
재시도 및 과금: 무엇을 재시도하고 무엇을 재시도하지 말아야 하는가

“작업 수준 관리”의 가장 큰 가치는 재시도를 제대로 처리하는 데 있습니다. 과금과 재시도 전략은 오류 유형에 따라 다릅니다:
“비즈니스 작업 재시도 횟수”와 “과금 여부”를 별도로 고려하십시오. 429/503 재시도는 과금되지 않으므로 자유롭게 백오프하셔도 됩니다. 하지만 타임아웃 연결 종료와 콘텐츠 안전 거부는 실패하더라도 과금됩니다. 무작정 재시도하면 비용이 증가합니다. 다시 비용을 지불할지 결정하기 전에 오류 유형을 확인하십시오.
오류 판단과 친절한 메시지에 대한 전체 기준은 다음을 참조하십시오:

Gemini 이미지 오류 처리

실패 감지 신호, 콘텐츠 모더레이션 정책, 그리고 친절한 메시지 전략입니다.

생성 실패 보장

사용자의 책임이 아닌 실패의 경우, credits는 건수 기준으로 환급됩니다.

​
고급: 하나의 큐, 여러 공급자

작업 추상화를 사용하면 Worker 호출은 “하나의 엔드포인트에 하드코딩”된 방식에서 “provider로 라우팅”되는 방식으로 바뀔 수 있습니다. 단일 submit(provider, payload) 진입점을 통합하고, Worker가 작업의 provider 필드에 따라 실제 업스트림을 결정하게 하십시오:
  • 페일오버: 공급자 A가 계속 실패하면 사용자에게는 보이지 않게 자동으로 B로 전환합니다.
  • 가격 비교 / 라우팅: 비용이나 상황에 따라 서로 다른 작업을 서로 다른 공급자나 모델로 분배합니다.
  • 카나리: 새 모델의 유효성을 검증하기 위해 일부 트래픽만 보내고, 이후 점진적으로 늘립니다.
대부분의 경우에는 사실 자체 제작한 멀티 공급자 레이어가 필요하지 않습니다: APIYI 자체가 gpt-image-2, Nano Banana, FLUX, Seedream 등 다양한 모델을 집계하므로, 단일 APIYI 키만으로 대부분의 요구를 하나의 API 스타일로 충족할 수 있습니다. 자체 제작한 공급자 추상화는 “혹시 모르니”를 위한 옵션입니다 — 진정으로 공급자 간 페일오버나 가격 비교가 필요할 때만 추가하십시오.

​
자주 묻는 질문

이미지 생성은 본질적으로 “한 번 제출하면 이미지 하나를 받는” 방식으로, 강한 동기식 의미를 가집니다. 따라서 이를 동기식 API로 감싸는 것이 대부분의 호출자에게 가장 간단합니다(유지해야 할 폴링도 없고, 처리해야 할 작업 만료도 없습니다). 비동기 큐, 상태 머신, 영속성이 필요한지는 귀하의 제품 형태(최종 사용자 대상인지, 이력이 필요한지)에 따라 달라지므로, 최대한의 유연성을 위해 그 부분은 필요에 따라 직접 구현하시면 됩니다.
계속 실행됩니다. 동기식 엔드포인트는 요청을 받으면 완료될 때까지 실행되며, 클라이언트의 연결 끊김은 서버 측 생성을 중단시키지 않으며, 해당 생성은 정상적으로 과금됩니다. 따라서 해상도에 맞춰 충분한 타임아웃을 설정하십시오(~60–600s) — 너무 짧게 설정해서 “이미지를 받지 못한 채 비용만 지불”하는 상황이 되지 않도록 하십시오.
아닙니다. APIYI는 투명 전달만 수행하며 사용자 입력이나 출력을 저장하지 않습니다. 사용자에게 이력, 상태 조회, 결과 영속성을 제공하려면 귀하의 쪽에 저장해야 하며 — 바로 이것이 이 가이드가 “작업 단위 관리”를 권장하는 이유입니다.
보통은 아닙니다. APIYI는 이미 하나의 API 스타일 아래에 여러 모델 패밀리를 통합하고 있으므로, 단일 키로도 보통 충분합니다. 공급자 간 장애 조치, 가격 비교, 규정 준수 라우팅에 대한 명확한 필요가 있을 때만 Worker 레이어에 공급자 추상화를 추가하는 것을 고려하시면 됩니다 — 이는 선택 사항이지 필수는 아닙니다.

​
관련 문서

Image API 필수 사항 및 모범 사례

모델별 timeout 표, base64 처리, 그리고 URL 출력 참고 자료입니다.

Async API가 없는 이유

FAQ: async image API가 있습니까? 작업 ID로 결과를 조회할 수 있습니까?

FLUX 개요

상위 async 폴링을 동기식 OpenAI Images API로 감싼 예시입니다.

Nano Banana 개발 가이드

동기식 멀티스레드 호출, timeout 설정, 그리고 과금 기본 사항을 한곳에 정리한 문서입니다.

Gemini 이미지 오류 처리

실패 감지 신호와 친절한 메시지 전략입니다.

생성 실패 보장

사용자가 원인이 아닌 실패에 대한 크레딧 환불 규정입니다.