ジョブ

画像と動画の生成は、ジョブとして実行されます。ジョブは、Sakuranbo AI がバックグラウンドで実行する生成のリクエストです。動画は、必ずジョブを返します。画像は、画像を返しますが、結果が間に合わないときはジョブを返します。チャットのリクエストはジョブではなく、結果を直接返します。

ジョブのエンドポイントはすべて、Authorization: Bearer で送る API キーが必要です。認証を参照してください。読み取れるのは、自分のアカウントのジョブだけです。

ジョブのステータスは、queued, in_progress, completed, failed, cancelled, expired のいずれかです。

• queued: ジョブを受理し、開始を待っています。
• in_progress: ジョブを実行中です。
• completed: ジョブが終わり、出力ファイルの準備ができています。
• failed: ジョブがエラーで止まりました。理由は error フィールドに入ります。
• cancelled: ジョブがキャンセルされました。
• expired: ジョブが制限時間内に終わりませんでした。

queued と in_progress は実行中のステータスです。残りの 4 つは最終のステータスで、最終のステータスになったジョブは、そこから変わりません。failed、cancelled、expired のジョブは課金されませんが、まれに例外があります。リクエストがモデルの提供元に届いたかどうかを Sakuranbo AI が確認できないときは、ジョブが upstream_error で failed になり、確保した金額は、課金されるかどうかを Sakuranbo AI が確認するまで確保されたままになります。確保されたままのときは、ジョブ ID を添えてサポートにお問い合わせください。

GET /v1/jobs/{id} は、ジョブを 1 件返します。ステータスが最終になるまで、数秒おきにポーリングします。

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 が入ります。動画を参照してください。

ポーリングの代わりに、webhook のイベントを受け取ることもできます。Webhookを参照してください。

完了したジョブのファイルは、outputs に入ります。各項目に、url、content_type、バイト数の bytes、expires_at が入ります。ファイルは expires_at まで保管されます。expires_at は、ジョブが完了してから 7 日後です。その時刻を過ぎると、outputs は空になり、ファイルは削除されます。

ファイルの url は、ジョブを取得するたびに同じ値で、expires_at まで使えます。GET /v1/files/{token} は、署名付き URL でファイルを配信します。URL の署名が認証情報の代わりになるため、API キーは不要です。expires_at まで、URL を知っていれば誰でもファイルをダウンロードできるため、URL は秘密として扱ってください。

• 403 は、URL が正しくない、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())

• レスポンスは、ジョブを含む 200 で、ジョブのステータスは cancelled です。
• ジョブのために確保していた金額は残高に戻り、課金されません。
• すでに cancelled のジョブをキャンセルしても、200 を返します。
• completed、failed、expired のジョブをキャンセルすると、400 と invalid_request を返します。error.details.status に現在のステータスが入ります。完了したジョブの課金は残ります。

POST /v1/videos/{id}/cancel は、動画を同じ方法でキャンセルします。

MCP サーバーには、同じデータを読み取るツール list_jobs と get_job があります。MCP サーバーを参照してください。

404 のレスポンスは、その ID のジョブがアカウントにないことを示します。すべてのコードは、エラーを参照してください。