이미지 연동을 SeedRouter로 옮기기

이미지 API를 SeedRouter로 이전하려면 API 키와 기본 URL만 바꾸는 것이 아니라 요청과 응답의 규약을 확인해야 합니다. GPT Image 2는 익숙한 이미지 생성 필드를 쓰지만, 제출하면 작업 ID가 반환됩니다. 애플리케이션은 그 ID를 저장하고, 완료될 때까지 폴링하고, 완성된 이미지 URL을 읽어야 합니다.

의미 있는 최소 단위의 이전은 서버 측 코드에서 보내는 텍스트-이미지 요청 한 건입니다. 참조 이미지 편집, 마스크, 더 큰 배치로 넘어가기 전에 이것부터 통과시키세요. 새 경로가 같은 인수 검사를 통과할 때까지는 기존 연동을 그대로 사용할 수 있게 두세요.

어떤 전제를 바꿔야 하나요?

이미지 요청을 쓸 수 있는 파일로 바꾸는 코드를 찾으세요. 지금은 첫 응답에 이미지가 들어 있다고 기대하거나, base64 필드를 디코딩하거나, multipart 업로드를 쓰고 있을 수 있습니다. 이런 전제는 SeedRouter GPT Image 2 레퍼런스와 하나씩 대조해 확인해야 합니다.

그래서 기본 URL을 설정할 수 있는 동기식 Images SDK라 해도 그대로 갈아 끼울 수 있는 대체재가 아닙니다. 계속 필요한 모델 설정은 유지하되, 결과를 기다리고 소비하는 애플리케이션 코드는 바꾸세요.

코드를 옮기기 전에 요청 필드를 매핑하세요

model, prompt, size, quality, n부터 시작하세요. 모델 ID는 gpt-image-2를 씁니다. 크기는 1024x1024처럼 명시하거나 auto를 사용하세요. 기존의 별도 resolution 필드나 비율 문자열을 그대로 크기로 옮겨오지 마세요.

SeedRouter의 OpenAPI 문서가 검토에 도움이 됩니다. 호출부에서 보이는 인자만 확인하지 말고, SDK가 채워 넣는 값까지 포함해 애플리케이션이 실제로 보내는 필드를 비교하세요. 알 수 없는 필드는 거부됩니다.

이 모델에서 style, response_format, 설정 가능한 input_fidelity는 받아들여지는 요청 필드가 아닙니다. 범용 옵션 객체 안에 숨기지 말고 이런 전제를 제거하세요. 요청은 stream과 partial_images도 지원하지 않습니다. 이 연동에서 진행 상황을 알리는 수단은 작업 상태입니다.

출력 설정에는 의존 관계가 있습니다. 투명을 요청하면 PNG를 고르세요. output_compression은 JPEG일 때만 보내고 PNG에는 보내지 마세요. 압축 값 0은 유효하므로, 참/거짓 판정으로 기본값으로 바꿔 버리지 않도록 하세요. 기본 요청이 성공하는 것만으로는 드러나지 않는 작은 세부입니다.

동기 응답이라는 전제를 바꾸세요

다음 Node.js 예시는 요청 한 건을 제출하고 작업 ID를 출력합니다. SEEDROUTER_API_KEY는 서버에 설정하세요. 키를 브라우저 코드나 공개되는 환경 변수에 두어서는 안 됩니다.

const response = await fetch('https://api.seedrouter.ai/v1/images/generations', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SEEDROUTER_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'gpt-image-2',
    prompt: 'A cobalt-blue ceramic mug on a pale gray tabletop.',
    size: '1024x1024',
    quality: 'low',
    n: 1,
  }),
  signal: AbortSignal.timeout(60000),
});
const task = await response.json();
if (!response.ok) {
  // Preserve a task reference if one accompanies an uncertain submission.
  if (typeof task.id === 'string') console.log('Task reference:', task.id);
  throw new Error(`Submission needs review: HTTP ${response.status}`);
}
if (typeof task.id !== 'string' || !task.id) throw new Error('Missing task ID.');
console.log(task.id); // Persist this ID with your application's image record.

수동 스모크 테스트라면 ID를 출력하는 것만으로 충분합니다. 다만 애플리케이션에서는 사용자에게 제어를 돌려주기 전에 저장하세요. 그러면 사용자가 다른 화면으로 이동해도 이미지 레코드는 대기 상태로 남고, 나중에 확인해 결과를 되찾을 수 있습니다.

진행 상황은 같은 인증 헤더로 GET https://api.seedrouter.ai/v1/tasks/{id}를 호출해 확인합니다. completed이면 output.data[].url을 읽고, failed이면 문서화된 오류를 처리해 적절한 실패 상태를 보여 주세요. 진행 상황을 저장하는 실행 가능한 예시는 배치 제출과 폴링을 참고하세요.

이미지 다운로드 요청에는 API 키를 붙이지 마세요. 인증은 작업 API 호출에 속하며, 반환된 자산 URL을 따로 가져올 때 쓰는 것이 아닙니다.

참조 이미지와 마스크를 URL 입력으로 옮기기

기존의 로컬 파일 방식에는 준비 단계가 하나 더 필요합니다. 참조 이미지를 직접 관리하는 접근 가능한 HTTP(S) URL에 올려 두세요. 그런 다음 images: [{"image_url": "https://example.com/reference.png"}] 형태로 전달하고, 이 주소는 본인 것으로 바꾸세요. 파일 경로, blob: URL, base64 data URL, Files ID는 보내지 마세요.

그 URL이 브라우저 로그인 쿠키 없이도 열리는지 확인하세요. 로그인한 세션에서만 열리는 URL은 이 요청에 쓸 수 있는 참조 이미지가 아닙니다. 작업이 처리되는 동안 이미지 접근을 유지하고, 제출 직후에 권한을 회수하지 마세요.

마스크는 mask: {"image_url": "https://example.com/mask.png"} 형태로 지정하며 참조 이미지가 필요합니다. 첫 번째 참조 이미지와 크기가 같아야 합니다. 기존 편집 흐름을 옮기기 전에 미디어 입력 제약, 특히 파일 형식과 파일 크기를 모두 확인하세요.

이전 인수 테스트는 무엇을 다뤄야 하나요?

중단 상황을 포함해, 애플리케이션이 의존하는 동작을 테스트하세요. 이미지 한 장이 성공했다는 것은 그 요청 하나가 동작했다는 뜻일 뿐입니다. 대기 상태가 새로고침을 견딘다거나, 다운로드 실패 시 중복 생성을 피한다는 것을 증명하지는 않습니다.

• 텍스트 전용 요청을 제출하고, 폴링 전에 반환된 ID를 저장한다.
• 폴링을 멈췄다가 같은 ID로 재개하고, 추가 POST가 발생하지 않는지 확인한다.
• processing, completed, failed를 서로 다른 상태로 처리한다.
• API 인증 헤더를 보내지 않고 완료된 이미지를 내려받는다.
• 접근 가능한 URL로 참조 이미지 편집을 확인하고, 접근할 수 없는 URL로 실패 처리를 확인한다.
• 압축 값 0을 포함한 선택 필드를 공개된 스키마로 검증한다.
• 계정 청구액을 지어낸 작업 응답 비용 필드가 아니라 사용 내역에서 읽는지 확인한다.

반복 가능한 실패·시간 초과 테스트에는 모의 응답을 사용하세요. 이 검사들을 통과한 뒤에야 의도적으로 작은 실제 테스트를 하세요. 실제 생성은 잔액을 소모합니다. 제출 결과가 불확실하면 재시도 전에 먼저 조사하세요. 로컬에서 예외가 났다는 것은 작업이 접수되지 않았다는 증거가 아닙니다.

자주 묻는 질문

기존 프롬프트를 그대로 쓸 수 있나요?

요청 제약을 충족한다면 출발점으로는 쓸 수 있습니다. 비교용으로 대표적인 프롬프트를 몇 개 남겨 두되, 반복 생성에서 동일한 이미지를 기대하지는 마세요.

새 클라이언트 라이브러리가 필요한가요?

여기의 예시에는 필요 없습니다. 표준 HTTP 요청이면 충분합니다. 어떤 클라이언트를 고르든, 완성 이미지를 즉시 기대하는 대신 작업 제출과 폴링을 처리할 수 있어야 합니다.

최종 비용은 어디서 확인하나요?

계정 사용 내역에서 확인합니다. 완료된 작업에 토큰 사용량이 포함될 수 있지만, 공개 응답에 금액 필드는 없습니다. 추정 방법은 요금 가이드에서 다룹니다.

애플리케이션 경계에서 이전을 마무리하세요

이미지 API 이전은 애플리케이션이 결과의 전체 수명 주기를 다룰 때 완료됩니다. 접수된 작업, 대기 상태, 완성된 출력, 다운로드, 그리고 실패입니다. 첫 변경은 작게 유지하고, 중단 상황을 테스트하고, 입력과 출력 전제를 확인한 뒤에야 남은 요청을 옮기세요.