Seedance 视频 API

Python 完整示例

Python 3.10+，无需安装第三方包。先设置上方环境变量，再下载 video_client.py 运行。默认生成 5 秒竖屏视频，结果保存为 out.mp4。

图片可选：Windows 设置 $env:VIDEO_IMAGE = "reference.png"；macOS / Linux 设置 export VIDEO_IMAGE="reference.png"。仅在新订单首次运行时读取图片和参数；已有状态文件继续原订单。需要修改提示词时，先修改代码中的请求体并为新订单更换状态文件名。

import base64, hashlib, http.client, json, os, shutil, time, uuid
import urllib.error, urllib.request
from pathlib import Path
from urllib.parse import urljoin

base = os.environ.get("VIDEO_API_BASE", "https://__ORIGIN__").rstrip("/")
key = os.environ.get("VIDEO_API_KEY", "").strip()
state_path = Path(os.environ.get("VIDEO_STATE", "order-001.json"))
output = Path(os.environ.get("VIDEO_OUTPUT", "out.mp4"))
agent = "vinted-video-client/1.0"
if not key.startswith("sk-") or key == "sk-your-key":
    raise SystemExit("Set VIDEO_API_KEY to your own sk- key first.")

class ApiError(SystemExit):
    def __init__(self, status, message):
        super().__init__(message)
        self.status = status

def save_state():
    temporary = state_path.with_suffix(state_path.suffix + ".tmp")
    temporary.write_text(json.dumps(state, ensure_ascii=False), encoding="utf-8")
    temporary.replace(state_path)

def call(method, path, body=None, idem=None, field=None):
    data = None if body is None else json.dumps(body).encode("utf-8")
    headers = {"Authorization": "Bearer " + key, "User-Agent": agent}
    if data is not None:
        headers["Content-Type"] = "application/json"
    if idem:
        headers["Idempotency-Key"] = idem
    for attempt in range(3):
        delay = 5 * (attempt + 1)
        req = urllib.request.Request(base + path, data=data, headers=headers, method=method)
        try:
            with urllib.request.urlopen(req, timeout=90) as response:
                result = json.load(response)
            if not isinstance(result, dict) or (field and
                    (not isinstance(result.get(field), str) or not result[field])):
                raise ValueError("empty or incomplete JSON response")
            return result
        except urllib.error.HTTPError as exc:
            raw = exc.read().decode("utf-8", "replace")
            try:
                detail = json.loads(raw)
            except ValueError:
                detail = {}
            error = detail.get("error", {}) if isinstance(detail, dict) else {}
            if not isinstance(error, dict):
                error = {}
            message = "HTTP %s: %s; request_id=%s" % (
                exc.code, error.get("message", raw[:300]),
                error.get("request_id", exc.headers.get("X-Request-ID", "")))
            retryable = (exc.code in {408, 429, 500, 502, 503, 504} or
                         (exc.code == 409 and error.get("type") in
                          {"idempotency_in_progress", "submission_reclaimed"}))
            if not retryable:
                raise ApiError(exc.code, message + "\nState kept: " + str(state_path))
            retry = exc.headers.get("Retry-After")
            if retry is None and isinstance(detail, dict):
                retry = detail.get("retry_after")
            try:
                delay = max(delay, float(retry))
            except (TypeError, ValueError):
                pass
        except (OSError, ValueError, http.client.HTTPException) as exc:
            message = str(exc)
        if attempt == 2 or delay > 60:
            raise SystemExit(message + "\nWait and rerun with the SAME VIDEO_STATE and API Key: " + str(state_path))
        time.sleep(delay)

# Persist the operation before the first creation request; never persist the key.
key_hash = hashlib.sha256(key.encode()).hexdigest()
if state_path.exists():
    state = json.loads(state_path.read_text(encoding="utf-8"))
    if state.get("base") != base or state.get("key_hash") != key_hash:
        raise SystemExit("This state belongs to a different base URL or API Key.")
else:
    state = {"base": base, "key_hash": key_hash, "operation_id": uuid.uuid4().hex,
             "image_path": os.environ.get("VIDEO_IMAGE", ""),
             "body": {"prompt": "A clean product showcase", "model": "seedance2.0fast",
                      "duration": 5, "ratio": "9:16"}}
    save_state()

def upload_reference():
    image = Path(state["image_path"]).read_bytes()
    digest = hashlib.sha256(image).hexdigest()
    if state.get("image_hash", digest) != digest:
        raise SystemExit("The reference image changed. Restore the original image to resume.")
    uploaded = call("POST", "/v1/files", {
        "image_b64": base64.b64encode(image).decode("ascii")
    }, field="image_id")
    state.update(image_hash=digest, image_expires_at=uploaded["expires_at"])
    state["body"]["image_ids"] = [uploaded["image_id"]]
    save_state()

if not state.get("job_id"):
    if state["image_path"] and not state["body"].get("image_ids"):
        upload_reference()
    try:
        job = call("POST", "/v1/videos", state["body"],
                   idem=state["operation_id"], field="id")
    except ApiError as exc:
        # Reconcile the original submission first. Only refresh an expired
        # upload after an explicit rejection, retaining the same operation.
        if (exc.status != 400 or not state["image_path"] or
                state.get("image_expires_at", float("inf")) > time.time()):
            raise
        upload_reference()
        job = call("POST", "/v1/videos", state["body"],
                   idem=state["operation_id"], field="id")
    state["job_id"] = job["id"]
    save_state()

job_path = "/v1/videos/" + state["job_id"]
print("job_id=" + state["job_id"], flush=True)
deadline = time.monotonic() + 1800
while time.monotonic() < deadline:
    current = call("GET", job_path, field="status")
    if current["status"] in {"succeeded", "failed"}:
        break
    if current["status"] not in {"queued", "running"}:
        raise SystemExit("Unexpected status: " + str(current["status"]))
    time.sleep(5)
else:
    raise SystemExit("Still pending; rerun with the SAME VIDEO_STATE to continue polling.")
if current["status"] != "succeeded":
    raise SystemExit("Generation failed: " + json.dumps(current, ensure_ascii=False))

# A signed URL needs no Authorization header and expires; mint it when needed.
signed = call("GET", job_path + "/signed_url?download=1", field="url")
url = signed["url"]
download = urljoin(base.rstrip("/") + "/", url)
part = output.with_name(output.name + ".part")
request = urllib.request.Request(download, headers={"User-Agent": agent}, method="GET")
with urllib.request.urlopen(request, timeout=600) as response, part.open("wb") as handle:
    if response.status != 200:
        raise SystemExit("download failed: %d" % response.status)
    shutil.copyfileobj(response, handle)
    expected = response.headers.get("Content-Length")
    if expected is not None and handle.tell() != int(expected):
        raise SystemExit("Incomplete download; rerun with the SAME VIDEO_STATE.")
part.replace(output)
print("saved " + str(output))

请求超时、空响应、临时错误最多自动重试 3 次；等待过久或需要充值时会退出并保留状态。重新运行可继续提交确认、轮询或下载，不会因为本地等待结束而新建订单。视频失败时以任务返回的 error 和实际账单为准。

接入须知

使用自定义视频 REST 接口，接入工具需支持自定义路径、JSON 请求体与异步轮询。

1. 基址 https://__ORIGIN__；业务接口都在 /v1 下。不要直连源站 IP。
2. 鉴权 每个受保护请求带请求头 Authorization: Bearer sk-your-key（Bearer 后有一个空格）。
3. 格式 JSON 请求使用 Content-Type: application/json；图片与视频读取返回二进制。视频请求发往 POST /v1/videos，不能直接套用聊天接口或图片生成接口。
4. 异步 POST /v1/videos 成功返回 HTTP 202 和任务 id，不会等到视频生成完。必须轮询 GET /v1/videos/{job_id} 直到 succeeded 或 failed。把 202 当失败是最常见的错。
5. 超时 客户端读超时设 ≥ 60 秒；轮询间隔 3–5 秒；总等待预算 ≥ 10 分钟（seedance2.5/30 秒更久）。不要用一次同步请求等成品，也不要套 30 秒短超时。
6. 幂等 创建前保存唯一 Idempotency-Key 与请求体；超时、空响应或重启后，使用同一个 API Key、操作编号和请求体恢复。新订单用新编号。收到任务 id 后只需查询；客户端等待超时不代表任务已取消。
7. 计费 按视频计积分；余额不足返回 402；触发频率/额度限制返回 429（按 Retry-After 等待）。
8. 下载 使用 GET /v1/videos/{job_id}/signed_url?download=1 获取原片下载链接，普通签名和列表中的 download_url 是轻量版。母版获取失败时返回固定的轻量版链接，以响应的 quality（original 或 preview）为准。只用本站返回的地址，支持 Range 断点续传；接口选好版本后，续传不会跨版本。不要缓存或转存这些短期地址。

余额查询

GET /v1/balance 返回当前积分余额与最近流水。响应字段为 balance（整数积分）与 ledger（最近流水数组）。

BASE="${VIDEO_API_BASE:-https://__ORIGIN__}"
KEY="${VIDEO_API_KEY:?Set VIDEO_API_KEY to the original sk- key}"
curl --fail-with-body -sS --max-time 90 "$BASE/v1/balance" \
  -H "Authorization: Bearer $KEY" -A "vinted-video-client/1.0"
# {"balance":12345,"ledger":[{"reason":"consume","delta":-20,"job_id":"example-job","balance_after":12345,"created_at":1756000000}]}

流水字段是 delta，负数为扣款、正数为入账。普通失败全额退款；适用内容审核扣费时可能部分退款或退款为零。退款结算可能晚于任务终态，以该任务的账单记录为准。

上传参考图

图生视频可选。POST /v1/files 每次上传一张 PNG、JPEG 或 WebP，以 image_b64 传 data URL 或纯 base64，解码后单图最大 50 MiB，编码字符串不超过 70,000,000 字符。成功返回 HTTP 201。多图逐张上传，再把所有 id 传给视频接口。

BASE="${VIDEO_API_BASE:-https://__ORIGIN__}"
KEY="${VIDEO_API_KEY:?Set VIDEO_API_KEY to the original sk- key}"

set -euo pipefail
UPLOAD=$(python3 -c 'import base64,json; from pathlib import Path; print(json.dumps({"image_b64":base64.b64encode(Path("reference.png").read_bytes()).decode()}))' |
  curl --fail-with-body -sS --max-time 90 -X POST "$BASE/v1/files" \
    -A "vinted-video-client/1.0" \
    -H "Authorization: Bearer $KEY" \
    -H "Content-Type: application/json" \
    --data-binary @-)
IMAGE_ID=$(printf '%s' "$UPLOAD" | jq -er '.image_id | select(type == "string" and length > 0)')

响应字段为 image_id、url、format、size 和 expires_at，id 有效期一小时。同一账号的有效 Key 在过期前可重复使用该 id；已受理的视频任务不受上传过期影响。将 image_id 放进 image_ids，不要把上传响应的 url 当公网图床链接。

查询与下载

轮询 GET /v1/videos/{job_id}。中间状态为 queued、running，终态为 succeeded 或 failed。

set -euo pipefail
BASE="${VIDEO_API_BASE:-https://__ORIGIN__}"
KEY="${VIDEO_API_KEY:?Set VIDEO_API_KEY to the original sk- key}"
JOB_ID=$(tr -d '\r\n' < job.id)
DEADLINE=$((SECONDS + 1800))
while [ "$SECONDS" -lt "$DEADLINE" ]; do
  CURRENT=$(curl --fail-with-body -sS --max-time 90 "$BASE/v1/videos/$JOB_ID" \
    -H "Authorization: Bearer $KEY" -A "vinted-video-client/1.0")
  STATUS=$(printf '%s' "$CURRENT" | jq -er '.status | select(type == "string")')
  case "$STATUS" in
    succeeded) break ;;
    failed) printf '%s\n' "$CURRENT"; exit 1 ;;
    queued|running) sleep 5 ;;
    *) printf '%s\n' "$CURRENT"; exit 1 ;;
  esac
done
if [ "${STATUS:-}" != succeeded ]; then
  echo "Still pending. Keep job.id and rerun this polling block."; exit 1
fi
curl --fail-with-body -sS --max-time 600 "$BASE/v1/videos/$JOB_ID/file" \
  -H "Authorization: Bearer $KEY" -A "vinted-video-client/1.0" -o result.mp4.part
mv result.mp4.part result.mp4

GET|HEAD /v1/videos/{job_id}/file 也可使用 Key 访问，并支持字节范围。

人物照片转彩绘 API

把人物照片转成彩色铅笔手绘风格。沿用账户的 sk- API Key 与积分余额：提交图片、查询任务、下载结果，全部通过下面的接口完成。省略 prompt 即使用本站默认彩铅风格，也可以传入自己的绘图要求。

先查价再提交：GET /v1/image-ai/settings 返回当前 price_per_image，以实际返回值为准。每张受理成功的图片独立扣积分，生成失败自动退款；未受理的图片不扣费，可在 GET /v1/balance 核对流水。该功能不占视频日配额，当前月卡账户暂不支持。

请求与结果

• images_b64：必填数组，1–30 张 PNG、JPEG 或 WebP，元素为纯 Base64 或 data URL。每张解码后最多 20 MiB，整次 JSON 默认最多 96 MiB（含 Base64 体积，服务可调整）；大图请拆成小批次。
• prompt：可选，最多 4,000 字符。留空使用默认彩铅风格；填写则整批使用这段绘图要求。接口不返回本站默认提示词。
• Idempotency-Key：可选但强烈建议，1–200 字符。每个新批次用新编号；提交超时、响应丢失或重启时，保留原 Key、编号和请求体重试。相同请求重放不会重复扣费；相同编号对应不同正文时返回 409 idempotency_conflict。操作编号按 API Key 隔离。
• 202 只表示收到批次。逐一检查 items[].ok：true 时保存 id，false 时读取 error。余额不足或非法图片可能使部分乃至全部图片未受理，不能只看 HTTP 状态。
• 图片任务状态为 queued（排队）、processing（生成中）、succeeded（成功）、failed（失败）。每 3–5 秒轮询一次；只有成功且完整下载图片，才算取得结果。
• 成功任务返回 download_url，可能为相对地址；用 URL 解析函数与站点基址拼接，保留全部签名参数。链接过期后重新查询任务获取新地址；也可带 Key 直接访问文件接口。以实际 Content-Type 保存 PNG、JPEG 或 WebP。
• 同账户的其他有效 Key 可以查询和下载该账户的图片；其他账户的任务一律返回 404。任务与文件默认保留 24 小时，具体以设置返回的 retention_hours 为准，请及时保存。

curl：本地图片提交与查询

下面示例使用 Bash、Python 3 和 curl 7.76+。把人物图放在当前目录，命名为 portrait.jpg。新订单使用新目录；超时重试保留已保存的 JSON 与操作编号。

export IMAGE_API_BASE="https://__ORIGIN__"
export IMAGE_API_KEY="sk-your-key"
# 每个订单使用单独目录；重试保留 request.json 和 operation.id，不重新生成。
python3 - <<'PY'
import base64, json, uuid
from pathlib import Path
request, operation = Path("image-request.json"), Path("image-operation.id")
if not request.exists():
    body = {"images_b64": [base64.b64encode(Path("portrait.jpg").read_bytes()).decode("ascii")]}
    request.write_text(json.dumps(body), encoding="utf-8")
if not operation.exists():
    operation.write_text(uuid.uuid4().hex, encoding="ascii")
PY
curl --fail-with-body -sS --max-time 30 "$IMAGE_API_BASE/v1/image-ai/settings" \
  -H "Authorization: Bearer $IMAGE_API_KEY"
curl --fail-with-body -sS --max-time 90 "$IMAGE_API_BASE/v1/image-ai/submit" \
  -H "Authorization: Bearer $IMAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(cat image-operation.id)" \
  --data-binary @image-request.json
# 从返回 items 中取 ok=true 的 id；每 5 秒查询一次，直到 succeeded 或 failed。
JOB_ID="替换为已受理的图片任务id"
curl --fail-with-body -sS --max-time 30 \
  "$IMAGE_API_BASE/v1/image-ai/jobs/$JOB_ID" \
  -H "Authorization: Bearer $IMAGE_API_KEY"
# succeeded 后可直接用 Key 下载；响应 Content-Type 决定真实图片格式。
curl --fail-with-body -sS --max-time 90 \
  "$IMAGE_API_BASE/v1/image-ai/jobs/$JOB_ID/file" \
  -H "Authorization: Bearer $IMAGE_API_KEY" -o portrait-result.image

Python：批量生成、轮询与下载

Python 3.10+，先执行 python -m pip install requests，把下方代码保存为 image_client.py。设置 IMAGE_API_BASE、IMAGE_API_KEY 后运行 python image_client.py portrait.jpg second.png。PowerShell 设置环境变量时使用 $env:IMAGE_API_KEY = "sk-your-key"。

可选 IMAGE_PROMPT 设置整批绘图要求，IMAGE_WAIT_SECONDS 设置本次最多等待秒数（默认 1800），IMAGE_OUTPUT 设置下载目录。状态文件默认 image-order-001.json：重跑会恢复已有任务；新订单须改用新的 IMAGE_STATE 文件名。状态文件含输入图片与请求体，应保存在自己的受控目录；每个订单同一时间只运行一个进程。

总等待到期不会取消生成，也不代表失败。保留状态文件和原 API Key 再次运行即可继续查询或下载；未受理的图片与已确认失败的图片不会在重跑时自动创建新任务。

"""Python 3.10+; install: python -m pip install requests"""
import base64
import json
import os
import sys
import time
import uuid
from pathlib import Path
from urllib.parse import quote, urljoin, urlsplit

import requests

BASE = os.environ.get("IMAGE_API_BASE", "https://__ORIGIN__").rstrip("/") + "/"
KEY = os.environ.get("IMAGE_API_KEY", "").strip()
STATE = Path(os.environ.get("IMAGE_STATE", "image-order-001.json"))
OUT = Path(os.environ.get("IMAGE_OUTPUT", "image-results"))
WAIT = float(os.environ.get("IMAGE_WAIT_SECONDS", "1800"))
if not KEY.startswith("sk-") or WAIT <= 0:
    raise SystemExit("Set IMAGE_API_KEY to your own sk- key and use a positive wait limit.")
origin = urlsplit(BASE)
if origin.scheme not in ("https", "http") or not origin.netloc:
    raise SystemExit("IMAGE_API_BASE must be an HTTP(S) origin, without /v1.")
if origin.path != "/" or origin.query or origin.fragment:
    raise SystemExit("IMAGE_API_BASE must contain only the site origin.")

def save():
    STATE.parent.mkdir(parents=True, exist_ok=True)
    temp = STATE.with_name(STATE.name + ".tmp")
    temp.write_text(json.dumps(state, ensure_ascii=False), encoding="utf-8")
    temp.replace(STATE)

if STATE.exists():
    state = json.loads(STATE.read_text(encoding="utf-8"))
    if state["base"] != BASE:
        raise SystemExit("Use the original base URL, API Key, and state file to resume.")
else:
    paths = [Path(name) for name in sys.argv[1:]]
    if not 1 <= len(paths) <= 30:
        raise SystemExit("Usage: python image_client.py photo.png [photo2.jpg ...]; 1-30 images.")
    images = []
    for path in paths:
        data = path.read_bytes()
        if not 0 < len(data) <= 20 * 1024 * 1024:
            raise SystemExit(str(path) + ": decoded image must be between 1 byte and 20 MiB.")
        images.append(base64.b64encode(data).decode("ascii"))
    body = {"images_b64": images}
    if os.environ.get("IMAGE_PROMPT", "").strip():
        body["prompt"] = os.environ["IMAGE_PROMPT"]
    if len(body.get("prompt", "")) > 4000:
        raise SystemExit("IMAGE_PROMPT must not exceed 4000 characters.")
    if len(json.dumps(body).encode("utf-8")) > 96 * 1024 * 1024:
        raise SystemExit("Split these images into smaller batches; JSON exceeds the default 96 MiB limit.")
    state = {"base": BASE, "operation": uuid.uuid4().hex,
             "body": body, "accepted": None, "done": {}}
    save()

deadline = time.monotonic() + WAIT
session = requests.Session()
session.headers.update({"Authorization": "Bearer " + KEY,
                        "User-Agent": "image-client/1.0"})

def remaining():
    seconds = deadline - time.monotonic()
    if seconds <= 0:
        raise TimeoutError("Total wait ended. Rerun with the SAME IMAGE_STATE and API Key.")
    return seconds

def safe_url(path):
    url = urljoin(BASE, path)
    target = urlsplit(url)
    if (target.scheme, target.netloc) != (origin.scheme, origin.netloc):
        raise RuntimeError("Refusing a result URL outside the configured site.")
    return url

def error_message(response):
    try:
        value = response.json()
        error = value.get("error", value.get("detail", {}))
        if isinstance(error, dict):
            return str(error.get("message") or error.get("type") or "Request failed")
        return str(error)
    except (ValueError, AttributeError):
        return "Non-JSON response; retain the HTTP status for support."

def call(method, path, **kwargs):
    budget = remaining()
    response = session.request(method, safe_url(path), timeout=(min(10, budget), min(90, budget)),
                               allow_redirects=False, **kwargs)
    if not 200 <= response.status_code < 300:
        raise RuntimeError("HTTP " + str(response.status_code) + ": " + error_message(response))
    return response

def get_json(method, path, **kwargs):
    with call(method, path, **kwargs) as response:
        value = response.json()
    if not isinstance(value, dict):
        raise RuntimeError("Unexpected JSON response. Keep the same state file to resume.")
    return value

def download(job):
    link = job.get("download_url")
    if not link:
        raise RuntimeError("Succeeded job has no download_url; query this job again.")
    with call("GET", link, stream=True) as response:
        kind = response.headers.get("Content-Type", "").split(";", 1)[0].lower()
        extension = {"image/png": ".png", "image/jpeg": ".jpg", "image/webp": ".webp"}.get(kind)
        if not extension:
            raise RuntimeError("Unexpected image Content-Type: " + kind)
        OUT.mkdir(parents=True, exist_ok=True)
        dest = OUT / (job["id"] + extension)
        partial = dest.with_suffix(dest.suffix + ".part")
        size = 0
        prefix = b""
        with partial.open("wb") as file:
            for chunk in response.iter_content(64 * 1024):
                remaining()
                if chunk:
                    prefix = (prefix + chunk)[:12]
                    file.write(chunk)
                    size += len(chunk)
        valid = ((kind == "image/png" and prefix.startswith(b"\x89PNG\r\n\x1a\n"))
                 or (kind == "image/jpeg" and prefix.startswith(b"\xff\xd8\xff"))
                 or (kind == "image/webp" and prefix[:4] == b"RIFF" and prefix[8:12] == b"WEBP"))
        if not size or not valid:
            raise RuntimeError("Downloaded bytes do not match the announced image format.")
        expected = response.headers.get("Content-Length")
        if expected and response.headers.get("Content-Encoding", "identity") == "identity":
            if size != int(expected):
                raise RuntimeError("Incomplete download. Rerun with the same state file.")
        partial.replace(dest)
    return str(dest.resolve())

try:
    if state["accepted"] is None:
        settings = get_json("GET", "/v1/image-ai/settings")
        print("Current credits per image:", settings["price_per_image"])
        accepted = get_json("POST", "/v1/image-ai/submit", json=state["body"],
                            headers={"Idempotency-Key": state["operation"]})
        if not isinstance(accepted.get("items"), list) or not accepted.get("batch_id"):
            raise RuntimeError("Missing batch receipt. Keep the same state file to resume.")
        state["accepted"] = accepted
        save()
    items = state["accepted"]["items"]
    pending = set()
    failed = any(not item.get("ok") for item in items)
    for index, item in enumerate(items, 1):
        if not item.get("ok"):
            print("NOT ACCEPTED", index, item.get("error", "Unknown error"))
        elif not item.get("id"):
            raise RuntimeError("Accepted item has no id.")
        else:
            job_id = str(item["id"])
            result = state["done"].get(job_id)
            if result and result["status"] == "failed":
                failed = True
                print("FAILED", job_id, result.get("error", "Generation failed"))
            elif result and Path(result.get("file", "")).is_file():
                print("SAVED", result["file"])
            else:
                pending.add(job_id)
    while pending:
        for job_id in list(pending):
            job = get_json("GET", "/v1/image-ai/jobs/" + quote(job_id, safe=""))
            status = job.get("status")
            if status in ("queued", "processing"):
                continue
            if status == "failed":
                failed = True
                state["done"][job_id] = {"status": status, "error": job.get("error", "")}
                print("FAILED", job_id, job.get("error", "Generation failed"))
            elif status == "succeeded":
                path = download(job)
                state["done"][job_id] = {"status": status, "file": path}
                print("SAVED", path)
            else:
                raise RuntimeError("Unknown job status: " + str(status))
            pending.remove(job_id)
            save()
        if pending:
            time.sleep(min(5, remaining()))
    raise SystemExit(1 if failed else 0)
except (requests.RequestException, RuntimeError, TimeoutError, ValueError, OSError) as exc:
    raise SystemExit(str(exc) + "\nKeep IMAGE_STATE and the original API Key to resume; do not create a new order.")
finally:
    session.close()

号池状态

需单独申请只读 Key。

GET /v1/pool/status 返回实时号池规模与可用量，用于向你的客户证明号池真实。

curl --fail-with-body -sS "$BASE/v1/pool/status" \
  -H "Authorization: Bearer $POOL_KEY"

{
  "generated_at": 1756531200,
  "total": 48,
  "available": 31,
  "status_counts": {"active": 31, "busy": 2, "cooling": 5, "inactive": 10},
  "availability_counts": {"active": 31, "busy": 2, "cooling": 5, "inactive": 3,
                          "recovery_pending": 4, "quota_exhausted": 1, "quota_frozen": 1, "unavailable": 1},
  "quota": {"total": 192, "remaining": 118, "remaining_available": 84}
}