빠른 답변
APIYI를 통해 생성된 대부분의 이미지 및 동영상(Veo 3.1, Sora, Nano Banana, gpt-image-2-vip 등)은 Cloudflare와 같은 글로벌 CDN에 호스팅된 URL로 반환됩니다. 다운로드 속도가 느리거나 타임아웃이 발생하는 원인은 대개 다음 두 가지 중 하나입니다:- 사용자 서버에서 CDN으로 이어지는 네트워크 경로: 중국 본토에 있는 서버가 해외 CDN에 접속할 때는 국가 간 대역폭, ISP 라우팅, 로컬 DNS의 영향을 받습니다.
- 스토리지 측 문제: CDN 배후의 스토리지 노드가 느려지면 모든 경로가 영향을 받을 수 있습니다.
핵심 사항Cloudflare R2 리소스 URL은 일반적으로
*.r2.cloudflarestorage.com 형식이나 Cloudflare를 통해 프록시된 커스텀 도메인 형태를 띱니다. 다운로드 속도는 사용자 서버가 가장 가까운 Cloudflare 엣지 노드에 얼마나 효율적으로 연결될 수 있는지에 따라 결정됩니다.API 호출은 성공했지만 이미지가 다운로드되지 않습니까?
이미지 생성은 두 단계로 진행됩니다:- 프로그램이 APIYI API를 호출하여 이미지가 생성되고 URL이 반환됩니다
- 프로그램이 해당 URL에서 이미지를 다운로드합니다
- APIYI 로그에는 요청이 성공 및 과금됨으로 표시됩니다 — 이미지는 실제로 정상 생성되었습니다
- 프로그램에서
Read timed out또는Connection reset와 같은 오류를 보고하며, 오류 메시지의 호스트는api.apiyi.com가 아닌 이미지 도메인입니다 Read timed out는 연결은 수립되었으나 오랫동안 데이터가 수신되지 않았음을 의미합니다. 이는 “연결할 수 없음”과 동일하지 않으며, 이 오류 자체만으로는 어느 쪽에 문제가 있는지 알 수 없습니다
일반적인 원인
국경 간 혼잡
중국 본토의 서버가 해외 CDN에 연결할 때 피크 시간대에 국제 회선 출구에서 혼잡을 겪는 경우가 많아, 속도가 느려지거나 시간 초과가 발생합니다.
최적화되지 않은 ISP 라우팅
일부 클라우드 제공업체는 국제 트래픽을 미국 서부나 유럽을 경유하도록 라우팅하여 수십 밀리초의 불필요한 지연을 추가합니다.
부적절한 DNS 해석
로컬 DNS가 Cloudflare 호스트명을 가장 가까운 APAC 노드가 아니라 먼 엣지(예: 미국 서부)로 해석할 수 있습니다.
방화벽 / 보안 그룹 제한
일부 서버는 해외 IP 대역, port 443 또는 특정 CDN 도메인으로의 아웃바운드 트래픽을 제한하여 연결 품질을 저하시킵니다.
HTTP/2 및 연결 재사용
HTTP/2나 연결 재사용이 없는 클라이언트는 파일마다 TCP/TLS 핸드셰이크 비용을 지불합니다.
단일 스레드 다운로드
직렬 단일 스레드 다운로드는 CDN 멀티플렉싱의 이점을 누릴 수 없어 처리량이 낮게 유지됩니다.
문제 해결 단계
1
송신 IP 및 CDN 노드 확인
이미지 도메인이 Cloudflare를 통해 서비스되는 경우, 해당 도메인의 다음 세 줄을 확인하십시오:
/cdn-cgi/trace 경로를 통해 단일 명령으로 송신 IP 및 할당된 노드를 확인할 수 있습니다. Linux, macOS 및 Windows cmd에서 작동합니다:ip=(송신 IP), colo=(HKG, SIN, LAX, FRA 등의 노드 코드), loc=(지역).- 30초 이내에 출력이 없는 경우: 서버가 도메인에 전혀 연결할 수 없는 상태입니다. 단계 4와 5를 집중적으로 확인하십시오.
- 즉시 출력되는 경우: 연결 상태는 정상이므로 전송 단계에 문제가 있는 것입니다. 단계 3으로 이동하여 단계별 소요 시간을 확인하십시오.
2
노트북과 서버 비교
노트북과 서버에서 동일한 이미지 URL을 다운로드합니다(명령어는 단계 3 참조).
- 노트북은 빠르고 서버는 느린 경우: 서버의 네트워크 경로 문제일 가능성이 가장 높지만, 일부 경로에 대해서만 스토리지 측 성능이 저하되었을 수도 있습니다. 두 결과 모두 당사에 전송해 주십시오.
- 모든 환경에서 느린 경우: 스토리지 측 문제일 가능성이 가장 높습니다. 해당 URL과 함께 당사에 문의해 주십시오.
3
CDN 기본 네트워크 테스트
ping, mtr, traceroute을(를) 사용하여 지연 시간과 패킷 손실을 검사합니다:curl -o /dev/null -m 60 -w "total=%{time_total} speed=%{speed_download}\n" "https://speed.cloudflare.com/__down?bytes=5000000"
(Windows에서는 /dev/null을(를) NUL(으)로 대체하십시오). 이 역시 느리다면 서버의 송신 네트워크가 문제입니다. 이 작업은 빠르고 이미지 URL만 느리다면 결과를 당사에 전송해 주십시오.패킷 손실, 200ms 이상의 지연 시간, 또는 해외로 우회하는 경로는 모두 링크 수준의 문제를 나타냅니다.4
실제 다운로드 속도 측정
curl을(를) 사용하여 소요 시간과 처리량을 검사합니다:- Linux / macOS
- Windows cmd
-m 60을(를) 사용하면 curl이 60초 후에 중단되더라도 소요 시간을 출력하므로 무한 대기 상태에 빠지지 않습니다. -4 대신 -6(으)로 다시 실행해 보십시오. 특정 프로토콜만 지연되는 경우 정상 작동하는 프로토콜을 사용하도록 프로그램을 고정할 수 있습니다.다음 항목을 중점적으로 확인하십시오:time_namelookup: DNS 확인 소요 시간time_connect: TCP 연결 소요 시간time_appconnect: TLS 핸드셰이크 완료 시점(0은 핸드셰이크 실패를 의미)time_starttransfer: 첫 바이트 도달 시간(TTFB)size_download: 실제 수신된 바이트 수(0 또는 매우 작은 값은 연결되었으나 전송이 중단되었음을 의미)speed_download: 평균 처리량(바이트/초)
5
DNS 확인 결과 검사
6
서버 자체 확인
“어제는 작동했는데 오늘은 안 됨”과 같은 현상은 대개 서버에서 무언가가 변경되었음을 의미합니다. 각 항목을 확인하십시오:
- 클라우드 콘솔: 트래픽 쿼터가 소진되었는지, 대역폭이 제한되었는지, 계정이 연체 상태인지 확인하십시오.
- 다른 프로세스가 대역폭을 모두 점유하고 있는지 확인하십시오(Windows: 작업 관리자 → 성능 → 이더넷, Linux:
iftop,nload). - 보안 그룹 및 방화벽이 443 포트와 해외 IP 대역을 허용하는지, 최근 아웃바운드 규칙이 변경되었는지 확인하십시오.
- 프로그램이 응답하지 않는 프록시를 거치고 있는지 확인하십시오(
HTTP_PROXY/HTTPS_PROXY확인, Windows의 경우netsh winhttp show proxy도 확인).
해결 방법
옵션 1: 퍼블릭 DNS로 전환 (가장 간단)
많은 서버의 기본 DNS는 Cloudflare를 먼 노드로 연결합니다. 다음 퍼블릭 DNS 서버를 사용해 보십시오:옵션 2: 다운로드 방식 최적화
병렬 다운로드
여러 파일을 일괄 다운로드할 때는 대역폭을 최대한 활용할 수 있도록 병렬 다운로더(
aria2c -x 8, Python asyncio + httpx)를 사용하십시오.짧은 타임아웃 + 재시도
연결(connect) 및 읽기(read) 타임아웃을 분리하여 설정하고, 읽기 타임아웃은 30초 내외로 유지하며 3~4회 재시도하십시오. 멈춘 연결은 새로 연결하면 정상적으로 작동하는 경우가 많으므로 120초 동안 기다리는 것보다 훨씬 낫습니다.
연결 재사용
반복되는 핸드셰이크를 방지하기 위해 HTTP/2 또는 keep-alive(
httpx, requests.Session())를 지원하는 클라이언트를 사용하십시오.디스크로 직접 스트리밍
전체 파일을 메모리에 로드하는 대신 응답을 디스크로 직접 스트리밍하십시오.
timeout=120를 사용한 단순 일회성 다운로드는 지양하십시오. 연결이 중단되면 무의미하게 120초 동안 대기하게 되며 전체 생성 작업이 실패로 표시되어, 이미 생성되고 과금된 이미지를 낭비하게 됩니다.
옵션 3: 네트워크 연결 상태가 더 우수한 리전으로 이전
사용 환경에서 지원한다면 Cloudflare와의 연결성이 우수한 리전을 권장합니다:해외 (권장)
AWS / GCP / Azure / Cloudflare Workers는 모두 매우 낮은 지연 시간(일반적으로 10-50ms)으로 Cloudflare R2에 도달합니다.
중국: 프리미엄 DC
중국 본토에 반드시 배포해야 한다면 3망 BGP 및 프리미엄 국제 회선(CN2 GIA, CMI, AS9929)을 갖춘 DC를 선택하십시오.
홍콩 / 싱가포르
중국 본토와의 낮은 지연 시간(30-80ms) 및 우수한 APAC Cloudflare 연결성을 제공하는 좋은 절충안입니다.
저가형 VPS 지양
저가형 호스팅은 국제 아웃바운드(egress) 대역폭 정체가 심해 사용량이 몰리는 시간대에 수십 KB/s 수준까지 속도가 떨어질 수 있습니다. CDN 트래픽이 많은 워크로드에는 권장하지 않습니다.
옵션 4: 다른 호스트를 통한 릴레이 (최후의 수단)
서버에서 Cloudflare로 빠르게 접근하기 어렵고 리전을 변경할 수도 없는 경우:- 해외 서버를 릴레이로 사용: 해외 서버로 먼저 다운로드한 다음, 전용선/프리미엄 회선을 통해 다시 전송합니다.
- 자체 오브젝트 스토리지를 통한 릴레이: 에셋을 자체 OSS / COS / S3(예: 중국 리전 버킷)로 미러링한 후 해당 스토리지에서 서비스합니다.
- 프리웜 및 캐싱: 백엔드에서 한 번 다운로드한 후 후속 요청은 로컬 캐시에서 서비스합니다.
자주 묻는 질문
노트북에서는 빠른데 서버에서는 왜 느립니까?
노트북에서는 빠른데 서버에서는 왜 느립니까?
가정용 광대역 인터넷과 데이터센터의 국제 아웃바운드 회선 품질에는 상당한 차이가 있을 수 있으며, 이것이 가장 흔한 원인입니다.하지만 이것이 유일한 원인은 아닙니다. 스토리지 측 노드의 성능이 저하되면 특정 경로에만 영향을 미칠 수 있으며, 이 또한 “노트북은 빠르고 서버는 느린” 현상으로 나타날 수 있습니다. 이 현상만으로 단정 짓지 마시고, 위의 단계를 실행한 후 스토리지 측을 확인할 수 있도록 결과를 보내주시기 바랍니다.
오류 메시지에는 api.apiyi.com에 연결할 수 없다고 나오는데 세부 정보의 호스트는 이미지 도메인인 이유는 무엇입니까?
오류 메시지에는 api.apiyi.com에 연결할 수 없다고 나오는데 세부 정보의 호스트는 이미지 도메인인 이유는 무엇입니까?
해당 문구는 대개 사용자 프로그램에서 직접 조합하여 생성한 메시지입니다. 실제로 실패한 것은 이미지 다운로드이며, 생성 API 호출은 성공했습니다. 세부 정보에 표시된 호스트를 신뢰하시고, 두 종류의 오류 메시지를 분리하여 처리하는 것을 권장합니다.
DNS를 변경했는데도 여전히 느린 이유는 무엇입니까?
DNS를 변경했는데도 여전히 느린 이유는 무엇입니까?
DNS는 어떤 CDN 엣지로 확인(resolve)되는지에만 영향을 줍니다. 기저의 국제 대역폭이 이미 혼잡한 상태라면 DNS 변경만으로는 해결되지 않습니다. 리전을 변경하거나 해외 호스트를 경유(릴레이)하는 방법을 고려해 보십시오.
중국 본토에서 Cloudflare R2가 차단되어 있습니까?
중국 본토에서 Cloudflare R2가 차단되어 있습니까?
Cloudflare는 중국 본토에서 차단되지 않았지만, 피크 시간대에는 국제 아웃바운드 회선이 혼잡해질 수 있고 일부 인터넷 서비스 제공업체(ISP)가 최적이 아닌 경로를 사용하므로 접속 품질이 일정하지 않을 수 있습니다. 이는 R2만의 문제가 아닌 일반적인 국경 간 네트워크 문제입니다.
동영상 다운로드가 계속 실패합니다. 어떻게 해야 합니까?
동영상 다운로드가 계속 실패합니다. 어떻게 해야 합니까?
적절한 타임아웃 및 재시도 설정과 함께
aria2c 또는 wget -c처럼 이어받기를 지원하는 다운로더를 사용하십시오:APIYI에서 CDN URL 대신 Base64를 반환할 수 있습니까?
APIYI에서 CDN URL 대신 Base64를 반환할 수 있습니까?
동영상은 파일 크기가 커서(수십에서 수백 MB), Base64로 인코딩하면 약 33%의 오버헤드가 발생하며 이어받기도 지원되지 않습니다. 따라서 실제로 속도가 더 느려지고 대역폭이 낭비됩니다. 대용량 파일에는 Base64 사용을 권장하지 않습니다. 일부 이미지 엔드포인트에서는 Base64 응답을 지원하므로 관련 API 문서를 참조하십시오.
병목 지점이 CDN이 아니라 사용자의 네트워크임을 어떻게 확인합니까?
병목 지점이 CDN이 아니라 사용자의 네트워크임을 어떻게 확인합니까?
해외 호스트(AWS 도쿄, 싱가포르 등)에서 동일한
curl 테스트를 실행해 보십시오. 해외 호스트에서는 빠르지만 서버에서는 느리다면, 병목 지점은 CDN 자체가 아닌 서버와 Cloudflare 사이의 네트워크입니다.관련 문서
네트워크 프록시 설정
해외 네트워크 연결이 불안정할 때 사용할 수 있는 프록시 옵션입니다
APIYI 서버는 어디에 있습니까?
APIYI 서버 위치 및 지연 시간에 대해 알아봅니다
Veo 동영상 생성 API
동영상 API의 출력 형식 및 URL 유효 기간입니다
고객 지원 문의
문제가 해결되지 않으면 지원팀이 도와드리겠습니다
고객 지원팀 문의 시 공유해야 할 정보자가 점검으로 문제가 해결되지 않는 경우, 불필요한 문답 과정을 줄이기 위해 아래 항목을 한 번에 정리하여 보내주시기 바랍니다:
- 문제가 발생한 이미지 URL 및 생성 일시(또는 요청 ID)
- 전체
/cdn-cgi/trace출력 결과(노트북에서 1건, 서버에서 1건) curl단계별 타이밍 출력 결과(-4실행 결과 1건,-6실행 결과 1건)tracert/mtr출력 결과 및 5 MB 테스트 다운로드 결과- 사용 중인 서버의 클라우드 제공업체 및 리전
- 문제가 발생하기 시작한 대략적인 시점(시간대 포함, 예:
21:23 (UTC+8))