API 타임아웃 설정: 몇 초가 적당한가요?

타임아웃은 대부분 모델이 아직 생성하는 중에 클라이언트나 중간 프록시가 기다리기를 멈춰서 발생합니다. 연결을 닫아도 이미 업스트림 제공사에 도달한 요청은 취소되지 않고, 생성이 끝나면 과금됩니다. 짧은 타임아웃과 재시도를 조합하기보다 처음부터 충분히 긴 타임아웃을 설정하세요.

타임아웃 직후에 재시도하면 두 번 과금되고도 결과를 못 받을 수 있습니다.

끊어 버린 요청은 대개 끝까지 진행되어 과금됩니다.
SDK의 기본 재시도는 타임아웃 뒤에 같은 요청을 다시 보냅니다.
재시도하기 전에 호출 로그에서 앞선 요청의 상태와 청구액을 확인하세요.

권장 타임아웃

작업	권장 타임아웃	비고
일반 채팅	60~120초	보통 몇 초 안에 응답
추론 모델, 긴 출력	스트리밍 사용. 스트리밍하지 않으면 300~600초	추론 강도가 높을수록 오래 걸림
이미지 생성과 편집	360초	이미지 엔드포인트는 동기식이므로 연결이 끊기면 결과가 사라짐
4K 출력, 참조 이미지가 많은 요청	600초	피크 시간에 더 느려짐
비디오 생성	작업 상태 폴링	제출과 상태 확인 호출은 빠르게 반환됨. 모델별 비디오 가이드 참고

추론 모델은 답하기 전에 생각하므로 요청 하나가 몇 분씩 걸릴 수 있습니다. 예를 들면 다음과 같습니다.

gpt-6-sol, gpt-5.6-sol
gpt-5.4-pro, o3-pro (gpt-5.5-pro는 2026년 10월에 종료됨)
gemini-3.1-pro-preview

긴 출력은 스트리밍으로 받기

스트리밍하지 않는 요청은 답변 전체가 생성된 뒤에야 반환되므로, 읽기 타임아웃과 전체 생성 시간이 경쟁하게 됩니다. 스트리밍(stream=True)을 쓰면 출력이 생성되는 대로 도착합니다.

첫 데이터가 빠르게 도착하고 그 뒤로도 이벤트가 계속 들어옵니다.
읽기 타임아웃은 이벤트 사이의 간격만 감당하면 되므로 보통 90~120초면 충분합니다.
총 소요 시간은 같지만, 전체 답변을 기다리다 연결이 끊기는 일은 없어집니다.

스트리밍하지 않는다면 타임아웃을 300~600초로 두되, 생성이 길수록 실패할 확률이 높아진다는 점을 감안하세요.

긴 요청은 자동 재시도 끄기

OpenAI 공식 Python SDK는 타임아웃이나 일부 오류가 나면 기본적으로 두 번 재시도합니다. 이미지와 추론 요청은 max_retries를 0으로 설정하고 재시도 시점을 직접 정하세요.

Python
Node.js
cURL

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["LAOZHANG_API_KEY"],
    base_url="https://api.laozhang.ai/v1",
    max_retries=0,  # 자동 재시도 없음. 타임아웃으로 두 번 과금되는 일을 막습니다
)

response = client.chat.completions.create(
    model="gpt-6-sol",
    messages=[{"role": "user", "content": "이 코드의 시간 복잡도를 분석해 주세요"}],
    timeout=600,  # 추론 모델에 충분한 시간을 줍니다
)
print(response.choices[0].message.content)

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.LAOZHANG_API_KEY,
  baseURL: "https://api.laozhang.ai/v1",
  timeout: 600 * 1000, // 밀리초
  maxRetries: 0,
});

const response = await client.chat.completions.create({
  model: "gpt-6-sol",
  messages: [{ role: "user", content: "3,000자 분량의 기술 분석을 작성해 주세요" }],
});
console.log(response.choices[0].message.content);

# --max-time은 요청 전체의 제한 시간(초)입니다
curl https://api.laozhang.ai/v1/images/generations \
  -H "Authorization: Bearer $LAOZHANG_API_KEY" \
  -H "Content-Type: application/json" \
  --max-time 360 \
  -d '{"model": "gpt-image-2.5-flare-vip", "prompt": "A calm mountain lake at sunrise"}'

타임아웃을 늘려도 계속될 때

다음 순서로 점검하세요.

새 타임아웃이 적용되는지 확인

일부 프레임워크는 HTTP 클라이언트를 자체 타임아웃으로 감쌉니다. 실제 적용된 설정을 출력해 보고, 바꾼 값이 실제로 쓰이는 값인지 확인하세요.

모든 경유 지점 확인

생성 시간보다 타임아웃이 짧은 지점이 하나라도 있으면 그곳에서 먼저 연결이 닫힙니다. 지점마다 값을 늘리세요.

직접 운영하는 리버스 프록시: Nginx의 proxy_read_timeout 기본값은 60초입니다.
클라우드 로드 밸런서의 유휴 타임아웃
서버리스 함수의 최대 실행 시간
큐 워커의 작업별 타임아웃

타임아웃과 속도 제한 구분

연결이 끊기거나 읽기 타임아웃이 난 것은 충분히 기다리지 않았다는 뜻입니다. 429는 속도나 용량 제한이며 대기 시간과 무관합니다. 429는 백오프를 두고 몇 번 재시도하고, 계속되면 고객 지원에 문의하세요.

호출 로그에서 실제 소요 시간 확인

호출 로그에서 요청의 소요 시간과 청구액을 확인하고, 그보다 여유 있게 타임아웃을 설정하세요.

자주 묻는 질문

클라이언트가 타임아웃되어도 과금되나요?

업스트림 제공사가 생성을 끝냈다면 과금됩니다. 연결 끊김은 내 쪽에서만 일어난 일이고 게이트웨이와 제공사는 계속 진행합니다. 429나 503처럼 업스트림이 200이 아닌 응답을 반환하면 과금되지 않습니다. 실제 청구액은 호출 로그에서 확인하며, 환불과 잔액 조정은 이용약관을 따릅니다.

연결이 끊긴 뒤 ID로 이미지를 다시 받을 수 있나요?

아니요. 이미지 엔드포인트는 동기식이고 LaoZhang API는 생성 결과를 기본적으로 저장하지 않으므로, 끊긴 결과는 사라집니다. 비동기 방식이 필요하면 이미지 API는 작업 ID를 반환하나요?에 설명된 대로 백엔드에 작업 큐를 두세요.

타임아웃을 아주 길게 잡으면 부작용이 있나요?

과금은 사용량이나 호출 횟수에만 좌우되고 기다린 시간과 무관하므로 달라지지 않습니다. 다만 긴 연결은 워커나 풀 슬롯을 점유하므로, 부하가 높을 때는 이미지와 추론 요청을 별도 작업 큐에서 처리하세요.

사용 가이드

API 타임아웃 설정: 몇 초가 적당한가요?

권장 타임아웃

긴 출력은 스트리밍으로 받기

긴 요청은 자동 재시도 끄기

타임아웃을 늘려도 계속될 때

자주 묻는 질문

클라이언트가 타임아웃되어도 과금되나요?

연결이 끊긴 뒤 ID로 이미지를 다시 받을 수 있나요?

타임아웃을 아주 길게 잡으면 부작용이 있나요?

관련 문서

​권장 타임아웃

​긴 출력은 스트리밍으로 받기

​긴 요청은 자동 재시도 끄기

​타임아웃을 늘려도 계속될 때

​자주 묻는 질문

​클라이언트가 타임아웃되어도 과금되나요?

​연결이 끊긴 뒤 ID로 이미지를 다시 받을 수 있나요?

​타임아웃을 아주 길게 잡으면 부작용이 있나요?

​관련 문서

권장 타임아웃

긴 출력은 스트리밍으로 받기

긴 요청은 자동 재시도 끄기

타임아웃을 늘려도 계속될 때

자주 묻는 질문

클라이언트가 타임아웃되어도 과금되나요?

연결이 끊긴 뒤 ID로 이미지를 다시 받을 수 있나요?

타임아웃을 아주 길게 잡으면 부작용이 있나요?

관련 문서