API文档

开始接入

公开演员数据可由浏览器匿名读取；身份映射与购买只能由合作方后端使用JD1签名访问，终端浏览器不访问SZKL。

Base URL

https://www.szkl.cn/api/v1

业务环境

合作方仅接受production；须审核通过并完成配置

响应格式

JSON（媒体与字幕除外）；错误使用稳定的 error.code

请求追踪

响应头 x-request-id

接入流程

1. 线下签署B端合作合同（合作方与巨东AI之间的框架合同）。
2. 在/partners/apply提交申请：工商主体、联系人、平台显示名称与合作方服务端生成的Ed25519公钥（SPKI PEM）。
3. 审核通过后配置平台，发放credentialId与权威audience；公钥指纹可在后台核对。
4. 完成合同登记、凭证和权限配置后，合作方可调用身份绑定与购买接口。
5. 预存余额充值后开始业务交易。

密钥生成（在合作方服务端执行）

openssl genpkey -algorithm ed25519 -out partner-private.pem   # 私钥，仅保存在服务端
openssl pkey -in partner-private.pem -pubout -out partner-public.pem   # 公钥，粘贴到申请表单

公钥以-----BEGIN PUBLIC KEY-----开头；不要提交私钥、SSH格式或JWK。私钥丢失平台侧无法恢复；请联系管理员停用受影响凭证并安排重新配置。

Scope

身份与绑定

authorization_sessions:create / authorization_sessions:read / projects:bind / identity:assert_verified_email
以管理员实际配置的权限为准

购买与资金

purchase:create / purchase:read / funds:read
以管理员实际配置的权限为准

样片归档

content_archive
以管理员实际配置的权限为准

演员详情

catalog:read
默认未开通，按平台申请开通

选角推荐

casting:recommend / casting:read
默认未开通，按平台申请开通

公开演员API

演员目录、详情和媒体端点允许任意Origin无凭据 GET/OPTIONS，禁止携带Cookie或Authorization。公开核验端点只提供匿名 GET，不读取登录会话。媒体URL以响应中的绝对公开地址为准。

• GET
  /health

  读取服务健康与部署环境

  匿名
• GET
  /actors

  搜索和分页读取公开演员

  匿名
• GET
  /actors/{actorCode}

  读取演员详情与形象列表；媒体只含演员首图、风格变体与自我介绍视频

  匿名
• GET
  /media/{publicId}

  读取已发布宣传媒体

  匿名
• GET
  /media/{publicId}/captions

  读取已发布字幕

  匿名
• GET
  /verification/{token}

  查询公开授权核验事实（当前仅历史test/test_only授权，正式生产核验未开放）

  匿名

另提供只读目录MCP端点 POST /api/v1/catalog-mcp（无状态Streamable HTTP，JSON响应），工具 search_actors、get_actor、get_catalog_filters 与上述公开演员接口同口径，匿名可用、只读。

最小请求

curl -H "Accept: application/json" \
  "https://www.szkl.cn/api/v1/actors?limit=24&offset=0"

公开读取错误：参数无效为400 BAD_REQUEST，资源不存在为404 NOT_FOUND，依赖不可用为503 SERVICE_UNAVAILABLE，未预期异常为500 INTERNAL_ERROR。媒体还支持206部分内容、304未修改和416范围不可满足。

公开授权核验

当前核验接口仅支持历史 test/test_only 授权事实，不提供正式production授权核验。正式购买响应中的核验编号不能据此视为已经支持公开核验。

使用授权编号查询最小核验事实。非法编号、权威不存在返回 404；依赖或响应畸形返回 503；成功与错误均禁止缓存，成功响应不携带来源地址。

curl -H "Accept: application/json" \
  "https://www.szkl.cn/api/v1/verification/JDT-ABCDEF0123456789ABCDEF01"

合作方API

合作方接口只接受人工审核后配置的服务端凭证。合作方后端直接建立平台范围身份映射，响应不含授权URL、state、回跳或Cookie；合作网站完成自己的订单、合同和支付后，再调用购买接口取得项目买断授权；生成由合作方模型侧直接完成，不经巨东API。

• POST
  /partner/authorization-sessions

  建立服务端身份映射；scope：authorization_sessions:create + projects:bind + identity:assert_verified_email

  JD1
• GET
  /partner/authorization-sessions/{sessionId}

  查询身份映射与后续权威状态；scope：authorization_sessions:read

  JD1
• GET
  /partner/actors/{actorCode}

  读取演员完整详情：全部形象图片、三视图与音频及扩展资料；scope：catalog:read（默认未开通）

  JD1

购买与资金

• GET
  /partner/purchase-options

  读取项目买断价目、年限系数和场景规则；scope：purchase:read

  JD1
• POST
  /partner/purchase-orders

  原子完成扣款、合同与项目买断授权；scope：purchase:create

  JD1
• GET
  /partner/purchase-orders

  按外部订单号查询购买和授权事实；scope：purchase:read

  JD1
• GET
  /partner/fund-balance

  读取合作平台预存余额；scope：funds:read

  JD1
• GET
  /partner/fund-events

  分页读取不可变资金流水；scope：funds:read

  JD1

样片归档与审核

• POST
  /partner/content-archives/uploads

  申请样片归档直传授权（预签名PUT地址，1小时有效）；scope：content_archive

  JD1
• POST
  /partner/content-archives/complete

  确认样片回传并启动异步审核（画面机审+LLM语义比对）；scope：content_archive

  JD1
• GET
  /partner/content-archives

  查询归档状态机、机审/LLM/人工复核结论与时间线；scope：content_archive

  JD1

选角推荐

• POST
  /partner/casting/recommendations

  提交选角推荐任务（文字描述、角色表或剧本文件），立即返回任务号；scope：casting:recommend

  JD1
• GET
  /partner/casting/recommendations/{taskId}

  查询本平台推荐任务的状态与逐角色候选；scope：casting:read

  JD1
• GET
  /partner/casting/quota

  查询本平台今日推荐轮次与剧本解析额度；scope：casting:read

  JD1

提交即回：创建后返回 taskId，按 pollAfterSeconds 轮询结果。同一 clientRequestId 重放同一请求体返回原任务、不重复计次；结果只含公开画像字段，保留24小时。每日轮次和剧本解析份数按平台计算，剧本文件解码后不超过700KB，请求体超过1,000,000字节返回413，更大的剧本请整理成角色表提交。

样片归档为授权合规审核意见与证据留存：巨东不是发行闸门，审核不通过合作方仍可自行决定发行；审核结论由状态查询接口读取，样片文件保留365天后清理，审核记录永久留存。

合作网站需要保存

客户映射

externalUserId ↔ sessionId，同一用户长期保持稳定

购买映射

externalOrderId ↔ purchaseId/projectId，买断授权绑定该项目

实名认证

只传已认证结果、认证时间和认证记录编号；不传身份证号、证件图片或原始材料

请求与响应示例

以下响应只摘录合作方成功响应的data字段，省略号和尖括号需替换为实际值。完整JSON包裹为{ "data": { ... }, "meta": { "request_id": "..." } }；金额仅为示例，不代表当前报价。

① 建立服务端身份映射

POST /api/v1/partner/authorization-sessions
{
  "externalUserId": "customer-42",
  "externalProjectId": "drama-2026-001",
  "contactEmail": "customer@example.com",
  "emailVerified": true,
  "emailVerificationMethod": "partner_account_v1",
  "requestedScopes": ["projects:bind"],
  "selection": { "version": 2, "mode": "editable", "actorCodes": ["ACT-781C32A7CC"] }
}

201 →
{ "status": "claimed", "accountLinked": true, "sessionId": "<uuid>",
  "externalProjectId": "drama-2026-001", "selection": { ... } }

响应不含授权URL、state、回跳、Cookie或token；同一externalUserId重复提交收敛到同一映射。购买时externalCustomerId必须与externalUserId完全一致。本请求必填externalUserId/externalProjectId/contactEmail/emailVerified/emailVerificationMethod/requestedScopes，可选selection（预选演员单）；必填性以OpenAPI schema为准。

② 购买项目买断授权

POST /api/v1/partner/purchase-orders
{
  "externalOrderId": "order-2026-0001",
  "externalCustomerId": "customer-42",
  "subjectKind": "individual",
  "subjectName": "张三",
  "identityVerified": true,
  "identityVerifiedAt": "2026-09-05T10:00:00+08:00",
  "identityVerificationReference": "partner-verify-0001",
  "customerAcceptedAt": "2026-09-05T10:05:00+08:00",
  "acceptanceReference": "partner-accept-0001",
  "projectName": "品牌短剧", "workType": "短剧",
  "synopsis": "用于品牌故事展示的系列短剧项目。", "releaseChannels": ["合作网站"],
  "scenarioId": "<purchase-options返回>",
  "actorConfigurations": [
    { "actorCode": "ACT-781C32A7CC", "commercialPeriods": 6 }
  ],
  "projectAuthorization": {
    "version": 1,
    "productionCompany": "某某影业有限公司",
    "producerCompany": "某某影业有限公司",
    "workKind": "series",
    "episodeCount": 12,
    "episodeDurationMinutes": 10,
    "roles": [ { "actorCode": "ACT-781C32A7CC", "roleName": "女主角" } ]
  },
  "idempotencyKey": "order-2026-0001-create"
}

201 → { "purchaseId": "<uuid>", "projectId": "<uuid>", "contractNo": "...",
  "licenses": [ { "actorCode": "...", "licenseId": "<uuid>", "pricingModel": "buyout_v1",
                  "buyoutCents": 49500, "pricePerSecondCents": 33, "commercialExpiresAt": "..." } ],
  "totalCents": 49500, "balanceAfterCents": ... }

单事务全有或全无：余额不足（INSUFFICIENT_FUNDS）或任一环节失败整体回滚，不产生部分扣款。买断价由服务端按演员当前每秒权威价折算（每秒单价×1500×年限系数；1年精确、2/3年向下取整到10元；当前全员0.33元/秒对应495/890/1230元/年）；买断含项目内不限量生成与演员未来新增形象，同一项目需重新买断，年限1–3年。

购买字段说明（每个字段为什么需要）

字段与格式以OpenAPI schema为准（必填性以各schema的required列表为唯一权威）；以下解释业务含义并同步标注必填性，供表单设计与向客户收集信息时参考。购买请求顶层仅projectAuthorization可选，其余全部必填；projectAuthorization整体可选，一旦提供则内部version/productionCompany/workKind/roles必填，series另必填episodeCount/episodeDurationMinutes、film另必填filmDurationMinutes。

externalOrderId 必填

你们的订单号：双方对账与追溯的唯一凭据，由你们系统生成。

externalCustomerId 必填

你们的客户ID：先经授权会话完成绑定，购买才能关联到真实客户。

idempotencyKey 必填

防重复扣款：建议用“订单号-create”。网络超时后同键同内容重试返回原结果，同键不同内容返回IDEMPOTENCY_CONFLICT。

subjectKind / subjectName 必填

谁买授权（合同被授权方）：个人填身份证姓名、企业填营业执照全称；必须与实名或执照完全一致，不接受简称或品牌名。

identityVerified 三件套 必填

实名在合作网站完成、认证材料留合作网站；此处只登记已认证事实、时间与凭据编号，作为合同效力与争议追溯依据。未实名（false）的请求会被拒绝。

customerAcceptedAt + acceptanceReference 必填

客户在你们页面确认订单内容的时间与确认凭据编号，共同构成“客户同意购买”的证据；两个值都要生成保存，不能只存勾选状态。

projectName / workType / synopsis / releaseChannels 必填

合同标的与授权用途条款的素材：作品名称、类型、内容简介（10–2000字）与计划发行渠道（1–10个），写清楚对客户是保护。

scenarioId 必填

使用场景：不同场景对应不同授权条款与计价组合，必须取自purchase-options返回的scenarios，不要自行构造。

actorConfigurations 必填

逐演员买断：actorCode与commercialPeriods（6/12/18个月）。价格由服务端按权威每秒价计算并在响应中返回快照，客户端不应自行计价；买断含项目内不限量生成与演员未来新增形象，换项目需重新买断。

projectAuthorization.productionCompany 必填

出品公司＝作品的版权主体（片头“出品”署名）。它回答“作品归谁”，与subjectName回答的“谁买授权”是两件事：客户自有版权时填同一家，代理或发行时填实际版权方。合同必须同时写明两者，演员形象授权才挂在真实权利链上。

projectAuthorization.producerCompany 选填

制片公司＝实际承制拍摄方；与出品为同一家时填一样，或不传该字段。

filingNumber / releaseLicenseNumber 选填

作品备案号与发行许可证号（选填）：证明作品本身合规。

projectAuthorization.workKind 必填

作品形态：series（剧集，按集）/film（电影，按部），决定合同标的的规格写法与时长必填项——series必填episodeCount与episodeDurationMinutes，film必填filmDurationMinutes。短剧一律series。

projectAuthorization.roles 必填

每位所选演员在剧中饰演的角色名，必须与actorConfigurations的演员一一对应。

projectAuthorization.version 必填

资料结构版本号，当前固定填1。

③ 生成说明（生成接口已退役）

买断订单的生成在您的模型侧直接进行：不经巨东API、无需预留或结算、生成次数不限。历史按秒生成预留/结算接口已整体退役移除（全库无历史调用数据）；如您的旧代码中存在对接残留，可整体删除。

JD1签名

每次请求使用新的时间戳和nonce。签名覆盖HTTP方法、原始查询顺序和最终发送的body字节；响应不明确时使用新nonce查询权威状态，不盲目重放写请求。

x-jd-credential: <credential-id>
x-jd-environment: production
x-jd-audience: <configured-audience>
x-jd-timestamp: <unix-seconds>
x-jd-nonce: <base64url-random-bytes>
x-jd-signature: <base64url-ed25519-signature>

完整规范原文以下载的OpenAPI为准。签名允许前后300秒时钟差，成功使用过的nonce不可重放。

签名原文（固定顺序）

JD1
credential:<credential-id>
environment:production
audience:<configured-logical-audience>
timestamp:<unix-seconds>
nonce:<base64url-random-bytes>
method:<UPPERCASE-METHOD>
target:<pathname-with-original-query-order>
body-sha256:<base64url-sha256-of-raw-body-bytes>

UTF-8编码，字段顺序与换行固定，所有值禁止CR/LF。target不含scheme/host，查询参数不得在签名后重排；GET使用空body摘要。

Node.js签名示例（仅服务端）

import { createHash, createPrivateKey, randomBytes, sign } from "node:crypto";
const b64u = (b) => b.toString("base64url");
const body = Buffer.from(JSON.stringify(payload));
const canonical = [
  "JD1",
  `credential:${credentialId}`,
  `environment:${environment}`,
  `audience:${audience}`,
  `timestamp:${Math.floor(Date.now() / 1000)}`,
  `nonce:${b64u(randomBytes(24))}`,
  `method:POST`,
  `target:/api/v1/partner/authorization-sessions`,
  `body-sha256:${b64u(createHash("sha256").update(body).digest())}`,
].join("\n");
const signature = b64u(sign(null, Buffer.from(canonical),
  createPrivateKey({ key: privateKeyPkcs8Pem, format: "pem" })));

签名原文与Base64url编码是语言无关的，以下是等价实现参考（Java/Go 为语句片段，需包进你们的函数或类后使用）；务必对实际发送的body字节签名（不要重新序列化后再发送另一份字节）。

Python签名示例（cryptography，仅服务端）

import base64, hashlib, json, secrets, time
from cryptography.hazmat.primitives import serialization

def b64u(raw: bytes) -> str:
    return base64.urlsafe_b64encode(raw).rstrip(b"=").decode()

body = json.dumps(payload, ensure_ascii=False, separators=(",", ":")).encode()
nonce = b64u(secrets.token_bytes(24))
canonical = "
".join([
    "JD1",
    f"credential:{credential_id}",
    f"environment:{environment}",
    f"audience:{audience}",
    f"timestamp:{int(time.time())}",
    f"nonce:{nonce}",
    "method:POST",
    "target:/api/v1/partner/authorization-sessions",
    f"body-sha256:{b64u(hashlib.sha256(body).digest())}",
])
key = serialization.load_pem_private_key(private_key_pkcs8_pem, password=None)
signature = b64u(key.sign(canonical.encode()))

Java签名示例（JDK 17+，仅服务端）

import java.nio.charset.StandardCharsets;
import java.security.*;
import java.security.spec.PKCS8EncodedKeySpec;
import java.util.Base64;

static String b64u(byte[] raw) {
    return Base64.getUrlEncoder().withoutPadding().encodeToString(raw);
}

byte[] body = /* 实际发送的JSON字节 */;
String canonical = String.join("
",
    "JD1",
    "credential:" + credentialId,
    "environment:" + environment,
    "audience:" + audience,
    "timestamp:" + epochSecond,
    "nonce:" + nonce,
    "method:POST",
    "target:/api/v1/partner/authorization-sessions",
    "body-sha256:" + b64u(MessageDigest.getInstance("SHA-256").digest(body)));
String pemBody = privateKeyPkcs8Pem.replaceAll("-----[A-Z ]+-----|\s", "");
PrivateKey key = KeyFactory.getInstance("Ed25519")
    .generatePrivate(new PKCS8EncodedKeySpec(Base64.getDecoder().decode(pemBody)));
Signature signer = Signature.getInstance("Ed25519");
signer.initSign(key);
signer.update(canonical.getBytes(StandardCharsets.UTF_8));
String signature = b64u(signer.sign());

Go签名示例（标准库，仅服务端）

import (
    "crypto/ed25519"
    "crypto/x509"
    "encoding/base64"
    "encoding/pem"
)

b64u := base64.RawURLEncoding.EncodeToString

block, _ := pem.Decode(privateKeyPkcs8PEM) // PKCS#8 私钥PEM
key, _ := x509.ParsePKCS8PrivateKey(block.Bytes)
edKey := key.(ed25519.PrivateKey)
signature := b64u(ed25519.Sign(edKey, []byte(canonical)))

集成建议

以下为参考建议而非接入门禁；服务端的原子购买与幂等已保证账本正确性。采纳这些建议可以减少接入问题与对账分歧。

错误与重试

MISSING_AUTHENTICATION / MALFORMED_AUTHENTICATION / INVALID_SIGNATURE

认证头或签名无效。
处置：先修复签名实现，不盲重试。

STALE_REQUEST

时间戳超出±300秒窗口。
处置：校准时钟后用新nonce重试。

REPLAY_DETECTED

nonce已被使用。
处置：使用新nonce，不复用原请求。

ENVIRONMENT_MISMATCH

凭证与目标环境不一致。
处置：修复environment配置。

AUDIENCE_MISMATCH

请求audience与凭证环境配置不一致。
处置：修复audience配置，原样复制后台值。

CREDENTIAL_UNAVAILABLE / PLATFORM_UNAVAILABLE / ENVIRONMENT_NOT_READY

凭证不可用，或平台/环境门禁未开放（production需平台approved+已登记合同）。
处置：联系管理员检查状态。

PLATFORM_REGISTRATION_INCOMPLETE

提交projectAuthorization时平台登记主体资料不完整。
处置：联系巨东补全平台登记后重试。

ORIGINAL_FIGURE_NOT_PURCHASABLE

购买请求包含尚未开放购买的原创数字人。
处置：移除原创数字人后重试。

SCOPE_FORBIDDEN

凭证不含所需scope。
处置：由管理员审核开通，不能客户端扩权。

RATE_LIMITED

当前凭证超过120次/分钟。
处置：等待窗口后用新nonce重试。

SESSION_FORBIDDEN / SESSION_NOT_FOUND

会话属于其他平台或不存在。
处置：不重试、不枚举，核对ID。

PROJECT_NOT_FOUND / ACTOR_NOT_FOUND

项目不属于当前平台或演员不存在/未上架。
处置：核对购买返回的projectId与公开actorCode。

BAD_REQUEST

请求字段、结构或演员编号无效。
处置：修复请求正文后用新nonce重试。

IDEMPOTENCY_CONFLICT

同一幂等键绑定了不同规范请求。
处置：停止重试；购买先GET同一externalOrderId与首份快照核对。

CONFLICT

对象状态已变化（会话失效或授权状态变化）。
处置：核对状态，不原样重放。

INSUFFICIENT_FUNDS

预存余额不足。
处置：充值后用新nonce重新发起。

EXTERNAL_CUSTOMER_UNMAPPED

外部客户尚未完成身份绑定。
处置：先完成authorization-sessions绑定。

CASTING_DAILY_LIMIT_REACHED

本平台今日推荐轮次或剧本解析份数已用完（响应附resetAt）。
处置：等到resetAt后再提交。

CASTING_TOO_MANY_TASKS

本平台进行中的推荐任务已达上限。
处置：等已有任务完成后再提交。

TASK_NOT_FOUND

推荐任务不存在、已过期（24小时）或不属于当前平台。
处置：不重试、不枚举，核对taskId。

SCRIPT_TOO_LARGE / FILE_TYPE_UNSUPPORTED / FILE_UNREADABLE / FILE_ENCRYPTED / TEXT_EMPTY / TEXT_TOO_LONG

剧本文件超过700KB、格式不支持、无法读取、已加密或文字为空/过长（不计份数）。
处置：改用角色表结构提交，或修复文件后用新nonce重试。

机器可读字段、schema、scope和响应以 OpenAPI v1 为准；本文摘要不放宽认证、幂等、额度或失败关闭规则。

更新日志

按日期倒序列出已登记进 OpenAPI 的接口契约变更；机器契约以下载的 v1.yaml 为准。