twp/1 认证探活 + 协议协商(CLI 登录验证即此):回 protocol/app{id,name,ownerType}/configEtag/serverTime/features;协议版本不符 400 protocol_unsupported;认证失败 401 app_key_invalid / 403 app_disabled / 403 app_ip_denied(CIDR fail-closed);请求签名三头可选(在场恒校验);configEtag 与 /t1/config 按同一 x-tansr-client-features 声明生成;owner 仅保留原音频可见性,其余扩展仍按声明投影

POST

/t1/handshake

curl --request POST \
  --url https://api.tansr.com/t1/handshake \
  --header 'Content-Type: application/json' \
  --header 'x-tansr-key: <x-tansr-key>' \
  --header 'x-tansr-key-id: <x-tansr-key-id>' \
  --data '{ "protocol": "example", "client": { "name": "example", "version": "example" } }'

Authorizations

• appKeyId
• appKey

Parameters

Header Parameters

x-tansr-client-features

string

/^[A-Za-z0-9-]+(\s*,\s*[A-Za-z0-9-]+)*$/

客户端可理解的可选扩展词表，逗号分隔，未知词忽略。platform-audio 控制旧令牌端音频可见性；tts-input-limit-v1 声明原子输入上限；bound-device-v1 声明绑定终端段；nonchat-operations-v1 声明六个非聊天能力；adjudicator-policy-slots-v1 声明裁决主备独立策略及预算模式，未声明时 independent 配置只发有效主选并禁用备用，旧 shared 策略保持原备用。新能力对所有未声明客户端剥除，owner 仅保留原音频可见性。响应 Vary 本头，正文和规范化特性集合共同生成 ETag；config、handshake、heartbeat 必须携相同特性。

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 Body^required

Media typeapplication/json

object

protocol

期望协议;非 twp/1 → 400 protocol_unsupported

string

<= 16 characters

client

object

name

required

string

>= 1 characters <= 64 characters

version

required

string

>= 1 characters <= 32 characters

Example^generated

{
  "protocol": "example",
  "client": {
    "name": "example",
    "version": "example"
  }
}

Responses

200

握手成功

Media typeapplication/json

object

protocol

required

string

Allowed value: twp/1

app

required

object

id

required

ApiKeyId(api_keys.public_id)

string

name

required

string

ownerType

required

Any of:

string

string

Allowed value: user

string

string

Allowed value: org

configEtag

required

账套配置包当前 ETag(/t1/config 一致性事实源)

string

serverTime

required

string

features

required

能力协商位(恒加法演进);当前词表 = TWP_FEATURES:org-governance(账套治理段下发)、usage-purpose(twp meta.purpose 计费归属可发)、usage-purpose-2(purpose 词表 v2 增量可发,TM-9:memory)、usage-purpose-3(v3 增量可发,K2:adjudication)、image-input(exchange user 消息可携 image 块,M3)、prompt-cache(exchange 可携缓存语义:system 块 cacheable 位 + cache.skipWrite/key,CW11-W1)、reasoning-off(params.reasoning 词表含 off 显式思考关断,RFC-M3 B2)、session-register(批ι 地板 wire 标记 floor-1:meta 未知键忽略 + purpose 词形受理 + 会话首见幂等登记;部署核验/诊断用,非发送门,RFC-R79-ι)。消费方按串精确匹配,未知串恒忽略

Array<string>

Example

{
  "protocol": "twp/1",
  "app": {
    "ownerType": "user"
  }
}

400

Protocol_unsupported

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 operation_input_invalid operation_not_configured 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_outcome_unknown 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"
  }
}

401

App_key_invalid(查无/密文不符/缺头)/ signature_invalid(T-A34:签名头不全/ts 偏差>300s/签名不匹配/强制档未签名,detail.reason)/ nonce_replayed(600s 窗内重放)

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 operation_input_invalid operation_not_configured 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_outcome_unknown 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"
  }
}

403

App_disabled / app_ip_denied / forbidden(scope 不符)

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 operation_input_invalid operation_not_configured 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_outcome_unknown 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"
  }
}

本文是否有帮助?

有帮助没帮助