Grok Imagine API: Pipe2 SDK로 이미지 생성하기

Pipe2를 통해 Grok Imagine API를 사용하려면 Image Generator를 model: 'grok-imagine-image'로 실행하세요. 텍스트 프롬프트를 보내고, 반환된 실행 ID로 상태를 조회한 다음 생성된 이미지를 가져옵니다. 이 가이드는 Pipe2 API와 인증 방식을 사용하며, xAI API를 직접 호출하는 방법은 다루지 않습니다.

Grok 모델을 명시적으로 선택하기

파이프라인 슬러그는 image-generator이며, 모델 식별자는 input 안에 넣습니다. 기본 모델에는 grok-imagine-image, Grok Imagine Quality에는 grok-imagine-image-quality를 사용하세요. Auto는 다른 엔진을 선택할 수 있으므로 Grok이 필요한 경우 모델을 지정해야 합니다.

예제에서는 기본 모델을 사용하고 참조 이미지를 넣지 않으며 quality: 'fast'를 지정합니다. 이 작업 흐름을 보여 줄 수 있는 유효한 Grok 설정 중 비용이 가장 낮은 구성입니다. Fast는 1K 출력을, auto와 hd는 2K 출력을 선택합니다. 현재 기본 Grok 모델은 두 크기의 이미지 기본 가격이 같으므로 fast가 추가 할인을 제공하지는 않습니다. 참조 이미지를 넣으면 비용이 늘어납니다. 여러 요청을 실행하기 전에 같은 슬러그와 입력으로 EstimatePipelineCost를 호출하세요.

SDK 예제 실행하기

npm install @pipe2-ai/sdk로 패키지를 설치하세요. 아래 코드를 grok-image.mjs로 저장하고, 환경 변수 PIPE2_TOKEN에 Pipe2 개인 액세스 토큰을 설정한 뒤 node grok-image.mjs를 실행합니다. 계정에 충분한 크레딧이 있어야 합니다. 토큰은 서버에 보관하세요.

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

const token = process.env.PIPE2_TOKEN;
if (!token) throw new Error('Set PIPE2_TOKEN');
const client = createClient(token);
const input = {
  model: 'grok-imagine-image',
  prompt: 'A small red paper boat on a rain-darkened stone step, soft morning light, editorial photograph, no text.',
  quality: 'fast',
  enhance_prompt: false,
};
const { run_pipeline } = await client.RunPipeline({
  pipeline_slug: 'image-generator',
  input,
});

for (let attempt = 0; attempt < 60; attempt++) {
  const { pipeline_runs_by_pk: run } = await client.GetPipelineRun({
    id: run_pipeline.run_id,
  });
  if (!run) throw new Error('Run not found');
  if (run.status === 'failed' || run.status === 'cancelled') {
    throw new Error(run.error_message ?? run.status);
  }
  if (run.status === 'completed') {
    const url = run.assets?.[0]?.url;
    if (!url) throw new Error('Completed run has no image asset');
    console.log(url);
    process.exit(0);
  }
  await new Promise((resolve) => setTimeout(resolve, 3000));
}
throw new Error(`Polling timed out; resume with run ID ${run_pipeline.run_id}`);

이 코드에 해당하는 파이프라인 요청은 다음과 같습니다.

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

이 JavaScript 모듈이 사용하는 클라이언트는 TypeScript SDK 문서에서, 공개 API는 API 참조 문서에서 확인할 수 있습니다.

이미지가 완성될 때까지 실행 ID 보관하기

RunPipeline은 완성된 이미지가 아니라 실행 ID를 반환합니다. GetPipelineRun으로 상태와 출력 파일을 가져옵니다. 예제는 실패하거나 취소되면 중단하고, 완료된 실행에 파일이 있는지 확인한 뒤 첫 번째 이미지 URL을 출력합니다. 조회는 3초 대기 간격으로 최대 60회 수행합니다. 이는 애플리케이션의 설정이며 생성 시간을 보장하는 값이 아닙니다.

조회 시간이 초과되면 생성 요청을 중복으로 보내지 말고 같은 실행 ID로 조회를 재개하세요. 요청이 성공적으로 시작되면 즉시 ID를 저장합니다. 운영 환경에서는 네트워크 오류도 처리하고, 애플리케이션에 필요한 위치에 반환된 파일 참조를 보관해야 합니다.

필요한 경우에만 참조 이미지 추가하기

텍스트 프롬프트만으로도 충분합니다. 두 Grok 이미지 모델 모두 reference_images에 JPEG 또는 PNG 파일을 최대 3개까지 지원하며, 이미지당 최대 크기는 20 MB입니다. 이 파이프라인에서는 reference_videos를 받지 않습니다. 지원하는 화면 비율은 1:1, 16:9, 9:16, 4:3, 3:4이며, 예제는 기본 정사각형 구도를 사용합니다.

enhance_prompt: false를 지정하면 텍스트만 포함한 요청에서 생성 전에 프롬프트가 다시 작성되는 것을 막을 수 있습니다. 피사체, 배경, 구도, 조명을 설명하고 사용 전에 결과를 검토하세요. 구도를 더 구체적으로 계획하려면 Grok Imagine 프롬프트 가이드를 참고하세요. 참조 이미지를 추가할 때는 각 이미지의 역할을 설명하고 변경된 요청의 비용을 다시 추정해야 합니다.