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
以管理员实际配置的权限为准

公开演员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}

  查询公开授权核验事实

  匿名

最小请求

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/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

样片归档为授权合规审核意见与证据留存：巨东不是发行闸门，审核不通过合作方仍可自行决定发行；审核结论由状态查询接口读取，样片文件保留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完全一致。

② 购买项目买断授权

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",
  "customerPhone": "13800001234",
  "acceptanceReference": "partner-accept-0001",
  "signRedirectUrl": "https://partner-site.example/order/order-2026-0001/signed",
  "projectName": "品牌短剧", "workType": "短剧",
  "synopsis": "用于品牌故事展示的系列短剧项目。", "releaseChannels": ["合作网站"],
  "scenarioId": "<purchase-options返回>",
  "actorConfigurations": [
    { "actorCode": "ACT-781C32A7CC", "commercialYears": 1 }
  ],
  "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为准；以下解释业务含义，供表单设计与向客户收集信息时参考。

externalOrderId

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

externalCustomerId

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

idempotencyKey

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

subjectKind / subjectName

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

identityVerified 三件套

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

customerPhone

客户本人手机号：电子签署的参与方匹配与意愿认证短信都使用它，缺失或不匹配时客户在签署环节无法完成；个人订单必须与实名主体一致。

customerAcceptedAt + acceptanceReference

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

projectName / workType / synopsis / releaseChannels

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

scenarioId

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

actorConfigurations

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

projectAuthorization.productionCompany

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

projectAuthorization.producerCompany

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

filingNumber / releaseLicenseNumber

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

projectAuthorization.workKind

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

projectAuthorization.roles

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

projectAuthorization.version

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

signRedirectUrl

签署完成跳回你们页面的HTTPS地址（可选）；不传时客户停留在签署平台完成页。

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

买断订单的生成在您的模型侧直接进行：不经巨东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" })));

集成建议

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

错误与重试

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时平台登记主体资料不完整。
处置：联系巨东补全平台登记后重试。

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绑定。

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

更新日志

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