跳转到内容
tansr 资料站

会话心跳:缺 sessionId 开新会话(sessions.api_key_id 归账)并回 sessionId;在册触碰 last_seen_at;meta 白名单(零留存);配置失效订阅:请求可携客户端 configVersion,响应恒回带服务端 configVersion 与 configStale(不一致=true → 重拉 /t1/config;未携恒 false);请求签名三头可选(在场恒校验);configVersion/bundleEtag 与 /t1/config 同径同档同锚——令牌径按 x-tansr-client-features 声明档计(客户端须三径同携同值,否则 configStale 恒真),owner 双头径恒全量单一 etag、漏头不 stale;在册会话心跳 = 续租恒走并发守门 acquire——窗内零变化,出窗会话重入与新会话同律判限(enforce 429 plan_concurrency_exceeded / shadow 计 would_reject),判限先于 last_seen_at 刷新;已归档会话(DELETE /t1/sessions/{id} 后)恒 410 session_archived(detail.sessionId;不复活、不入位;SDK 停该会话心跳、下轮 exchange 开新会话)

POST
/t1/heartbeat
curl --request POST \
  --url https://api.tansr.com/t1/heartbeat \
  --header 'Content-Type: application/json' \
  --header 'x-tansr-key: <x-tansr-key>' \
  --header 'x-tansr-key-id: <x-tansr-key-id>' \
  --data '{ "sessionId": "example", "client": "cli", "configVersion": "example", "meta": { "clientVersion": "example", "platform": "example" } }'

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Header Parameters

Section titled “Header Parameters”
x-tansr-client-features
string
/^[A-Za-z0-9-]+(\s*,\s*[A-Za-z0-9-]+)*$/

客户端可理解的可选扩展词表(逗号分隔,大小写不敏感,未知词忽略;与服务端 features 反向同形)。词表:platform-audio = 可理解 bundle 音频两面加法键(capabilities.platform.speechToText/textToSpeech、platformModels.speechToText/textToSpeech 与 media.asr/tts)。分档只施于 app_user 令牌径(十王修案 FX-A-05,分册 A S3:分档只保护已发布 .strict() 的旧 SDK,而 SDK 恒走令牌径):令牌径仅对声明者下发五键 / 四键 / 音频两面,缺头恒三键 / 两键,正文与 ETag 按档重算(响应 Vary 本头),同一客户端须在 /t1/config、/t1/handshake、/t1/heartbeat 同携同值,否则 configEtag/bundleEtag 与 bundle 异档、configStale 恒真;owner 径(AK/SK 双头 / 装置键 / PAT)恒全量、单一 ETag,本头为 no-op

x-tansr-ts
string
/^\d{1,15}$/

签名时间戳(unix 秒,十进制串;T-A34):与服务器时钟偏差 >300s → 401 signature_invalid

x-tansr-nonce
string
>= 16 characters <= 128 characters

签名随机数(≥16 字符;T-A34):同 keyId 600s 窗内重现 → 401 nonce_replayed

x-tansr-sign
string
/^[0-9a-f]{64}$/

请求签名(hex 小写;T-A34):HMAC-SHA256(K=sha256(SK 明文) 原始摘要, TWP1-HMAC-SHA256\n{METHOD}\n{path+query}\n{ts}\n{nonce}\n{sha256hex(rawBody)});三头须同现,在场恒校验;app signRequired 或 TANSR_API_TWP_REQUIRE_SIGNATURE=1 时未签名恒 401 signature_invalid

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
sessionId

缺席 = 开新会话并回 sessionId;在册 = 触碰 last_seen

string
<= 64 characters
client
Any of:
string
Allowed value: cli
configVersion

客户端当前 configVersion(/t1/config 响应携带的内容指纹)

string
<= 64 characters
meta

白名单元数据;正文类字段 400(总则 5 零留存)

object
clientVersion
string
<= 64 characters
platform
string
<= 64 characters

Responses

Section titled “Responses”

200

Section titled “200”

心跳受理

Media typeapplication/json
object
sessionId
required
string
serverTime
required
string
configVersion
required

服务端当前 configVersion(内容稳定指纹)

string
configStale
required

配置已失效(不一致=true;请求未携 configVersion 恒 false)

boolean
bundleEtag

此刻 GET /t1/config 的 ETag(不带引号;= configVersion 同源;sdk 比对缓存条目 etag,不同即失效重拉)

string
licenseStatus

Harness 许可状态提示位(O-A0 冻结;O-A3 起下发)

string
features

能力协商位(与 handshake 同词表 TWP_FEATURES;未知串恒忽略)

Array<string>
Examplegenerated
{
  "sessionId": "example",
  "serverTime": "example",
  "configVersion": "example",
  "configStale": true,
  "bundleEtag": "example",
  "licenseStatus": "example",
  "features": [
    "example"
  ]
}

401

Section titled “401”

App_key_invalid / signature_invalid / nonce_replayed(T-A34)

Media typeapplication/json
object
error
required
object
code
required

错误码注册表单源派生(src/http/errors.ts ERROR_CODES;码稳定,消费方按码翻译)

string
Allowed values: adjudicator_not_authorized admin_forbidden admin_key_invalid app_disabled app_ip_denied app_key_invalid approval_self_forbidden asr_not_configured asr_quota_exceeded auth_channel_undelivered bad_request conflict content_blocked context_window_exceeded currency_not_supported device_code_denied device_code_expired device_code_pending device_code_slow_down egress_blocked endpoint_disabled envelope_key_undelivered fence_denied forbidden idempotency_conflict idp_untrusted image_not_supported imagegen_not_configured imagegen_quota_exceeded insufficient_balance internal_error invalid_api_key license_required limit_exceeded liquidation_not_enabled model_not_authorized model_not_found nonce_replayed not_found order_state_invalid org_byok_not_available org_ceiling_exceeded otp_invalid otp_rate_limited pay_amount_mismatch pay_channel_undelivered pay_signature_invalid payload_too_large payment_required plan_apps_exceeded plan_concurrency_exceeded plan_end_users_exceeded plan_gate_unavailable plan_members_exceeded plan_required plan_tier_insufficient policy_locked pool_signing_undelivered preflight_required pricing_guard_tripped principal_required protocol_unsupported quota_exceeded rate_limited refund_not_eligible section_not_deliverable session_archived signature_invalid stream_backpressure token_expired tts_not_configured tts_quota_exceeded unauthorized upstream_connect_timeout upstream_disconnected upstream_error upstream_idle_timeout upstream_timeout upstream_total_timeout upstream_ttfb_timeout validation_failed videogen_not_configured videogen_quota_exceeded websearch_not_configured websearch_quota_exceeded
message
required
string
requestId
required
string
detail
object
Example
{
  "error": {
    "code": "adjudicator_not_authorized"
  }
}

404

Section titled “404”

Not_found(未知/他人会话)

Media typeapplication/json
object
error
required
object
code
required

错误码注册表单源派生(src/http/errors.ts ERROR_CODES;码稳定,消费方按码翻译)

string
Allowed values: adjudicator_not_authorized admin_forbidden admin_key_invalid app_disabled app_ip_denied app_key_invalid approval_self_forbidden asr_not_configured asr_quota_exceeded auth_channel_undelivered bad_request conflict content_blocked context_window_exceeded currency_not_supported device_code_denied device_code_expired device_code_pending device_code_slow_down egress_blocked endpoint_disabled envelope_key_undelivered fence_denied forbidden idempotency_conflict idp_untrusted image_not_supported imagegen_not_configured imagegen_quota_exceeded insufficient_balance internal_error invalid_api_key license_required limit_exceeded liquidation_not_enabled model_not_authorized model_not_found nonce_replayed not_found order_state_invalid org_byok_not_available org_ceiling_exceeded otp_invalid otp_rate_limited pay_amount_mismatch pay_channel_undelivered pay_signature_invalid payload_too_large payment_required plan_apps_exceeded plan_concurrency_exceeded plan_end_users_exceeded plan_gate_unavailable plan_members_exceeded plan_required plan_tier_insufficient policy_locked pool_signing_undelivered preflight_required pricing_guard_tripped principal_required protocol_unsupported quota_exceeded rate_limited refund_not_eligible section_not_deliverable session_archived signature_invalid stream_backpressure token_expired tts_not_configured tts_quota_exceeded unauthorized upstream_connect_timeout upstream_disconnected upstream_error upstream_idle_timeout upstream_timeout upstream_total_timeout upstream_ttfb_timeout validation_failed videogen_not_configured videogen_quota_exceeded websearch_not_configured websearch_quota_exceeded
message
required
string
requestId
required
string
detail
object
Example
{
  "error": {
    "code": "adjudicator_not_authorized"
  }
}

410

Section titled “410”

Session_archived(已归档会话;detail.sessionId;终态——开新会话)

Media typeapplication/json
object
error
required
object
code
required

错误码注册表单源派生(src/http/errors.ts ERROR_CODES;码稳定,消费方按码翻译)

string
Allowed values: adjudicator_not_authorized admin_forbidden admin_key_invalid app_disabled app_ip_denied app_key_invalid approval_self_forbidden asr_not_configured asr_quota_exceeded auth_channel_undelivered bad_request conflict content_blocked context_window_exceeded currency_not_supported device_code_denied device_code_expired device_code_pending device_code_slow_down egress_blocked endpoint_disabled envelope_key_undelivered fence_denied forbidden idempotency_conflict idp_untrusted image_not_supported imagegen_not_configured imagegen_quota_exceeded insufficient_balance internal_error invalid_api_key license_required limit_exceeded liquidation_not_enabled model_not_authorized model_not_found nonce_replayed not_found order_state_invalid org_byok_not_available org_ceiling_exceeded otp_invalid otp_rate_limited pay_amount_mismatch pay_channel_undelivered pay_signature_invalid payload_too_large payment_required plan_apps_exceeded plan_concurrency_exceeded plan_end_users_exceeded plan_gate_unavailable plan_members_exceeded plan_required plan_tier_insufficient policy_locked pool_signing_undelivered preflight_required pricing_guard_tripped principal_required protocol_unsupported quota_exceeded rate_limited refund_not_eligible section_not_deliverable session_archived signature_invalid stream_backpressure token_expired tts_not_configured tts_quota_exceeded unauthorized upstream_connect_timeout upstream_disconnected upstream_error upstream_idle_timeout upstream_timeout upstream_total_timeout upstream_ttfb_timeout validation_failed videogen_not_configured videogen_quota_exceeded websearch_not_configured websearch_quota_exceeded
message
required
string
requestId
required
string
detail
object
Example
{
  "error": {
    "code": "adjudicator_not_authorized"
  }
}

429

Section titled “429”

Plan_concurrency_exceeded(enforce:新会话首见 / 出窗会话重入达硬帽;Retry-After 30)/ rate_limited

Media typeapplication/json
object
error
required
object
code
required

错误码注册表单源派生(src/http/errors.ts ERROR_CODES;码稳定,消费方按码翻译)

string
Allowed values: adjudicator_not_authorized admin_forbidden admin_key_invalid app_disabled app_ip_denied app_key_invalid approval_self_forbidden asr_not_configured asr_quota_exceeded auth_channel_undelivered bad_request conflict content_blocked context_window_exceeded currency_not_supported device_code_denied device_code_expired device_code_pending device_code_slow_down egress_blocked endpoint_disabled envelope_key_undelivered fence_denied forbidden idempotency_conflict idp_untrusted image_not_supported imagegen_not_configured imagegen_quota_exceeded insufficient_balance internal_error invalid_api_key license_required limit_exceeded liquidation_not_enabled model_not_authorized model_not_found nonce_replayed not_found order_state_invalid org_byok_not_available org_ceiling_exceeded otp_invalid otp_rate_limited pay_amount_mismatch pay_channel_undelivered pay_signature_invalid payload_too_large payment_required plan_apps_exceeded plan_concurrency_exceeded plan_end_users_exceeded plan_gate_unavailable plan_members_exceeded plan_required plan_tier_insufficient policy_locked pool_signing_undelivered preflight_required pricing_guard_tripped principal_required protocol_unsupported quota_exceeded rate_limited refund_not_eligible section_not_deliverable session_archived signature_invalid stream_backpressure token_expired tts_not_configured tts_quota_exceeded unauthorized upstream_connect_timeout upstream_disconnected upstream_error upstream_idle_timeout upstream_timeout upstream_total_timeout upstream_ttfb_timeout validation_failed videogen_not_configured videogen_quota_exceeded websearch_not_configured websearch_quota_exceeded
message
required
string
requestId
required
string
detail
object
Example
{
  "error": {
    "code": "adjudicator_not_authorized"
  }
}

503

Section titled “503”

Plan_gate_unavailable(enforce 守门 Redis 故障;在册窗内会话为唯一放行例外)

Media typeapplication/json
object
error
required
object
code
required

错误码注册表单源派生(src/http/errors.ts ERROR_CODES;码稳定,消费方按码翻译)

string
Allowed values: adjudicator_not_authorized admin_forbidden admin_key_invalid app_disabled app_ip_denied app_key_invalid approval_self_forbidden asr_not_configured asr_quota_exceeded auth_channel_undelivered bad_request conflict content_blocked context_window_exceeded currency_not_supported device_code_denied device_code_expired device_code_pending device_code_slow_down egress_blocked endpoint_disabled envelope_key_undelivered fence_denied forbidden idempotency_conflict idp_untrusted image_not_supported imagegen_not_configured imagegen_quota_exceeded insufficient_balance internal_error invalid_api_key license_required limit_exceeded liquidation_not_enabled model_not_authorized model_not_found nonce_replayed not_found order_state_invalid org_byok_not_available org_ceiling_exceeded otp_invalid otp_rate_limited pay_amount_mismatch pay_channel_undelivered pay_signature_invalid payload_too_large payment_required plan_apps_exceeded plan_concurrency_exceeded plan_end_users_exceeded plan_gate_unavailable plan_members_exceeded plan_required plan_tier_insufficient policy_locked pool_signing_undelivered preflight_required pricing_guard_tripped principal_required protocol_unsupported quota_exceeded rate_limited refund_not_eligible section_not_deliverable session_archived signature_invalid stream_backpressure token_expired tts_not_configured tts_quota_exceeded unauthorized upstream_connect_timeout upstream_disconnected upstream_error upstream_idle_timeout upstream_timeout upstream_total_timeout upstream_ttfb_timeout validation_failed videogen_not_configured videogen_quota_exceeded websearch_not_configured websearch_quota_exceeded
message
required
string
requestId
required
string
detail
object
Example
{
  "error": {
    "code": "adjudicator_not_authorized"
  }
}