이미지 생성 API를 TypeScript로 호출하는 방법

이미지 생성 API는 프로그램에서 실행한 작업을 통해 프롬프트를 이미지로 바꿉니다. Pipe2에서는 Image Generator를 시작하고, 반환된 실행 ID로 상태를 조회한 뒤, 완료된 실행의 에셋에서 이미지 URL을 읽습니다. 아래 TypeScript 예제는 현재 카탈로그에서 비용이 가장 낮은 유효한 모델과 품질 조합을 사용합니다.

TypeScript SDK로 이미지 생성하기

@pipe2-ai/sdk를 설치하고 Pipe2 개인 액세스 토큰을 실행 환경의 PIPE2_TOKEN에 넣은 다음 Node로 이 모듈을 실행하세요. 프롬프트는 하나의 피사체, 배경, 조명 방향만 명확히 지정해 첫 결과를 쉽게 평가할 수 있게 했습니다.

import { createClient } from '@pipe2-ai/sdk';

const input = {
  model: 'gpt-image-2',
  prompt: 'A small red paper boat on a rain-darkened stone step, soft morning light, editorial product photograph, no text.',
  quality: 'fast',
};
const client = createClient(process.env.PIPE2_TOKEN);
const { run_pipeline } = await client.RunPipeline({
  pipeline_slug: 'image-generator',
  input,
});

while (true) {
  const { pipeline_runs_by_pk: run } = await client.GetPipelineRun({
    id: run_pipeline.run_id,
  });
  if (run?.status === 'completed') {
    console.log(run.assets?.[0]?.url);
    break;
  }
  if (run?.status === 'failed') throw new Error(run.error_message ?? 'Image generation failed');
  await new Promise((resolve) => setTimeout(resolve, 3000));
}

프로그램 안의 파이프라인 요청은 다음 JSON과 정확히 같습니다.

{
  "pipeline_slug": "image-generator",
  "input": {
    "model": "gpt-image-2",
    "prompt": "A small red paper boat on a rain-darkened stone step, soft morning light, editorial product photograph, no text.",
    "quality": "fast"
  }
}

TypeScript SDK 문서에서 설치, 인증, 파이프라인 작업, 에셋 업로드, 구독, 크레딧 조회 방법을 확인할 수 있습니다.

실행, 폴링, 에셋 흐름 이해하기

RunPipeline은 파이프라인 슬러그와 JSON 입력 객체를 받습니다. 이미지가 완성될 때까지 연결을 열어 두지 않고 비동기 실행의 식별자를 반환합니다. run_pipeline.run_id를 저장해 두면 GetPipelineRun으로 최신 상태를 가져올 수 있습니다.

폴링 루프는 두 가지 종료 상태를 처리합니다. completed 실행에는 생성된 에셋이 포함될 수 있으며, 예제는 첫 번째 에셋 URL을 출력합니다. failed 실행에는 error_message가 있을 수 있으므로 실행 ID와 함께 기록하세요. 프로덕션 코드에는 전체 제한 시간을 두고 실행을 찾을 수 없는 경우도 오류로 처리해야 합니다. 실시간 업데이트가 필요하면 SDK의 비동기 이터러블인 WatchPipelineRun도 사용할 수 있습니다.

비용이 가장 낮은 유효한 요청으로 시작하기

예제는 gpt-image-2와 quality: 'fast'를 명시합니다. 현재 Image Generator 카탈로그에서 비용이 가장 낮은 유효한 조합이며, 모델의 저품질 생성 등급에 해당합니다. 최종 이미지에 더 많은 크레딧을 쓰기 전에 인증, 요청 형태, 폴링, 에셋 처리를 확인하는 데 알맞습니다.

fast는 비용을 낮추는 선택이지 첫 출력의 배포 품질을 보장하는 설정이 아닙니다. 더 큰 작업을 보내기 전에 같은 pipeline_slug와 input으로 EstimatePipelineCost를 호출하세요. 모델, 품질, 참조 이미지 수를 바꿀 때마다 다시 견적해야 하며 실제 비용은 활성 카탈로그를 기준으로 합니다.

이미지에 필요한 설정만 선택하기

프롬프트 하나면 충분합니다. Image Generator는 참조 이미지, 지원되는 참조 동영상 한 개, 화면비, 품질, 모델 선택, 프롬프트 개선 설정도 받을 수 있습니다. 지원 한도는 선택한 모델에 따라 다르므로 모든 엔진이 같은 미디어를 받는다고 가정하지 말고 파이프라인 스키마를 확인하세요.

텍스트만으로 생성할 때는 피사체, 구도, 조명, 스타일을 짧은 서술문으로 적습니다. 이미지 안에 그대로 들어가야 하는 문구는 따옴표로 감싸고 생성 후 반드시 교정하세요. 참조 자료를 쓸 때는 각 이미지의 역할과 유지할 특징을 분명히 밝힙니다. 공통 화면비는 1:1, 16:9, 9:16, 4:3, 3:4입니다.

Auto를 사용하면 Pipe2가 호환되는 엔진을 고릅니다. 제품이 문서화된 특정 기능에 의존하거나 조건을 통제한 비교를 할 때만 모델을 고정하세요. AI 이미지 생성기 비교에서는 프롬프트, 참조 자료, 프레이밍, 시도 횟수를 동일하게 유지하는 방법을 설명합니다.

토큰, 실패, 출력 URL을 안전하게 다루기

실행 환경에서 전달한 Pipe2 토큰으로 SDK 클라이언트를 만드세요. 토큰을 소스 코드에 넣거나 저장소에 커밋하거나 브라우저 로그에 노출해서는 안 됩니다. 요청에는 Pipe2 파이프라인 슬러그를 사용하며, 클라이언트가 모델 공급자의 별도 자격 증명을 보낼 필요는 없습니다.

폴링 전에 실행 ID를 저장하면 프로세스가 재시작되어도 같은 작업을 이어서 추적할 수 있습니다. 반환된 에셋 URL은 애플리케이션 데이터로 취급하세요. 오래 유지할 참조가 필요하면 저장하고, 배열의 0번 항목에 접근하기 전 에셋 존재 여부를 확인하며, 무한 재시도 대신 오류를 전달해야 합니다. 사용자 프롬프트와 참조 미디어에는 애플리케이션의 일반적인 권한, 모더레이션, 보관 규칙도 적용하세요.