API 빠른 시작

이미지 MOCK 작업으로 연동 흐름을 확인합니다.

1. API 키 준비

운영자가 등록한 고객 계정으로 콘솔에 로그인하세요. 개발 키에 사용할 프로필과 profiles:read, jobs:write, jobs:read, assets:read 권한을 지정합니다.

서버 환경 변수 · 셸 예시

export PAI_API_BASE="http://localhost:4100"
export PAI_API_KEY="YOUR_SERVER_SIDE_API_KEY"
export PAI_REQUEST_ID="YOUR_UNIQUE_REQUEST_ID"

예시 값은 실제 키가 아닙니다. API 기본 주소는 배포 환경에 맞게 바꾸고 키는 서버에서만 보관하세요.

2. 허용 프로필 확인

프로필 조회 · cURL

curl "$PAI_API_BASE/v1/profiles" \
  -H "Authorization: Bearer $PAI_API_KEY"

input_schema, output_schema, price_units를 확인하세요. 아래 예시는 seed의 product-image 프로필 기준입니다.

3. 작업 요청

이미지 작업 요청 · cURL

curl "$PAI_API_BASE/v1/jobs" \
  -H "Authorization: Bearer $PAI_API_KEY" \
  -H "Idempotency-Key: $PAI_REQUEST_ID" \
  -H "Content-Type: application/json" \
  --data '{
  "profile": "product-image",
  "input": {
    "product": {
      "name": "테스트 상품"
    }
  },
  "output": {
    "aspect_ratio": "portrait",
    "image_count": 1
  }
}'

HTTP 202 응답의 job_id를 저장하세요. 같은 입력을 재시도할 때 동일한 Idempotency-Key를 사용합니다. 다른 입력이면 새 키가 필요합니다.

접수 응답 · 형식 예시

{
  "code": "OK",
  "message": "요청을 처리했습니다.",
  "job_id": "<응답에서 받은 UUID>",
  "status": "QUEUED",
  "profile_version": 1,
  "execution_mode": "MOCK",
  "is_ai_generated": false,
  "request_id": "<서버 요청 ID>"
}

4. 상태와 결과 조회

작업 조회 · cURL

curl "$PAI_API_BASE/v1/jobs/$PAI_JOB_ID" \
  -H "Authorization: Bearer $PAI_API_KEY"

PAI_JOB_ID는 접수 응답의 값입니다. SUCCEEDED 상태에서 results[].asset_id를 확인합니다. FAILED·CANCELED는 완료 상태이며 RECONCILING은 대사 중입니다.

결과 다운로드 URL 발급 · cURL

curl "$PAI_API_BASE/v1/assets/$PAI_ASSET_ID/download" \
  -H "Authorization: Bearer $PAI_API_KEY"

PAI_ASSET_ID는 결과 asset ID입니다. 응답의 download_url은 만료되는 URL입니다. 현재 PNG·MP4 파일은 MOCK 테스트 결과입니다.

원본 업로드·SDK

파일은 업로드 권한 발급 → 파일 PUT → 업로드 확정 순서로 등록합니다. 전체 흐름은 저장소의 examples/mock-flow.ts와 pnpm sdk:example에서 확인하세요.

전체 API 안내