GPT Image 2.5 API 출시. 이미지 생성과 편집을 시작하세요 →
PoYoPoYo
PoYo CLInpm 패키지 제공 중

PoYo 모델을 검색하고 실행하세요 터미널에서 바로.

API Key 없이 실시간 모델 카탈로그와 Schema를 확인할 수 있습니다. 채팅 스트리밍, 생성 제출, task_id 작업 복구가 필요할 때 인증하세요.

$npx -y @poyoapi/cli help
npm에서 보기GitHub문서 열기

3단계로 PoYo CLI 시작하기

먼저 CLI를 실행하고 models와 describe로 모델을 선택하세요. 모델 실행이나 계정 정보 조회가 필요할 때만 API Key가 필요합니다.

1

CLI 실행

전역 설치 없이 npx를 사용합니다. 공개 패키지는 Node.js 20 이상이 필요합니다.

node --version
npx -y @poyoapi/cli help
2

모델 선택

이 예시는 현재 사용 가능한 gpt-image-2 모델을 찾은 다음, 최신 입력 Schema와 공개 가격을 확인합니다. 두 명령 모두 API Key가 필요하지 않습니다.

npx -y @poyoapi/cli models image --q gpt-image-2 --limit 1
npx -y @poyoapi/cli describe gpt-image-2
3

인증 후 실행

API Key를 만든 다음 아래 세 명령을 순서대로 실행하세요. 유료 실행 전에 describe로 가격을 확인하세요. 생성 실패 시 크레딧을 차감하지 않습니다.

API Key 만들기

1. API Key 저장

예상 결과: CLI가 Key를 화면에 표시하지 않고 입력받은 뒤 저장 위치로 keyring 또는 config를 알립니다. 시스템 자격 증명 저장소를 사용할 수 없으면 현재 사용자의 PoYo 설정 파일을 사용합니다.

npx -y @poyoapi/cli auth login

2. 계정과 잔액 확인

예상 결과: 계정 정보와 사용 가능한 잔액이 표시됩니다. 401은 Key가 없거나 유효하지 않다는 뜻입니다.

npx -y @poyoapi/cli account

3. 가격 확인 후 실행

유료 요청입니다. 성공한 JSON 결과에는 task_id, 최종 상태, 출력 파일이 포함됩니다.

npx -y @poyoapi/cli run gpt-image-2 --prompt "cinematic product photo" --format json

모델 Schema를 CLI 인자로 변환하기

chat, run, submit 전에 CLI가 선택한 모델의 Schema를 읽고 각 필드를 모델 전용 인자로 변환합니다.

실행 전에 모델 확인

models는 공개 카탈로그를 보여 주고 describe는 Schema, 프로토콜, 실행 방식, Callback, 과금 정보를 반환합니다.

이 두 명령은 API Key가 필요 없습니다.

생성 프롬프트

Schema 문자열 필드를 일반 명령줄 값으로 전달합니다.

알 수 없는 옵션은 로컬에서 실패합니다. 전체 JSON Schema 검증은 API에서 수행됩니다.

지금 반환하고 나중에 복구

submit은 task_id를 즉시 반환합니다. task get은 상태를 읽고 task wait은 대기를 계속합니다.

비디오, 오디오, 3D 등 오래 걸리는 작업에 적합합니다.

CLI 출력 방식 제어하기

스트리밍 chat은 텍스트 또는 JSONL을 stdout에 출력합니다. 비스트리밍 명령은 table, JSON, JSONL, CSV로 반환하고 파일에도 저장할 수 있습니다.

CLI는 REST API와 동일한 endpoint와 과금 방식을 사용합니다.

작업에 맞는 명령 선택하기

모델 검색, 채팅, 생성, 작업 복구, 로컬 MCP 브리지는 각각 별도의 명령으로 실행합니다.

~/projects/poyo-demo
# 1. 모델 선택
$ npx -y @poyoapi/cli models image --q gpt-image-2 --limit 1

# 2. 생성된 명령 입력
$ npx -y @poyoapi/cli describe gpt-image-2
  prompt          string   required
  size            string   default: "1:1"
  output_format   string   enum: jpeg | png

# 3. 인증 후 실행
$ npx -y @poyoapi/cli run gpt-image-2 --prompt "cinematic product photo" --size 4:3 --output-format png --format json
{
  "task_id": "task_7f31b2",
  "status": "succeeded",
  "files": ["https://storage.poyo.ai/.../image.png"]
}

작업 수명 주기

task_id로 장기 작업 이어가기

PoYo는 기존 공개 작업 상태를 그대로 반환합니다. CLI가 시간 초과되거나 종료되어도 다시 제출하지 않고 같은 작업을 조회할 수 있습니다.

CLI Timeout은 백엔드 작업을 취소하지 않습니다. 중복 요청 대신 같은 task_id로 계속하세요.

장기 작업에는 submit
$ npx -y @poyoapi/cli submit gpt-image-2 --prompt "cinematic product photo" --format json

task_id task_7f31b2

$ npx -y @poyoapi/cli task wait TASK_ID --timeout 300 --format json

status succeeded

제한된 대기에는 run

run은 2초마다 폴링하며 기본 최대 90초 동안 기다립니다.

장기 작업에는 submit

task_id를 저장하고 다른 터미널이나 CI 단계에서 task get 또는 task wait을 사용합니다.

CLI, MCP, REST, Skill 중 선택하기

터미널과 CI에는 CLI, Agent 도구 호출에는 MCP, 애플리케이션에는 REST API, 반복 가능한 Agent 워크플로에는 Skill을 사용합니다.

PoYo CLI

개발자, 터미널, CI

사람이나 스크립트가 검색, 실행, 복구, 종료 코드를 필요로 할 때.

CLI 설치

MCP

AI Agent와 코딩 클라이언트

Agent가 하나의 연결에서 Schema, 가격, 도구를 발견해야 할 때.

MCP 보기

REST API

애플리케이션과 서비스

제품이 오케스트레이션, 스트리밍, 재시도, 트래픽을 직접 제어할 때.

문서 열기

PoYo Skill

반복 가능한 Agent 워크플로

Agent에게 인터페이스 외에 작업 지침과 안전 규칙도 필요할 때.

Skill 보기

PoYo CLI FAQ

명령이 아직 헷갈리나요? PoYo 지원팀에 문의→

터미널에서 첫 PoYo 모델을 실행하세요

먼저 공개 카탈로그를 살펴보고 모델을 실행할 준비가 되면 API Key를 만드세요.

API Key 만들기npm에서 보기