작업

이미지와 영상 생성은 작업으로 실행됩니다. 작업은 Sakuranbo AI가 백그라운드에서 실행하는 생성 요청입니다. 영상은 항상 작업을 반환합니다. 이미지는 이미지를 반환하거나, 결과가 제시간에 준비되지 않으면 작업을 반환합니다. 채팅 요청은 작업이 아닙니다. 결과를 바로 반환합니다.

모든 작업 엔드포인트에는 Authorization: Bearer로 보내는 API 키가 필요합니다. 인증을 참고하세요. 내 계정의 작업만 읽을 수 있습니다.

작업의 상태는 queued, in_progress, completed, failed, cancelled, expired 중 하나입니다.

• queued: 작업이 받아들여졌고 시작을 기다리고 있습니다.
• in_progress: 작업이 실행 중입니다.
• completed: 작업이 끝났고 출력 파일이 준비되었습니다.
• failed: 작업이 오류로 중단되었습니다. 이유는 error 필드에 있습니다.
• cancelled: 작업이 취소되었습니다.
• expired: 작업이 제한 시간 안에 끝나지 않았습니다.

queued와 in_progress는 실행 중 상태입니다. 나머지 넷은 최종 상태이며, 작업은 최종 상태에서 벗어나지 않습니다. failed, cancelled, expired 작업은 과금되지 않으며, 드문 예외가 하나 있습니다. Sakuranbo AI가 요청이 모델 제공업체에 도달했는지 확인하지 못하면 작업은 upstream_error와 함께 failed가 되고, 확보한 금액은 Sakuranbo AI가 과금 여부를 확인할 때까지 확보된 상태로 남습니다. 계속 남아 있다면 작업 ID와 함께 지원팀에 문의하세요.

GET /v1/jobs/{id} 엔드포인트는 작업 하나를 반환합니다. 상태가 최종 상태가 될 때까지 몇 초마다 폴링하세요.

curl "https://api.sakuranbo.ai/v1/jobs/job_0123456789abcdef0123456789abcdef" \
  -H "Authorization: Bearer $SAKURANBO_API_KEY"

const response = await fetch("https://api.sakuranbo.ai/v1/jobs/job_0123456789abcdef0123456789abcdef", {
  headers: {
    Authorization: `Bearer ${process.env.SAKURANBO_API_KEY}`,
  },
});
const data = await response.json();
console.log(data);

import os

import requests

response = requests.get(
    "https://api.sakuranbo.ai/v1/jobs/job_0123456789abcdef0123456789abcdef",
    headers={
        "Authorization": f"Bearer {os.environ['SAKURANBO_API_KEY']}",
    },
)
print(response.json())

응답에는 다음 필드가 있습니다.

• 실패한 작업도 200을 반환합니다. error 필드에 오류 응답과 같은 필드로 이유가 들어 있고, cost는 null입니다.
• 잠시 동안 작업이 completed인데 cost가 아직 null일 수 있습니다. 비용이 필요하다면 cost에 값이 들어올 때까지 기다리세요.
• usage에는 이미지 작업이라면 이미지 수가 들어 있고, 영상 작업이라면 null입니다.
• 영상의 ID는 작업의 ID와 같으므로 GET /v1/jobs/{id} 엔드포인트는 영상도 반환합니다. 영상 응답에는 polling_url과 eta_seconds 필드가 더 있습니다. 영상을 참고하세요.

폴링 대신 웹훅 이벤트를 받을 수도 있습니다. 웹훅을 참고하세요.

완료된 작업의 파일은 outputs에 들어 있습니다. 각 항목에는 url, content_type, 바이트 단위 크기인 bytes, expires_at이 있습니다. 파일은 expires_at까지 보관되며, expires_at은 작업이 완료된 지 7일 뒤의 시각입니다. 그 시각이 지나면 outputs가 비고 파일은 삭제됩니다.

파일의 url은 작업을 조회할 때마다 같으며 expires_at까지 유효합니다. GET /v1/files/{token} 엔드포인트는 서명된 URL로 파일을 제공합니다. URL의 서명이 자격 증명이므로 API 키가 필요하지 않습니다. URL을 아는 사람은 누구나 expires_at까지 파일을 내려받을 수 있으므로 URL을 비밀로 취급하세요.

• 403은 URL이 유효하지 않거나, 변경되었거나, expires_at이 지났다는 뜻입니다. expires_at 전이라면 작업을 다시 조회해 유효한 URL을 읽으세요. expires_at 이후에는 파일이 삭제되어 outputs가 비어 있습니다.
• 404는 파일이 더 이상 저장되어 있지 않다는 뜻입니다.

이 엔드포인트는 Range 요청을 지원합니다.

GET /v1/jobs 엔드포인트는 내 작업을 최신순으로 나열합니다.

curl "https://api.sakuranbo.ai/v1/jobs?status=completed&limit=10" \
  -H "Authorization: Bearer $SAKURANBO_API_KEY"

const response = await fetch("https://api.sakuranbo.ai/v1/jobs?status=completed&limit=10", {
  headers: {
    Authorization: `Bearer ${process.env.SAKURANBO_API_KEY}`,
  },
});
const data = await response.json();
console.log(data);

import os

import requests

response = requests.get(
    "https://api.sakuranbo.ai/v1/jobs?status=completed&limit=10",
    headers={
        "Authorization": f"Bearer {os.environ['SAKURANBO_API_KEY']}",
    },
)
print(response.json())

쿼리 파라미터는 모두 선택 사항이며 필터는 함께 적용됩니다.

응답에는 list로 설정된 object, 작업의 data 배열, has_more, next_cursor가 들어 있습니다. has_more가 true이면 next_cursor를 cursor로 보내 다음 페이지를 읽습니다. data 배열이 비어 있으면 조건에 맞는 작업이 없다는 뜻이며 오류가 아닙니다.

POST /v1/jobs/{id}/cancel 엔드포인트는 queued 또는 in_progress 상태의 작업을 취소합니다. 본문은 없습니다.

curl -X POST "https://api.sakuranbo.ai/v1/jobs/job_0123456789abcdef0123456789abcdef/cancel" \
  -H "Authorization: Bearer $SAKURANBO_API_KEY"

const response = await fetch("https://api.sakuranbo.ai/v1/jobs/job_0123456789abcdef0123456789abcdef/cancel", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SAKURANBO_API_KEY}`,
  },
});
const data = await response.json();
console.log(data);

import os

import requests

response = requests.post(
    "https://api.sakuranbo.ai/v1/jobs/job_0123456789abcdef0123456789abcdef/cancel",
    headers={
        "Authorization": f"Bearer {os.environ['SAKURANBO_API_KEY']}",
    },
)
print(response.json())

• 응답은 상태가 cancelled인 작업과 함께 200입니다.
• 작업을 위해 확보했던 금액은 잔액으로 돌아오며 요금은 청구되지 않습니다.
• 이미 cancelled인 작업을 취소하면 다시 200을 반환합니다.
• completed, failed, expired 상태의 작업을 취소하면 400과 invalid_request를 반환합니다. error.details.status가 현재 상태입니다. 완료된 작업은 청구된 요금이 그대로 유지됩니다.

POST /v1/videos/{id}/cancel 엔드포인트도 같은 방식으로 영상을 취소합니다.

MCP 서버에는 같은 데이터를 읽는 도구 list_jobs와 get_job이 있습니다. MCP 서버를 참고하세요.

404 응답은 내 계정에 그 ID의 작업이 없다는 뜻입니다. 전체 코드 목록은 오류를 참고하세요.