영상

Sakuranbo AI에서는 POST /v1/videos 엔드포인트로 영상을 생성합니다. 이 엔드포인트에는 Authorization: Bearer로 보내는 API 키가 필요합니다. 인증을 참고하세요. 본문은 JSON입니다.

영상은 생성에 시간이 걸리므로 이 엔드포인트는 결과를 기다리지 않습니다. 항상 작업과 함께 202를 반환합니다. 결과는 작업을 폴링하거나 웹훅 이벤트를 받아 확인합니다. 같은 Idempotency-Key로 요청을 다시 보내는 경우도 마찬가지이며, 작업이 이미 끝났어도 202를 반환합니다.

모델과 프롬프트를 보냅니다. 이 예시에서 사용하는 모델은 sakuranbo/cherry-1.0-pro입니다.

curl -X POST "https://api.sakuranbo.ai/v1/videos" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SAKURANBO_API_KEY" \
  -d '{
  "model": "sakuranbo/cherry-1.0-pro",
  "prompt": "Aerial shot gliding over a misty mountain lake at sunrise, gentle wind and birdsong",
  "duration": 5,
  "resolution": "1080p",
  "aspect_ratio": "16:9"
}'

const response = await fetch("https://api.sakuranbo.ai/v1/videos", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: `Bearer ${process.env.SAKURANBO_API_KEY}`,
  },
  body: JSON.stringify({
    "model": "sakuranbo/cherry-1.0-pro",
    "prompt": "Aerial shot gliding over a misty mountain lake at sunrise, gentle wind and birdsong",
    "duration": 5,
    "resolution": "1080p",
    "aspect_ratio": "16:9"
  }),
});
const data = await response.json();
console.log(data);

import os

import requests

response = requests.post(
    "https://api.sakuranbo.ai/v1/videos",
    headers={
        "Authorization": f"Bearer {os.environ['SAKURANBO_API_KEY']}",
    },
    json={
        "model": "sakuranbo/cherry-1.0-pro",
        "prompt": "Aerial shot gliding over a misty mountain lake at sunrise, gentle wind and birdsong",
        "duration": 5,
        "resolution": "1080p",
        "aspect_ratio": "16:9",
    },
)
print(response.json())

예시 모델의 입력 파라미터는 다음과 같습니다.

요청 본문에는 다음 필드가 있습니다.

표에 없는 파라미터나 범위를 벗어난 값은 400과 invalid_request를 반환합니다. error.param이 파라미터의 이름을 알려 주고, error.details.allowed, error.details.minimum, error.details.maximum이 유효한 값을 알려 줍니다.

보내는 필드에 따라 영상을 만드는 방식이 정해집니다.

• prompt만 보내면 텍스트로 영상을 생성합니다.
• first_frame을 보내면 이미지에서 영상을 시작합니다. last_frame도 보내면 영상이 이미지로 끝납니다. last_frame에는 first_frame이 필요합니다.
• reference_images를 보내면 이미지를 참조로 사용하는 영상을 생성합니다. 프롬프트가 첫 번째 이미지나 두 번째 이미지를 가리킬 수 있으므로 순서가 중요합니다. reference_images는 first_frame, last_frame과 함께 쓸 수 없습니다.

이미지는 PNG, JPEG, WebP, GIF 이미지의 공개 https URL이거나 data:image/...;base64, URI입니다. 데이터 URI는 URL보다 크기 제한이 작으므로 큰 이미지는 공개 URL로 보내세요. 서버는 작업을 만들기 전에 각 URL을 가져와 확인합니다. 리다이렉트를 따라가지 않으며, 자격 증명, IP 주소, 내부 호스트 이름이 들어 있는 URL은 거부합니다. 사용할 수 없는 이미지는 400과 invalid_request를 반환합니다. error.param이 필드의 이름을 알려 줍니다. URL이면 error.details.reason이 무엇이 잘못되었는지 알려 줍니다. 데이터 URI가 너무 크면 error.details.max_bytes가 허용 크기입니다.

202 응답은 작업에 polling_url과 eta_seconds 두 필드가 더해진 것입니다. object는 video입니다.

progress와 eta_seconds는 경과 시간을 바탕으로 한 추정치입니다. 마감 시한이나 과금의 근거로 사용하지 마세요. Location 헤더와 polling_url은 모두 영상을 가리킵니다.

status가 completed, failed, cancelled, expired 중 하나가 될 때까지 몇 초마다 GET /v1/videos/{id} 엔드포인트를 폴링하세요. polling_url은 이 요청의 URL입니다. 실패한 작업도 200을 반환하며 이유는 error에 있습니다. 상태는 작업을 참고하세요.

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

const response = await fetch("https://api.sakuranbo.ai/v1/videos/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/videos/job_0123456789abcdef0123456789abcdef",
    headers={
        "Authorization": f"Bearer {os.environ['SAKURANBO_API_KEY']}",
    },
)
print(response.json())

폴링을 피하려면 웹훅 엔드포인트를 등록해 job.succeeded, job.failed, job.cancelled 이벤트를 받으세요. 웹훅을 참고하세요.

제한 시간 안에 끝나지 않은 작업은 expired가 됩니다. 이 작업은 과금되지 않습니다.

모델 제공업체가 혼잡한 상황은 POST /v1/videos 엔드포인트의 HTTP 상태로 나타나지 않습니다. 나중에 작업의 error 필드에 코드 rate_limited 또는 concurrency_limited로 나타납니다. 잠시 기다린 뒤 영상을 다시 생성하세요.

모델 제공업체가 프롬프트나 참조 이미지를 그 내용을 이유로 거부할 수도 있습니다. 이 경우에도 HTTP 상태로 나타나지 않으며, 작업이 코드 content_policy_violation으로 실패합니다. 요금은 청구되지 않습니다.

완료된 작업의 outputs에는 항목이 하나 있습니다. 그 url은 API 키가 필요하지 않은 서명된 URL이며 expires_at까지 유효합니다. expires_at은 작업이 완료된 지 7일 뒤의 시각입니다. URL을 아는 사람은 누구나 그때까지 파일을 내려받을 수 있으므로 URL을 비밀로 취급하세요. expires_at이 지나면 파일이 삭제되므로 필요한 영상은 저장해 두세요.

API 키로 GET /v1/videos/{id}/content 엔드포인트를 호출할 수도 있습니다. 이 엔드포인트는 서명된 URL로 리다이렉트하여 응답하므로 클라이언트가 리다이렉트를 따라가야 합니다. 작업에 파일이 없으면 404를 반환하며 error.details.status가 작업의 상태입니다. 작업이 아직 실행 중이거나, 실패했거나, 취소되었거나, 만료된 경우와, 파일이 이미 삭제된 경우가 여기에 해당합니다.

GET /v1/videos 엔드포인트는 내 영상을 최신순으로 나열하며, 작업 목록과 같은 limit, cursor, status 파라미터를 받습니다. POST /v1/videos/{id}/cancel 엔드포인트는 대기 중이거나 실행 중인 영상을 취소합니다. 둘 다 작업 엔드포인트의 규칙을 따릅니다. 작업을 참고하세요.

원하는 값으로 Idempotency-Key 헤더를 보내세요. 같은 키와 같은 내용의 요청이 다시 오면 같은 작업을 받고 요금은 한 번만 청구됩니다. 같은 키로 다른 요청을 보내면 409와 idempotency_conflict가 반환됩니다. 키는 한정된 시간 동안 기억되며, 그 시간은 API 레퍼런스에 나와 있습니다.

요청이 받아들여지면 Sakuranbo AI는 예상 가격만큼을 잔액에서 확보합니다. 예상 가격은 duration과 resolution으로 계산합니다. 작업이 완료되면 resolution의 초당 가격으로 요청한 duration만큼 요금이 청구되며, 이는 확보했던 금액과 같습니다. 취소되거나 만료된 작업은 과금되지 않습니다. 실패한 작업도 보통은 과금되지 않으며, 확보했던 금액은 잔액으로 돌아옵니다.

드물게 Sakuranbo AI가 요청이 모델 제공업체에 도달했는지 확인하지 못하는 경우가 있습니다. 이때 작업은 upstream_error와 함께 실패하고, 확보한 금액은 Sakuranbo AI가 과금 여부를 확인할 때까지 확보된 상태로 남습니다. 계속 남아 있다면 작업 ID와 함께 지원팀에 문의하세요.

가격은 모델 카탈로그와 요금 페이지에서 확인하거나, 요청을 실행하기 전에 POST /v1/estimate 엔드포인트로 계산하세요. 비용 계산 API를 참고하세요.

429나 503 응답을 받으면 Retry-After 헤더에 표시된 초만큼 기다린 뒤 다시 시도하세요. 402 응답에는 balance 또는 key인 error.details.limit_source가 있습니다. 잔액과 API 키 사용 한도를 참고하세요. 전체 코드 목록은 오류를 참고하세요.