API

Direct HTTP API

Call the generation engine without opening the desktop app.

Direct HTTP API

Call the same SorryAssets capability API used by DesktopCore. Direct HTTP does not require the desktop app, MCP, or a SorryAssets project.

Before You Call

payments.

plaintext sa- value is shown once.

put it in browser code, a mobile binary, logs, or a public repository.

Sign in at SorryAssets account.
Make sure the account has enough spendable credits. API keys cannot initiate
Create a key at API keys. Its
Keep the key in a server-side secret manager or process environment. Never

An API key is an account bearer credential, not a supplier credential or a per-model grant.

Contract

GET /v1/videos/{id}/content.

API origin: https://api.sorryassets.com.
OpenAI SDK base URL: https://api.sorryassets.com/v1.
Auth: Authorization: Bearer sa-your-key.
Basic model discovery: GET /v1/models.
Inputs, parameters, and retail prices: GET /v1/catalog.
Exact preflight price: POST /v1/estimate.
Images: POST /v1/images/generations and POST /v1/images/edits.
Videos: POST /v1/videos, GET /v1/videos/{id}, and
Exact settlement: GET /v1/usage?taskRef={id}.

The checked contract is https://sorryassets.com/openapi.yaml. Models, Images, and Videos use OpenAI-shaped wire fields. Catalog, estimate, usage, account, and Admin are SorryAssets product APIs.

Discover And Estimate

API_BASE=https://api.sorryassets.com
AUTH_HEADER="Authorization: Bearer ${SORRYASSETS_API_KEY:?set SORRYASSETS_API_KEY}"

curl -fsS -H "$AUTH_HEADER" "$API_BASE/v1/models"
curl -fsS "$API_BASE/v1/catalog"
curl -fsS -X POST "$API_BASE/v1/estimate" \
  -H "$AUTH_HEADER" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "seedance-2.0-fast",
    "parameters": {"prompt": "a clean studio product reveal", "duration": 5}
  }'

Public model ids are globally unique. Generation requests select only model. Do not send capability, provider, connection, upstream model, project id, local node id, or local path.

Generate An Image

Choose an image model from Catalog. size is an optional hint and is not limited to an incomplete Catalog enum. The selected model may honor it, choose a nearest/default output, or reject an unsupported value.

curl -fsS -X POST "$API_BASE/v1/images/generations" \
  -H "$AUTH_HEADER" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: logical-image-request-001' \
  -d '{
    "model": "gemini-3.1-flash-image",
    "prompt": "a lime green studio headset",
    "size": "1536x1024",
    "n": 1
  }' > image-response.json

jq -r '.data[0].b64_json' image-response.json \
  | openssl base64 -d -A -out result.image

Inspect the decoded bytes before choosing an extension. SorryAssets may return PNG, JPEG, or WebP and never exposes a supplier URL.

Image edits use image for one reference or ordered repeated image[] parts for multiple references. Do not combine the two field shapes:

curl -fsS -X POST "$API_BASE/v1/images/edits" \
  -H "$AUTH_HEADER" \
  -H 'Idempotency-Key: logical-image-edit-001' \
  -F 'model=gemini-3.1-flash-image' \
  -F 'prompt=replace the background with a clean white studio' \
  -F 'n=1' \
  -F 'image[][email protected]' \
  -F 'image[][email protected]' > image-edit-response.json

Create A Video With The OpenAI SDK

Use an official SDK version that still includes the Videos resource:

import os
import time
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["SORRYASSETS_API_KEY"],
    base_url="https://api.sorryassets.com/v1",
)

video = client.videos.create(
    model="seedance-2.0-fast",
    prompt="a precise tabletop camera move around a ceramic object",
    size="1280x720",
    seconds="5",
)

while video.status not in {"completed", "failed"}:
    time.sleep(2)
    video = client.videos.retrieve(video.id)

if video.status != "completed":
    raise RuntimeError(video.error)

content = client.videos.download_content(video.id)
content.write_to_file("result.mp4")

The current OpenAI Videos API and Sora 2 SDK surface are scheduled for retirement on 2026-09-24. SorryAssets keeps /v1/videos as its own resource family; the checked OpenAPI contract remains authoritative if a future OpenAI SDK removes these helpers.

Create And Download A Video With HTTP

The standard JSON shape supports a prompt-only request or one public HTTPS input_reference image:

curl -fsS -X POST "$API_BASE/v1/videos" \
  -H "$AUTH_HEADER" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: logical-video-request-001' \
  -d '{
    "model": "seedance-2.0-fast",
    "prompt": "continue the camera move from this frame",
    "size": "1280x720",
    "seconds": "5",
    "input_reference": {"image_url": "https://example.com/reference.png"}
  }' > video.json

VIDEO_ID=$(jq -r '.id' video.json)

while :; do
  curl -fsS -H "$AUTH_HEADER" "$API_BASE/v1/videos/$VIDEO_ID" > video.json
  STATUS=$(jq -r '.status' video.json)
  [ "$STATUS" = completed ] && break
  [ "$STATUS" = failed ] && { jq . video.json; exit 1; }
  sleep 2
done

curl -fsS -H "$AUTH_HEADER" \
  "$API_BASE/v1/videos/$VIDEO_ID/content" -o result.mp4
curl -fsS -H "$AUTH_HEADER" \
  "$API_BASE/v1/usage?taskRef=$VIDEO_ID" > usage.json

Video state contains no billing fields or output URL. Download is authenticated and owner-scoped. Save content promptly because SorryAssets keeps durable task and billing facts, not a permanent cloud copy of supplier bytes.

Role-Tagged Video References

Some Catalog models declare multiple image, video, or audio roles. The SorryAssets references extension preserves those real roles. In multipart, send a JSON manifest and one ordered field per entry:

curl -fsS -X POST "$API_BASE/v1/videos" \
  -H "$AUTH_HEADER" \
  -H 'Idempotency-Key: logical-video-request-002' \
  -F 'model=seedance-2.0-fast' \
  -F 'prompt=animate the first frame with the supplied soundtrack' \
  -F 'size=1280x720' \
  -F 'seconds=5' \
  -F 'references=[{"role":"reference_image","field":"reference_0"},{"role":"reference_audio","field":"reference_1"}];type=application/json' \
  -F '[email protected]' \
  -F '[email protected]' > video.json

Use only roles declared by the selected Catalog binding. references and input_reference are mutually exclusive. JSON references use ordered {"role":"...","url":"https://..."} objects and accept only public HTTPS destinations.

Idempotency And Errors

Images and Videos accept optional Idempotency-Key. Supply one for durable retries and reuse it only for identical normalized fields and media. A conflict fails before another reservation or supplier attempt. Desktop always persists and sends this identity.

Models, Images, and Videos use the OpenAI error envelope under error. Catalog, estimate, and usage use {code, message}. 401 means the account key is unavailable, 402 means the balance cannot fund the request, 409 is an idempotency conflict or content-not-ready result, and 429 may include Retry-After. provider_unavailable means every compatible hidden route failed before acceptance. Public errors never include supplier responses, URLs, credentials, routes, or diagnostics.

Direct HTTP does not write a Desktop project. The caller owns downloaded bytes and any lineage it keeps.

HTTP 直连接口

通过 HTTP 调用与 DesktopCore 相同的 SorryAssets 能力 API。HTTP 直连不需要桌面应用、MCP 或 SorryAssets 项目。

调用前准备

登录 SorryAssets 账户。
确认账户有足够的可用 credits。API Key 不能发起支付。
在 API 密钥页面创建密钥。以 sa- 开头的明文只显示一次。
把密钥保存在服务端密钥管理系统或进程环境中，不要写入浏览器代码、移动端安装包、日志或公开仓库。

API Key 是账户 bearer 凭证，不是上游凭证，也不是逐模型授权。

接口契约

API Origin：https://api.sorryassets.com。
OpenAI SDK Base URL：https://api.sorryassets.com/v1。
鉴权：Authorization: Bearer sa-your-key。
基础模型发现：GET /v1/models。
输入、参数与零售价：GET /v1/catalog。
精确预估：POST /v1/estimate。
图片：POST /v1/images/generations、POST /v1/images/edits。
视频：POST /v1/videos、GET /v1/videos/{id}、GET /v1/videos/{id}/content。
精确结算：GET /v1/usage?taskRef={id}。

经过版本管理的契约位于 https://sorryassets.com/openapi.yaml。Models、Images 和 Videos 使用 OpenAI 形状的字段。Catalog、estimate、usage、账户和 Admin 是 SorryAssets 产品接口。

发现与预估

API_BASE=https://api.sorryassets.com
AUTH_HEADER="Authorization: Bearer ${SORRYASSETS_API_KEY:?set SORRYASSETS_API_KEY}"

curl -fsS -H "$AUTH_HEADER" "$API_BASE/v1/models"
curl -fsS "$API_BASE/v1/catalog"
curl -fsS -X POST "$API_BASE/v1/estimate" \
  -H "$AUTH_HEADER" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "seedance-2.0-fast",
    "parameters": {"prompt": "a clean studio product reveal", "duration": 5}
  }'

公开模型 ID 全局唯一。生成请求只选择 model，不要提交 capability、provider、连接、上游模型、项目 ID、本地节点 ID 或本地路径。

生成与编辑图片

从 Catalog 选择图片模型。size 是可选提示，不受不完整的 Catalog 枚举限制。所选模型可以采用、取邻近值或默认值，也可以拒绝不支持的尺寸。

curl -fsS -X POST "$API_BASE/v1/images/generations" \
  -H "$AUTH_HEADER" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: logical-image-request-001' \
  -d '{
    "model": "gemini-3.1-flash-image",
    "prompt": "a lime green studio headset",
    "size": "1536x1024",
    "n": 1
  }' > image-response.json

jq -r '.data[0].b64_json' image-response.json \
  | openssl base64 -d -A -out result.image

请检查解码后的字节再决定扩展名。SorryAssets 可能返回 PNG、JPEG 或 WebP，不会暴露上游 URL。

图片编辑在单张参考图时使用 image，多张时使用有序重复的 image[] multipart 字段；两种字段形态不能混用：

curl -fsS -X POST "$API_BASE/v1/images/edits" \
  -H "$AUTH_HEADER" \
  -H 'Idempotency-Key: logical-image-edit-001' \
  -F 'model=gemini-3.1-flash-image' \
  -F 'prompt=replace the background with a clean white studio' \
  -F 'n=1' \
  -F 'image[][email protected]' \
  -F 'image[][email protected]' > image-edit-response.json

使用 OpenAI SDK 创建视频

使用仍包含 Videos 资源的官方 SDK 版本：

import os
import time
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["SORRYASSETS_API_KEY"],
    base_url="https://api.sorryassets.com/v1",
)

video = client.videos.create(
    model="seedance-2.0-fast",
    prompt="a precise tabletop camera move around a ceramic object",
    size="1280x720",
    seconds="5",
)

while video.status not in {"completed", "failed"}:
    time.sleep(2)
    video = client.videos.retrieve(video.id)

if video.status != "completed":
    raise RuntimeError(video.error)

content = client.videos.download_content(video.id)
content.write_to_file("result.mp4")

OpenAI 当前的 Videos API 与 Sora 2 SDK 接口计划于 2026-09-24 退役。SorryAssets 会把 /v1/videos 继续作为自己的资源族；如果未来 OpenAI SDK 删除这些方法，以 SorryAssets 的 OpenAPI 契约为准。

使用 HTTP 创建与下载视频

标准 JSON 可以只传提示词，也可以传一张公网 HTTPS input_reference：

curl -fsS -X POST "$API_BASE/v1/videos" \
  -H "$AUTH_HEADER" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: logical-video-request-001' \
  -d '{
    "model": "seedance-2.0-fast",
    "prompt": "continue the camera move from this frame",
    "size": "1280x720",
    "seconds": "5",
    "input_reference": {"image_url": "https://example.com/reference.png"}
  }' > video.json

VIDEO_ID=$(jq -r '.id' video.json)

while :; do
  curl -fsS -H "$AUTH_HEADER" "$API_BASE/v1/videos/$VIDEO_ID" > video.json
  STATUS=$(jq -r '.status' video.json)
  [ "$STATUS" = completed ] && break
  [ "$STATUS" = failed ] && { jq . video.json; exit 1; }
  sleep 2
done

curl -fsS -H "$AUTH_HEADER" \
  "$API_BASE/v1/videos/$VIDEO_ID/content" -o result.mp4
curl -fsS -H "$AUTH_HEADER" \
  "$API_BASE/v1/usage?taskRef=$VIDEO_ID" > usage.json

Video 对象不包含计费字段或输出 URL。下载需要鉴权并校验任务归属。请及时保存产物，SorryAssets 持久保存任务与计费事实，不永久托管上游字节。

带角色的视频参考素材

部分 Catalog 模型声明多种图片、视频或音频角色。SorryAssets 的 references 扩展会保留这些真实角色。multipart 请求使用一份 JSON 清单，并按顺序上传对应字段：

curl -fsS -X POST "$API_BASE/v1/videos" \
  -H "$AUTH_HEADER" \
  -H 'Idempotency-Key: logical-video-request-002' \
  -F 'model=seedance-2.0-fast' \
  -F 'prompt=animate the first frame with the supplied soundtrack' \
  -F 'size=1280x720' \
  -F 'seconds=5' \
  -F 'references=[{"role":"reference_image","field":"reference_0"},{"role":"reference_audio","field":"reference_1"}];type=application/json' \
  -F '[email protected]' \
  -F '[email protected]' > video.json

只能使用所选 Catalog binding 声明的角色。references 与 input_reference 互斥。JSON references 使用有序的 {"role":"...","url":"https://..."} 对象，只接受公网 HTTPS 地址。

幂等与错误

Images 与 Videos 都接受可选的 Idempotency-Key。需要可靠重试时应主动提供，并且只在标准化字段和媒体完全一致时复用。冲突会在再次预留余额或请求供应商之前失败。Desktop 会持久保存并发送这个身份。

Models、Images、Videos 使用 error 包裹的 OpenAI 错误结构。Catalog、estimate、usage 使用 {code, message}。401 表示账户 Key 不可用，402 表示余额不足，409 表示幂等冲突或产物尚未就绪，429 可能附带 Retry-After。provider_unavailable 表示所有兼容的隐藏路由都在受理前失败。公开错误不会包含上游响应、URL、凭证、路由或诊断信息。

HTTP 直连不会写入 Desktop 项目。调用方负责保存产物与自己的创作脉络。