Skip to main content
POST
https://sajuapi.dev
/
v1
/
fortunes
/
batch
배치 운세 생성
curl --request POST \
  --url https://sajuapi.dev/v1/fortunes/batch \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "profile_ids": [
    {}
  ],
  "fortune_type": "<string>",
  "fortune_date": "<string>",
  "model": "<string>",
  "webhook_url": "<string>"
}
'
v1 Enterprise API (Coming Soon)이 엔드포인트는 Enterprise 버전에서 제공될 예정입니다. 현재는 v0 API를 사용하세요.
여러 프로필의 운세를 한 번에 생성합니다. 최대 100개의 프로필에 대해 동시에 운세를 생성할 수 있습니다.
배치 요청은 비동기로 처리됩니다. 요청 즉시 batch_id가 반환되며, 완료 시 웹훅으로 알림을 받거나 상태를 폴링할 수 있습니다.

​
Request Body 파라미터

​
profile_ids
array
required
운세를 생성할 프로필 ID 배열입니다. 최소 1개, 최대 100개까지 지정할 수 있습니다.
​
fortune_type
string
required
운세 유형입니다. daily, yearly, monthly 중 하나입니다.
​
fortune_date
string
운세 날짜입니다. ISO 8601 형식(YYYY-MM-DD)입니다. 기본값은 오늘입니다.
​
model
string
default:"haiku"
사용할 AI 모델입니다. 배치 요청에서는 비용 효율성을 위해 haiku가 권장됩니다.
​
webhook_url
string
배치 완료 시 알림을 받을 웹훅 URL입니다. 설정하면 완료 시 POST 요청이 전송됩니다.

​
Response

​
성공

배치 요청이 접수되면 Batch 객체가 반환됩니다.

​
실패

상태 코드에러 타입설명
400validation_error요청 데이터가 유효하지 않음
401authentication_errorAPI 키가 유효하지 않음
413payload_too_large프로필 수가 100개를 초과함
429rate_limited요청 한도 초과

​
요청 예시

curl -X POST https://api.sajuapi.dev/v1/fortunes/batch \
  -H "X-API-Key: bs_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "profile_ids": [
      "prf_abc123",
      "prf_def456",
      "prf_ghi789"
    ],
    "fortune_type": "daily",
    "fortune_date": "2025-01-16",
    "model": "haiku",
    "webhook_url": "https://your-server.com/webhooks/batch-complete"
  }'

​
응답 예시

{
  "id": "batch_xyz789abc123",
  "status": "processing",
  "total_count": 3,
  "completed_count": 0,
  "failed_count": 0,
  "fortune_type": "daily",
  "fortune_date": "2025-01-16",
  "model": "haiku",
  "webhook_url": "https://your-server.com/webhooks/batch-complete",
  "created_at": "2025-01-16T09:00:00Z",
  "estimated_completion": "2025-01-16T09:02:00Z"
}

​
Batch 객체

필드타입설명
idstring배치 ID입니다. batch_ 접두사로 시작합니다.
statusstring상태입니다. pending, processing, completed, failed 중 하나입니다.
total_countinteger전체 프로필 수입니다.
completed_countinteger완료된 프로필 수입니다.
failed_countinteger실패한 프로필 수입니다.
fortune_typestring운세 유형입니다.
fortune_datestring운세 날짜입니다.
modelstring사용된 AI 모델입니다.
webhook_urlstring웹훅 URL입니다. 설정한 경우에만 반환됩니다.
created_atstring생성 시간입니다.
estimated_completionstring예상 완료 시간입니다.
completed_atstring완료 시간입니다. 완료 후에만 반환됩니다.
resultsarray결과 배열입니다. 완료 후에만 반환됩니다.

​
배치 상태 조회

배치 상태를 확인하려면 GET /v1/fortunes/batch/{batch_id}를 호출합니다. 
curl -X GET https://api.sajuapi.dev/v1/fortunes/batch/batch_xyz789abc123 \
  -H "X-API-Key: bs_live_xxx"

​
완료된 배치 응답

{
  "id": "batch_xyz789abc123",
  "status": "completed",
  "total_count": 3,
  "completed_count": 3,
  "failed_count": 0,
  "results": [
    {
      "profile_id": "prf_abc123",
      "fortune_id": "ftn_result1",
      "status": "success"
    },
    {
      "profile_id": "prf_def456",
      "fortune_id": "ftn_result2",
      "status": "success"
    },
    {
      "profile_id": "prf_ghi789",
      "fortune_id": "ftn_result3",
      "status": "success"
    }
  ],
  "completed_at": "2025-01-16T09:01:45Z"
}

​
웹훅 페이로드

배치 완료 시 설정된 webhook_url로 다음 페이로드가 전송됩니다. 
{
  "event": "batch.completed",
  "batch_id": "batch_xyz789abc123",
  "status": "completed",
  "total_count": 3,
  "completed_count": 3,
  "failed_count": 0,
  "completed_at": "2025-01-16T09:01:45Z"
}

​
사용 사례

​
매일 자정에 모든 사용자 운세 생성

// 매일 자정(KST)에 실행되는 크론 작업
async function generateDailyFortunes() {
  // 활성 사용자 프로필 ID 조회
  const profiles = await getActiveProfileIds();

  // 100개씩 배치 처리
  for (let i = 0; i < profiles.length; i += 100) {
    const batch = profiles.slice(i, i + 100);

    await fetch('/v1/fortunes/batch', {
      method: 'POST',
      headers: {
        'X-API-Key': process.env.API_KEY,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        profile_ids: batch,
        fortune_type: 'daily',
        model: 'haiku'
      })
    });
  }
}