数字克隆 SZKL.CN

API文档

公开演员目录与经审核合作方的服务端接入契约。当前稳定站仍是 test_only Preview。

API V1 · TEST_ONLY
下载 OpenAPI YAML
GETTING STARTED

开始接入

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

Base URL
https://www.szkl.cn/api/v1
当前环境
test，无法律效力，不产生真实扣款
响应格式
JSON；错误使用稳定的 error.code
请求追踪
响应头 x-request-id
接入边界
  • 公开宣传媒体只用于发现与展示，不构成生产素材资格或商业授权。
  • JD1私钥只能保存在合作方服务端，不得进入浏览器、移动端包或日志。
  • production生成许可尚未开放；test预留不能升级为production事实。
PUBLIC DISCOVERY

公开演员API

公开端点允许任意Origin无凭据 GET/OPTIONS，禁止携带Cookie或Authorization。媒体URL以响应中的绝对公开地址为准。

  • GET
    /actors

    搜索和分页读取公开演员

    匿名
  • GET
    /actors/{actorCode}

    读取演员详情和公开形象

    匿名
  • GET
    /media/{publicId}

    读取已发布宣传媒体

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

    读取已发布字幕

    匿名

最小请求

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

合作方API

合作方接口只接受人工审核后配置的服务端凭证。合作方后端直接建立平台范围身份映射，响应不含授权URL、state、回跳或Cookie；合作网站完成自己的订单、合同和支付后，再调用购买接口。每个真实生成调用必须在模型启动前取得一次成功的test预留，并以一个终态结算收敛。

  • POST
    /partner/authorization-sessions

    直接建立test-only服务端身份映射

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

    查询身份映射与后续权威状态

    JD1
  • GET
    /partner/callback-signing-keys

    读取回调签名公钥

    匿名

购买与资金

  • GET
    /partner/purchase-options

    读取购买秒数、年限和场景规则

    JD1
  • POST
    /partner/purchase-orders

    原子完成扣款、合同、授权和额度建立

    JD1
  • GET
    /partner/purchase-orders

    按外部订单号查询购买和授权事实

    JD1
  • GET
    /partner/fund-balance

    读取合作平台预存余额

    JD1
  • GET
    /partner/fund-events

    分页读取不可变资金流水

    JD1

合作网站需要保存

客户映射
externalUserId ↔ sessionId，同一用户长期保持稳定
购买映射
externalOrderId ↔ purchaseId/projectId，购买后生成使用SZKL返回的projectId
生成映射
externalGenerationId ↔ projectId/terminalStatus，模型启动前先预留，结束时只结算一次
实名认证
只传已认证结果、认证时间和认证记录编号；不传身份证号、证件图片或原始材料

生成调用许可

  • POST
    /partner/generation-reservations

    模型启动前原子预留调用额度

    JD1
  • GET
    /partner/generation-reservations/{externalGenerationId}

    查询预留权威状态

    JD1
  • POST
    /partner/generation-reservations/{externalGenerationId}/extend

    延长仍有效的预留

    JD1
  • POST
    /partner/generation-reservations/{externalGenerationId}/success

    成功结算并消费额度

    JD1
  • POST
    /partner/generation-reservations/{externalGenerationId}/fail

    失败并释放额度

    JD1
  • POST
    /partner/generation-reservations/{externalGenerationId}/cancel

    取消并释放额度

    JD1
REQUEST SIGNING

JD1签名

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

x-jd-credential: <credential-id>
x-jd-environment: test
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不可重放。

FAIL CLOSED

错误与重试

MISSING_AUTHENTICATION
补齐服务端认证头，不重放原请求。
INVALID_SIGNATURE
核对签名原文、body字节和目标路径。
REPLAY_DETECTED
使用新nonce；不要复用已发送签名。
ENVIRONMENT_NOT_READY
当前环境未开放对应能力，不能客户端绕过。
IDEMPOTENCY_CONFLICT
同一幂等键绑定了不同规范请求，停止重试并修复键管理。
RATE_LIMITED
等待窗口后使用新时间戳、nonce和签名。

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