任务

图像和视频的生成以任务的形式运行。任务是由 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 无法确认请求是否已到达模型提供方，任务会变为 failed，错误代码为 upstream_error，其预留金额会保持预留，直到 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 包含图像数量；对于视频任务，usage 为 null。
• 视频与其任务使用相同的 ID，因此 GET /v1/jobs/{id} 也会返回视频。视频响应额外包含 polling_url 和 eta_seconds 字段。详见视频。

你也可以接收 Webhook 事件来代替轮询。详见 Webhook。

已完成任务的文件在 outputs 中。每一项包含 url、content_type、以 bytes 表示的大小和 expires_at。文件保留到 expires_at，即任务完成后 7 天。此后 outputs 为空，文件已被删除。

文件的 url 在你每次获取任务时都相同，并且在 expires_at 之前有效。GET /v1/files/{token} 通过签名 URL 提供文件。它不需要 API 密钥，因为 URL 中的签名就是凭证。任何拿到该 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())

查询参数均为可选，筛选条件可以组合使用：

响应的 object 为 list，包含任务的 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 的任务。完整的错误代码列表请参阅错误。