> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apiyi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 프록시 환경에서 이미지 호출이 약 90초 후 끊기나요?

> VPN이나 프록시를 켠 상태로 로컬에서 개발할 때, 타임아웃을 아무리 길게 설정하더라도 이미지 요청이 90~180초 후에 일괄적으로 끊기며 과금은 그대로 진행됩니다. 프록시가 데이터가 전송되지 않는 연결을 종료하기 때문입니다. api.apiyi.com을 직접 연결로 라우팅하여 이 문제를 해결하십시오.

## 증상

로컬 컴퓨터에서 VPN 또는 프록시 클라이언트를 실행한 상태로 이미지 생성 앱을 개발하거나 디버깅하고 있습니다(많은 개발자가 AI 코딩 도구의 인터넷 접속을 위해 이를 켜 둡니다). 이때 다음과 같은 증상이 나타납니다.

* 이미지 요청이 `socket hang up`, `ECONNRESET`, `RemoteDisconnected` 또는 `Connection aborted`와 같은 연결 오류로 자주 실패합니다.
* 클라이언트 타임아웃을 600초나 심지어 900초로 설정했음에도 약 **90\~180초** 후에 요청이 끊어집니다.
* 여러 요청이 마치 한 번에 끊긴 것처럼 **동시에 실패**하는 경우가 많습니다.
* 처리 속도가 느린 모델일수록 더 자주 영향을 받습니다(예: 이미지당 보통 60\~120초가 소요되는 `gpt-image-2-vip`).
* [호출 로그](/ko/faq/call-logs)에서는 **이러한 요청 대부분이 성공하여 과금된 것으로 표시됩니다**.

## 빠른 답변

<Info>
  **이는 동시 실행 수 제한이나 APIYI 타임아웃이 아닙니다. 컴퓨터의 프록시가 일정 시간 동안 데이터가 전송되지 않은 연결을 닫고 있는 것입니다.**

  이미지가 생성되는 동안에는 연결을 통해 데이터가 전혀 전송되지 않습니다. 이미지 생성에 시간이 오래 걸릴수록 프록시가 해당 연결을 유휴 상태로 간주하여 닫을 가능성이 높아집니다. `api.apiyi.com`을(를) 직접 라우팅(프록시 우회)하면 문제가 해결됩니다. APIYI는 중국 본토에서 직접 접속할 수 있습니다.
</Info>

## 발생 원인

스트리밍을 사용하지 않는 이미지 요청은 세 단계로 진행됩니다:

1. **업로드**: prompt와 참조 이미지를 전송하며, 몇 초에서 수십 초 정도 소요됩니다.
2. **대기**: 서버에서 이미지를 생성하며, 보통 60\~200초가 걸립니다. **이 시간 동안 연결을 통해 오가는 데이터는 없습니다.**
3. **다운로드**: 완결된 이미지가 한 번에 반환됩니다.

문제는 2단계입니다. 리소스를 확보하기 위해 프록시 클라이언트와 프록시 서버는 모든 연결에 유휴 타임아웃(idle timeout)을 설정합니다. 해당 시간 동안 양방향으로 데이터가 이동하지 않으면 연결이 종료됩니다. 널리 사용되는 Xray / V2Ray 코어에서 해당 설정은 `connIdle`이며 기본값은 300초이지만, **프록시 서버 운영자가 이를 훨씬 낮게 설정할 수 있으며**, 사용자의 컴퓨터에서는 이를 확인하거나 변경할 수 없습니다. 당사에서 조사한 사례에서는 이 값이 약 90초였습니다.

그 결과 다음과 같은 현상이 발생합니다:

* **클라이언트 타임아웃 설정으로는 해결할 수 없습니다.** 타임아웃은 프로그램이 대기할 의향이 있는 시간만을 지정합니다. 중간의 프록시가 먼저 연결을 종료하므로, 프로그램 입장에서는 연결이 끊어진 것으로만 나타납니다.
* **요청이 한꺼번에 실패하는 이유**: 프록시는 일반적으로 타이머에 맞춰 너무 오랫동안 유휴 상태였던 모든 연결을 한 번에 정리하므로, 이미지를 기다리던 여러 요청이 같은 초에 동시에 실패합니다.
* **채팅 및 코딩 도구가 정상 작동하는 이유**: 스트리밍 채팅은 데이터를 지속적으로 전송하므로 연결이 유휴 상태가 되지 않습니다. 반면 이미지 생성은 몇 분 동안 아무런 데이터도 전송하지 않습니다.

<Warning>
  **연결이 끊긴 요청도 대개 정상적으로 과금됩니다.** 요청이 이미 APIYI에 도달하여 생성이 시작된 상태입니다. 연결이 끊어져도 작업이 중단되지 않으므로 이미지는 정상 생성되어 과금되지만, 그 결과가 프로그램에 전달되지 못할 뿐입니다. 프로그램의 오류 횟수를 세는 대신 [호출 로그](/ko/faq/call-logs)에서 실제 과금 내역을 확인하시기 바랍니다.
</Warning>

## 확인 방법

<Steps>
  <Step title="소요 시간 확인">
    오류가 발생하기 전까지 실패한 각 요청의 실행 시간을 기록합니다. 소요 시간이 특정 고정값(예: 90초 또는 180초) 부근에 집중되어 있고 여러 요청이 **동일한 초**에 실패하는 경우가 빈번하다면, 프록시 유휴 타임아웃(idle timeout)이 원인일 가능성이 거의 확실합니다.
  </Step>

  <Step title="호출 로그와 비교">
    [호출 로그](/ko/faq/call-logs)에서 동일한 시간대를 조회합니다. 프로그램에서는 연결 끊김이 보고되었으나 로그에는 성공 및 과금된 요청으로 표시된다면, APIYI가 이미지 생성을 완료했으나 사용자에게 전달되는 연결이 끊어진 것입니다.
  </Step>

  <Step title="직접 경로로 소규모 배치 실행">
    아래 설명에 따라 `api.apiyi.com` 경로를 직접 연결하고 동일한 파라미터로 10\~20개의 이미지를 실행합니다. 연결 끊김 현상이 사라진다면 프록시가 원인이었던 것입니다.
  </Step>
</Steps>

## 해결 방법

<Tabs>
  <Tab title="프록시 클라이언트의 직접 연결 규칙(권장)">
    프록시 클라이언트에 APIYI에 대한 직접 연결 규칙을 추가하십시오. 다른 모든 트래픽은 계속 프록시를 통과하므로 AI 코딩 도구에는 영향을 주지 않습니다.

    Clash / Clash Verge / mihomo의 경우 설정 파일의 `rules` 최상단에 다음을 추가하십시오.

    ```yaml theme={null}
    rules:
      - DOMAIN-SUFFIX,apiyi.com,DIRECT
      # ... your existing rules
    ```

    v2rayN 및 유사한 클라이언트의 경우 라우팅 설정의 직접 연결 목록에 `apiyi.com`을 추가하십시오.

    <Note>
      **TUN 모드 또는 글로벌 모드**에서는 프록시가 컴퓨터의 모든 프로그램 트래픽을 캡처하므로 코드에서 이를 우회할 수 없습니다. 이와 같은 직접 연결 규칙을 추가하는 것만이 유일한 해결 방법입니다.
    </Note>
  </Tab>

  <Tab title="프로그램 내에서 프록시 우회">
    프록시가 시스템 프록시 또는 환경 변수 프록시로만 설정되어 있는 경우(TUN 모드가 꺼져 있는 경우), 프로그램에서 이를 건너뛸 수 있습니다.

    ```bash theme={null}
    # Set before running your program so APIYI domains bypass the proxy
    # macOS / Linux
    export NO_PROXY="api.apiyi.com,.apiyi.com"
    # Windows PowerShell
    $env:NO_PROXY="api.apiyi.com,.apiyi.com"
    ```

    * **Python `requests` / `httpx`**: 시스템 프록시를 자동으로 읽습니다. 이를 비활성화하려면 `trust_env=False`을 설정하십시오. 코드는 [스크립트에서 502가 발생하지만 호출 로그에는 아무것도 없습니까?](/ko/faq/proxy-empty-502)를 참조하십시오.
    * **Node.js**: 기본 내장된 `fetch`은 기본적으로 시스템 프록시를 읽지 않습니다. `HTTPS_PROXY`을 `ProxyAgent`, `global-agent` 또는 유사한 라이브러리와 함께 사용하는 경우 `api.apiyi.com`을 제외하십시오. `axios`의 경우 요청 시 `proxy: false`을 전달하십시오.
  </Tab>

  <Tab title="프록시를 반드시 사용해야 하는 경우">
    자체 호스팅 프록시 서버에서만 설정을 변경할 수 있습니다. 유휴 타임아웃을 600초 이상으로 늘리십시오(Xray / V2Ray에서는 `policy.levels.<level>.connIdle` 설정). 타인이 운영하는 서버인 경우 이를 변경할 수 없으므로 직접 연결 경로를 설정하는 것이 여전히 더 나은 방법입니다.
  </Tab>
</Tabs>

## 서버에 배포한 후에도 이 문제가 발생합니까?

**일반적으로는 발생하지 않습니다.** 서버는 보통 프록시 없이 실행되며 APIYI에 직접 연결되므로, 유휴 연결을 닫는 프록시가 존재하지 않습니다. 이는 권장되는 프로덕션 환경 구성이기도 합니다. 중국 본토의 클라우드 서버에서도 `api.apiyi.com`에 직접 접근할 수 있습니다.

서버와 APIYI 사이에 다른 계층이 존재한다면 해당 계층에도 유휴 타임아웃이 적용됩니다. 배포 시 다음 항목을 확인하십시오:

| 계층 | 일반적인 기본값 | 참고 사항 |
| - | - | - |
| 클라우드 NAT 게이트웨이 / 로드 밸런서 | Azure: 4분, AWS NAT 게이트웨이: 350초 | 서버에 공인 IP가 없어 NAT를 통해 아웃바운드 트래픽이 나갈 때만 적용되며, 대부분 콘솔에서 제한을 늘릴 수 있습니다 |
| 자체 Nginx 리버스 프록시 | `proxy_read_timeout` 기본값 60초 | 서비스와 APIYI 사이에 Nginx를 배치했다면 이 값을 늘려야 합니다. [API 타임아웃을 방지하려면 어떻게 해야 합니까?](/ko/faq/timeout-configuration)를 참고하십시오 |
| 서버에 설치된 프록시 | 프록시 설정에 따라 다름 | 로컬 개발 환경과 동일한 문제입니다. APIYI로 직접 라우팅하십시오 |

단일 이미지 작업은 대개 클라우드 NAT 기본값보다 짧은 60\~200초 이내에 완료됩니다. 자체 리버스 프록시를 추가했거나 서버 역시 프록시를 거치도록 구성된 경우에만 추가 작업이 필요합니다.

## 자주 묻는 질문

<AccordionGroup>
  <Accordion title="TCP keepalive를 활성화하면 도움이 됩니까?">
    클라우드 NAT 게이트웨이 환경에서는 도움이 됩니다. keepalive 프로브가 NAT에 연결이 여전히 유지되고 있음을 알리기 때문입니다. 그러나 실제 데이터를 기준으로 유휴 상태를 판단하는 프록시 클라이언트에는 거의 효과가 없으며, keepalive 프로브는 데이터로 간주되지 않습니다. 로컬 개발 환경의 경우에는 직접 라우팅하는 것이 여전히 올바른 해결책입니다.
  </Accordion>

  <Accordion title="웹 콘솔과 AI 코딩 도구는 왜 정상적으로 작동합니까?">
    해당 도구들의 요청은 빠르게 반환되거나 출력을 지속적으로 스트리밍하므로 연결이 90초 이상 유휴 상태로 유지되지 않습니다. 몇 분 동안 아무것도 전송하지 않다가 한 번에 모든 결과를 반환하는 이미지 생성과 같은 요청에서만 이 문제가 발생합니다.
  </Accordion>

  <Accordion title="이것은 빈 502 오류 문제와 동일합니까?">
    두 현상 모두 로컬 프록시로 인해 발생하지만 증상이 다릅니다. [빈 502 오류 사례](/ko/faq/proxy-empty-502)에서는 프록시가 본문 없는 502 오류를 임의로 생성합니다. 반면 이 문제에서는 이미지를 기다리는 동안 연결이 끊어지며 프로그램에는 연결 끊김 현상으로 나타납니다. 두 경우 모두 해결 방법은 동일합니다. APIYI 요청이 프록시를 거치지 않도록 설정하는 것입니다.
  </Accordion>

  <Accordion title="연결이 끊긴 요청에 대한 과금은 환불받을 수 있습니까?">
    이러한 연결 끊김은 APIYI가 이미 이미지를 생성하고 과금을 완료한 후 사용자와 APIYI 사이의 프록시에서 발생합니다. 금액이 큰 경우 시간대(시간대 정보 포함, 예: 16:30-17:00 (UTC+8))와 사용자 이름을 고객지원팀에 전달해 주시면 호출 로그를 함께 확인해 드리겠습니다.
  </Accordion>

  <Accordion title="이렇게 오래 기다리지 않고 호출할 수 있는 방법이 있습니까?">
    이미지 엔드포인트는 현재 동기 방식으로 반환되며 작업 ID 폴링을 지원하지 않습니다. 자세한 내용은 [비동기 이미지 API가 있습니까? 작업 ID로 결과를 조회할 수 있습니까?](/ko/faq/image-async-api)를 참고하십시오. APIYI로 직접 라우팅되면 오랜 대기 시간 자체는 문제가 되지 않습니다.
  </Accordion>
</AccordionGroup>

## 관련 문서

<CardGroup cols={2}>
  <Card title="스크립트에서 502 오류가 발생하지만 호출 로그에는 아무것도 없습니까?" icon="unplug" href="/ko/faq/proxy-empty-502">
    로컬 프록시로 인해 생성된 빈 502 오류입니다. 시스템 프록시를 우회하여 해결하십시오.
  </Card>

  <Card title="API를 사용하는 데 프록시가 필요합니까?" icon="wifi" href="/ko/faq/network-proxy">
    중국 본토에서 직접 접속할 수 있으며 프록시나 VPN이 필요하지 않습니다.
  </Card>

  <Card title="API 타임아웃을 방지하려면 어떻게 해야 합니까?" icon="timer" href="/ko/faq/timeout-configuration">
    타임아웃 설정 및 단계별 문제 해결 방법
  </Card>

  <Card title="비동기 이미지 API가 있습니까?" icon="clock" href="/ko/faq/image-async-api">
    응답이 동기식인 이유와 이를 비동기 방식으로 래핑하는 방법
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.