이미지 호출 주의사항(모범 사례)

이미지 생성은 동기식 장시간 요청(일반적으로 10–60초)으로, 대화 인터페이스의 호출 방식과 다릅니다. 대량 호출 전에 이 페이지를 반드시 숙독하세요.

타임아웃과 재시도

• 클라이언트 타임아웃을 ≥120초로 설정하세요, HTTP 라이브러리 기본값인 30초는 생성이 완료되기 전에 연결을 끊습니다;
• 연결이 끊긴 요청은 업스트림에서 이미 과금 처리 중일 수 있습니다 — 실패 시 선차감된 크레딧은 자동으로 반환되지만, 즉시 집중적으로 재시도하지 마세요, 지수 백오프(5s → 15s → 45s)를 권장합니다;
• 429는 속도 제한이 트리거된 것을 의미하며, 처리 방법은 속도 제한과 429를 참조하세요.

모델과 화면 비율 선택

• 화면 비율/해상도는 모델명 접미사로 지정합니다(-portrait, -landscape, -2k, -4k 등), size 파라미터에 의존하지 마세요, 전체 규칙은 이미지 및 비디오 생성 모델을 참조하세요;
• 대량 처리 시나리오에서는 -fast 등급을 우선 사용하고, 프롬프트 검증 후 표준 등급으로 전환하여 정밀 조정하세요;
• 4K 모델은 가격이 더 높고 생성 속도가 느리므로, 최종 결과물 단계에서만 사용하세요.

결과 처리

• 반환된 이미지 URL은 유효 기간이 있으므로, 받은 즉시 자신의 오브젝트 스토리지에 저장하고 핫링크하지 마세요;
• base64로 반환될 경우 응답 본문이 크므로, 리버스 프록시와 게이트웨이의 body 크기 제한을 늘려야 합니다;
• 건당 과금: 성공 1회에 1회 차감, 실패(업스트림 오류/타임아웃) 시 차감되지 않습니다.

비용 제어

• 먼저 소량으로 프롬프트 템플릿을 검증하고, 안정화된 후 대량으로 확장하세요;
• 이미지 서비스를 위한 별도의 API 토큰을 생성하고 크레딧 한도를 설정하여, 프로그램 버그로 인한 예산 초과를 방지하세요;
• 각 차감 내역은 콘솔 “로그”에서 확인하거나, 로그 조회 API를 사용하여 대사할 수 있습니다.