메인 콘텐츠로 건너뛰기

짧은 답변

타임아웃 문제의 90%를 커버하는 세 가지 황금 규칙입니다:
  1. 동기식 이미지 엔드포인트에는 360초 타임아웃을 설정하십시오. 이미지 생성에는 비동기 작업 ID가 없습니다. 너무 일찍 연결이 끊기면 과금은 되지만 이미지는 받지 못합니다.
  2. 추론 모델에는 충분한 시간을 주십시오. gemini-3.1-pro-preview, gpt-5.6-sol, gpt-5.5-pro는 stream 여부와 상관없이 몇 분이 걸릴 수 있습니다.
  3. 긴 요청은 절대 CDN 노드를 통해 실행하지 마십시오. api-cf.apiyi.com는 Cloudflare 뒤에 있으며 약 100초가 지나면 524를 반환합니다. 빠른 텍스트 호출에만 적합합니다.
별도로: 특정 모델이 계속해서 429(동시 실행 수 부족)을 반환한다면 지원팀에 문의하여 쿼터를 검토해 달라고 요청하십시오.

타임아웃 치트 시트

타임아웃된 요청도 과금됩니다클라이언트 연결이 끊어지더라도 서버와 업스트림 제공업체는 작업을 끝까지 완료하며, 해당 요청에는 정상적으로 과금됩니다.다시 말해, 타임아웃을 너무 짧게 설정하면 비용만 지불하고 아무런 결과도 얻지 못하게 됩니다. 거의 완료된 요청이 클라이언트에 의해 도중에 끊어지지 않도록, 안전한 상한값으로 넉넉하게 설정해 두십시오.

4가지 핵심 사항 상세 안내

모든 APIYI 이미지 모델은 동기식입니다. 즉, 요청을 보내고 연결을 유지하면 응답 본문으로 결과가 반환됩니다. 비동기 작업 ID나 폴링 엔드포인트는 존재하지 않으며, 연결이 끊어지면 결과도 사라집니다.기본값이 문제가 되는 이유: 주류 HTTP 클라이언트는 기본 타임아웃이 30~60초로 설정되어 있지만, 이미지 생성은 본질적으로 긴 시간이 소요되는 요청입니다.
  • 2K/4K 해상도의 high 품질 GPT-Image-2는 실제로 3~5분이 소요됩니다
  • Nano Banana 4K 생성은 약 50초부터 시작되며, 피크 시간대에는 더 오래 걸립니다
  • 다중 이미지 참조 작업은 종종 5분을 초과합니다
권장 사항: 모델의 지연 시간을 잘 모를 때는 360초를 기준값으로 사용하십시오. 4K 및 다중 이미지 참조와 같은 무거운 작업에는 600초를 지정하십시오. 모델별 권장값은 이미지 API 모범 사례에서 확인할 수 있습니다.
간혹 클라이언트가 5분을 기다리는 동안 로그에는 이미지가 30초 만에 완료된 것으로 표시되는 경우가 있습니다. 이는 로그의 소요 시간이 게이트웨이가 처리를 마친 시점까지만 기록되는 반면, 클라이언트는 본문 수신 완료 및 연결 종료 신호까지 기다리기 때문입니다. 타임아웃을 늘리는 것이 항상 해결책이 되는 것은 아닙니다: 다운로드가 느린 유형에는 도움이 되지만, 데이터 전송은 이미 완료되었고 종료 신호만 누락된 경우에는 도움이 되지 않습니다. 로그에는 완료되었다고 나오지만 클라이언트가 아무것도 수신하지 못함 문서를 참고하여 한 번 측정한 후 결정하십시오.
일반적인 텍스트 모델은 수 초 내에 응답하므로 텍스트 호출에는 타임아웃 조정이 전혀 필요하지 않다고 생각하기 쉽습니다. 추론 모델 및 한 번의 호출로 수만 자를 생성하는 모든 워크로드는 예외입니다:
  • gemini-3.1-pro-preview
  • gpt-5.6-sol
  • gpt-5.5-pro (더 비싸고 느림)
  • claude-opus-5 및 심층 사고(deep thinking) / 높은 노력 수준(high effort)으로 실행되는 기타 모델
  • 긴 출력 작업: 드라마 대본, 소설, 장문 번역, 대규모 코드 생성
이러한 호출은 오랜 시간 추론을 수행한 후 긴 본문을 token 단위로 출력하므로, 총 지연 시간이 10분 이상 걸리는 것도 정상입니다.핵심 포인트: 비스트리밍은 버틸 수 없지만, 적절한 읽기 타임아웃을 설정한 스트리밍을 사용하면 해결됩니다. 비스트리밍은 전체 생성 결과를 버퍼링한 후 한 번에 전송하므로, 읽기 타임아웃이 전체 생성 시간과 경쟁해야 하며 도중에 아주 작은 문제만 발생해도 연결이 끊어집니다. 반면 스트리밍을 사용하면 첫 번째 바이트가 수 초 내에 도착하고, 이후 수십 초마다 데이터 이벤트가 도착하므로(추론 중 측정된 최대 무응답 간격은 약 42초이며, 중간에 keepalive ping 포함), 읽기 타임아웃이 총소요 시간이 아닌 이벤트 간 간격만 감당하면 됩니다.권장 사항:
  • 긴 출력에는 스트리밍을 우선 사용하십시오(stream=True). 읽기 타임아웃은 전체 생성 시간을 감당하는 거대한 단일 값이 아니라 이벤트 간 간격에 맞춰 90~120초로 설정하십시오.
  • 비스트리밍 방식을 반드시 사용해야 한다면 타임아웃을 300~600초로 설정하고 불안정성을 감수하십시오. 실행 시간이 길어질수록 결과가 도착하기 전에 연결이 끊어질 가능성이 높아집니다.
  • 사고 계층(reasoning_effort / thinking)을 허용된 시간에 맞추십시오. 계층이 높을수록 더 많은 여유 시간이 필요합니다.
긴 출력에 대한 전체 구현 방법(스트리밍 코드, max_tokens, stop_reason, 재시도)은 장문 출력 실무 가이드를 참조하십시오.
APIYI의 api-cf.apiyi.com 앞단에는 Cloudflare 글로벌 CDN이 배치되어 있습니다. 전 세계 가속 및 해외에서의 낮은 지연 시간을 제공하지만, 약 100초의 요청 타임아웃이 적용되어 이 시간을 초과하면 524 오류가 발생합니다.⚠️ 이는 이미지 엔드포인트에만 국한되는 문제가 아닙니다. 다음을 포함하여 100초를 초과할 수 있는 모든 호출에는 적합하지 않습니다:
  • ❌ 이미지 생성 / 편집
  • ❌ 동영상 생성
  • ❌ 긴 텍스트 출력(장문 기사, 대규모 번역, 대형 코드 생성)
  • ❌ 추론 모델에서의 심층 사고 작업
✅ 적합한 사용처: 일반적인 채팅 및 100초 이내에 완료되는 짧은 생성 작업.권장 사항: 긴 요청에는 api.apiyi.com(또는 백업용 b.apiyi.com)을 사용하십시오. 전체 노드 비교는 Base URL 가이드를 참조하십시오.
타임아웃과 함께 429 Too Many Requests 오류가 자주 발생한다면, 대개 타임아웃 설정이 아니라 동시 실행 수 쿼터가 원인입니다.동시 실행 수 제한은 전체 계정이 아닌 모델별로 적용됩니다. 특정 모델—특히 새로 출시되었거나 공급이 제한된 모델—은 쿼터가 더 낮을 수 있습니다.조치 방법:
  1. 지수 백오프(exponential backoff)를 구현하여 일시적으로 제한에 도달하지 않도록 하십시오
  2. 429 오류가 계속 발생하면 APIYI 고객 지원팀에 문의하십시오 — 해당 모델의 실제 쿼터를 확인하고 조정을 도와드릴 수 있습니다
자세한 규칙은 동시 실행 수를 얼마나 사용할 수 있나요? 문서를 참조하십시오.

코드 예제

긴 요청에서 자동 재시도에 주의하십시오: 많은 SDK는 기본값으로 두 번 재시도합니다. 이미지 또는 추론 작업이 시간 초과로 재시도되면, 결과물 없이 세 번 과금될 수 있습니다. max_retries을 0으로 설정하고 애플리케이션 로직에서 재시도를 직접 제어하십시오.

타임아웃을 늘린 후에도 계속 타임아웃이 발생합니까? 모든 홉을 확인하십시오

1

1단계: SDK 타임아웃이 실제로 적용되는지 확인하십시오

일부 프레임워크는 HTTP 클라이언트 외부에 또 다른 타임아웃을 감싸서 적용합니다. 유효한 구성을 출력하여 변경한 매개변수가 실제로 사용 중인 매개변수인지 확인하십시오.
2

2단계: 경로의 모든 홉을 확인하십시오

생성 시간보다 타임아웃이 짧은 계층이 있다면 클라이언트보다 먼저 연결이 끊어집니다:
  • 자체 호스팅 리버스 프록시: Nginx proxy_read_timeout (기본값 60초)
  • 클라우드 로드 밸런서: 유휴 연결 타임아웃
  • API 게이트웨이 / CDN: 오리진 타임아웃
  • 서버리스 함수: 실행 제한 (기본적으로 보통 30~60초)
  • 작업 큐 워커: 작업별 타임아웃
모든 홉의 타임아웃을 늘려야 합니다 — 클라이언트만 변경해서는 아무런 효과가 없습니다.
3

3단계: CDN 노드를 사용하고 있지 않은지 확인하십시오

Base URL이 api-cf.apiyi.com인지 확인하십시오. 오래 걸리는 요청의 경우 api.apiyi.com 또는 b.apiyi.com(으)로 전환하십시오.경험적 규칙: **524**은(는) 모델이 느린 것이 아니라 거의 항상 Cloudflare 계층의 타임아웃을 의미합니다.
4

4단계: 타임아웃과 동시 실행 수 제한을 구분하십시오

상태 코드를 확인하십시오: 524 및 연결 끊김은 타임아웃 문제입니다. 429은(는) 쿼터 문제입니다. 해결 방법은 완전히 다릅니다.
5

5단계: 호출 로그에서 실제 지연 시간을 확인하십시오

콘솔 호출 로그에서 요청의 실제 소요 시간과 과금을 확인한 후, 이를 바탕으로 합리적인 타임아웃을 도출하십시오.

자주 묻는 질문

대부분의 이미지는 수십 초 내에 완료되므로 200초면 넉넉해 보입니다. 하지만 공급자 측 피크 시간대에는 요청이 대기열에 들어가며, 단일 생성이 때로는 몇 분까지 늘어날 수 있습니다. 이러한 상황이 발생하면 클라이언트가 계속 대기 중인 한 게이트웨이가 백그라운드에서 다른 경로로 자동 재시도합니다.타임아웃이 너무 짧으면 게이트웨이가 경로를 전환하기 전에 클라이언트 측에서 연결을 닫아 요청이 실패하게 됩니다. 따라서 이미지의 경우 자동 전환을 위한 여유를 확보할 수 있도록 타임아웃을 360초로 설정하고, 4K 또는 다중 참조 이미지의 경우 600초로 설정하십시오(위 표 참조).또한 참조 이미지가 클수록 속도가 느려집니다. 8~10MB 본문의 편집 요청은 시간의 일부를 업로드에만 소모하며, 공급자가 이를 처리하는 데도 더 오랜 시간이 걸립니다. 사용 사례가 허용한다면 참조 이미지를 긴 변 기준 2048픽셀 및 개당 2MB 미만으로 압축하십시오. 품질에는 거의 영향을 주지 않으면서 눈에 띄게 빨라집니다. 자세한 내용은 이미지 압축 및 해상도를 참조하십시오.
불가합니다. 클라이언트의 연결이 끊어지더라도 서버와 업스트림에서는 작업을 계속 완료하므로 비용이 실제로 발생합니다.올바른 방법은 작은 값을 사용하고 재시도에 의존하기보다는 타임아웃을 안전한 상한값으로 한 번에 설정하는 것입니다. 재시도는 과금만 증가시킬 뿐입니다.
이미지 엔드포인트는 현재 동기 패스스루 모드로 작동하며, 고객 비즈니스 데이터를 저장하지 않으므로 “연결 끊김 후 ID로 조회” 기능은 지원되지 않습니다.권장 패턴: 동기 호출 + 넉넉한 타임아웃 + 자체 작업 상태 테이블. 이는 실질적으로 경량 비동기 큐 역할을 합니다. 이미지 엔드포인트는 동기식입니까, 비동기식입니까?를 참조하십시오.동영상 모델은 기본적으로 비동기식으로 작동하므로 이에 영향을 받지 않습니다.
일부 방지할 수 있지만, 전적으로 의존해서는 안 됩니다.스트리밍은 첫 번째 token을 더 빠르게 전달하므로 응답이 완전히 없는 위험을 줄여 줍니다. 그러나 추론 모델은 생각(thinking) 단계 동안 아무것도 출력하지 않을 수 있으므로 읽기 타임아웃이 여전히 발생할 수 있으며, 전체 출력을 완료하는 데 걸리는 총 시간은 동일합니다.올바른 접근 방식은 스트리밍에 넉넉한 타임아웃을 병행하는 것입니다.
과금에는 영향이 없습니다 — 대기한 시간이 아니라 소비된 token 및 호출 횟수에 따라 과금됩니다.유일하게 고려할 사항은 클라이언트 측의 리소스 사용량입니다. 연결이 길어지면 워커나 연결 풀 슬롯을 계속 점유하게 됩니다. 높은 동시 실행 수 환경에서는 비동기 IO 또는 전용 장기 작업 큐를 통해 이미지 및 추론 요청을 실행하십시오.
  • 524: Cloudflare 계층 타임아웃으로, api-cf.apiyi.com을(를) 사용했으며 요청이 약 100초를 초과했음을 의미합니다. 노드를 전환하십시오.
  • 429: 소요 시간과 무관한 동시 실행 수 또는 요청 제한입니다. 지수 백오프를 추가하고 문제가 지속되면 지원팀에 문의하십시오.

관련 문서

이미지 API 모범 사례

모델별 타임아웃 표와 출력 형식 참고

Base URL은 어떻게 설정합니까?

네 개 노드의 차이점과 선택 방법

이미지 엔드포인트는 동기식입니까, 비동기식입니까?

동기식 모드와 클라이언트 측 작업 관리

사용할 수 있는 동시 실행 수는 얼마입니까?

모델 유형별 동시 실행 수 제한과 쿼터 요청

문의하기

WeCom 지원

WeCom 지원 QR 코드QR 코드를 스캔하거나 클릭하여 지원에 문의타임아웃 문제 해결 및 동시 실행 수 쿼터 요청

이메일