跳转到内容
tansr 资料站

使用私有逻辑缓存绑定执行原 TWP 请求

POST
/t1/cache/v1/exchange
curl --request POST \
  --url https://api.tansr.com/t1/cache/v1/exchange \
  --header 'Content-Type: application/vnd.tansr.cache-exchange.v1' \
  --header 'x-tansr-app-token: <x-tansr-app-token>' \
  --data binary

仅接受 app_user 短期令牌。Content-Type 必须逐字为 application/vnd.tansr.cache-exchange.v1，不允许查询串、Content-Encoding 或附加 MIME 参数。metadata 使用严格控制 JSON；原 TWP 字节保持原协议。受理与原资金预留同事务，确认提交后才调用供应商。相同完整帧身份只读重放原结果；已受理或事务未知不会再次执行，返回 result_unknown 或现有 TWP 冲突响应。已完成但原结果不可用也不会重新执行。SSE 沿用原 t.* 事件和流内终局错误语义；禁止自动回退旧 exchange。默认关闭时返回旧 not_found。

Authorizations

Section titled “Authorizations”

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/vnd.tansr.cache-exchange.v1

原始字节帧：4 字节无符号大端整数指定 metadata 的 UTF-8 字节数，后接严格 JSON metadata，再接未经改写的原 TWP JSON 字节。metadata 最多 65536 字节；TWP 为 1..33554432 字节。长度、SHA-256 和 runtimeSessionId 必须与实际 TWP 相符。

string format: binary

Responses

Section titled “Responses”

200

Section titled “200”

原 TWP JSON 结果，或原 t.* SSE 流；stream 由原 TWP 请求决定。

object
exchangeId
required

服务端签发(= x-tansr-request-id)

string
model
required

账套内 handle(回显)

string
blocks
required
Array
Any of:
object
t
required
string
Allowed value: text
v
required
string
cacheable
boolean
usage
required
object
inTokens
required

非缓存输入段(不含缓存读/写命中;差价计费的全价段)

integer
outTokens
required

输出 token

integer
cacheRTokens
required

缓存读命中段(上游未报恒 0;按价目 cacheRPerM 差价计费,未配缓存价回落全价)

integer
cacheWTokens
required

缓存写段(anthropic 系 cache_creation;上游未报恒 0)

integer
cost
required

DECIMAL 字符串(实结)

string
currency
required
string
balanceAfter
required

DECIMAL 字符串(台账终审余额)

string
estimated

本次计量为服务端保守估算(上游缺报/断链补账);实报行键缺席

boolean
estimatedReason
Any of:
string
Allowed value: upstream_usage_missing
dims

长尾计量维度桶(token/次数等整数量);仅非零桶携带;键词表见维度注册表;obs_ 前缀 = 观测位(不参与计费)

object
saved

本次请求缓存净省费(DECIMAL 串,= readSaved − writePremium;销售四列快照直算)

string
stop
required
Any of:
string
Allowed value: end
Example
{
  "blocks": [
    {
      "t": "text",
      "cacheable": true
    }
  ],
  "usage": {
    "estimatedReason": "upstream_usage_missing"
  },
  "stop": "end"
}

Headers

Section titled “Headers”
Cache-Control
required
string
Allowed value: no-store

禁止缓存绑定、票据、状态及模型响应。

202

Section titled “202”

原 TWP 请求仍在处理中。

Media typeapplication/json
object
status
required
string
Allowed value: in_progress
requestId
required

客户端幂等键回显(twp = meta.requestId;compat = idempotency-key 头)

string
retryAfterMs
required

建议重试间隔(毫秒;末端可自定退避)

integer
Example
{
  "status": "in_progress"
}

Headers

Section titled “Headers”
Cache-Control
required
string
Allowed value: no-store

禁止缓存绑定、票据、状态及模型响应。

400

Section titled “400”

Invalid_request 或 protocol_version_mismatch

Media typeapplication/json
One of:
object
protocol
required
Allowed value: sdk2-cache-v1
requestId
required
string
>= 1 characters <= 128 characters /^[A-Za-z0-9][A-Za-z0-9._~-]*$/
code
required
string
Allowed values: invalid_request protocol_version_mismatch unauthorized forbidden stale_revision stale_generation request_id_conflict projection_stale ticket_expired mapping_expired receipt_expired payload_too_large unsupported_capability capacity_exceeded epoch_unavailable mapping_unavailable result_unknown
status
required
integer
>= 400 <= 503
retryAction
required
string
Allowed values: none same-request query-status refresh-projection
fallback
required
Allowed value: none
message
required
string
>= 1 characters <= 256 characters
Example
{
  "protocol": "sdk2-cache-v1",
  "code": "invalid_request",
  "retryAction": "none",
  "fallback": "none"
}

Headers

Section titled “Headers”
Cache-Control
required
string
Allowed value: no-store

禁止缓存绑定、票据、状态及模型响应。

401

Section titled “401”

Unauthorized

Media typeapplication/json
One of:
object
protocol
required
Allowed value: sdk2-cache-v1
requestId
required
string
>= 1 characters <= 128 characters /^[A-Za-z0-9][A-Za-z0-9._~-]*$/
code
required
string
Allowed values: invalid_request protocol_version_mismatch unauthorized forbidden stale_revision stale_generation request_id_conflict projection_stale ticket_expired mapping_expired receipt_expired payload_too_large unsupported_capability capacity_exceeded epoch_unavailable mapping_unavailable result_unknown
status
required
integer
>= 400 <= 503
retryAction
required
string
Allowed values: none same-request query-status refresh-projection
fallback
required
Allowed value: none
message
required
string
>= 1 characters <= 256 characters
Example
{
  "protocol": "sdk2-cache-v1",
  "code": "invalid_request",
  "retryAction": "none",
  "fallback": "none"
}

Headers

Section titled “Headers”
Cache-Control
required
string
Allowed value: no-store

禁止缓存绑定、票据、状态及模型响应。

402

Section titled “402”

原 TWP 资金或供应商错误，保持原错误合同。

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"
  }
}

Headers

Section titled “Headers”
Cache-Control
required
string
Allowed value: no-store

禁止缓存绑定、票据、状态及模型响应。

403

Section titled “403”

Forbidden

Media typeapplication/json
One of:
object
protocol
required
Allowed value: sdk2-cache-v1
requestId
required
string
>= 1 characters <= 128 characters /^[A-Za-z0-9][A-Za-z0-9._~-]*$/
code
required
string
Allowed values: invalid_request protocol_version_mismatch unauthorized forbidden stale_revision stale_generation request_id_conflict projection_stale ticket_expired mapping_expired receipt_expired payload_too_large unsupported_capability capacity_exceeded epoch_unavailable mapping_unavailable result_unknown
status
required
integer
>= 400 <= 503
retryAction
required
string
Allowed values: none same-request query-status refresh-projection
fallback
required
Allowed value: none
message
required
string
>= 1 characters <= 256 characters
Example
{
  "protocol": "sdk2-cache-v1",
  "code": "invalid_request",
  "retryAction": "none",
  "fallback": "none"
}

Headers

Section titled “Headers”
Cache-Control
required
string
Allowed value: no-store

禁止缓存绑定、票据、状态及模型响应。

404

Section titled “404”

未启用缓存 exchange。

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"
  }
}

Headers

Section titled “Headers”
Cache-Control
required
string
Allowed value: no-store

禁止缓存绑定、票据、状态及模型响应。

409

Section titled “409”

Stale_revision、stale_generation、request_id_conflict 或 projection_stale

Media typeapplication/json
One of:
object
protocol
required
Allowed value: sdk2-cache-v1
requestId
required
string
>= 1 characters <= 128 characters /^[A-Za-z0-9][A-Za-z0-9._~-]*$/
code
required
string
Allowed values: invalid_request protocol_version_mismatch unauthorized forbidden stale_revision stale_generation request_id_conflict projection_stale ticket_expired mapping_expired receipt_expired payload_too_large unsupported_capability capacity_exceeded epoch_unavailable mapping_unavailable result_unknown
status
required
integer
>= 400 <= 503
retryAction
required
string
Allowed values: none same-request query-status refresh-projection
fallback
required
Allowed value: none
message
required
string
>= 1 characters <= 256 characters
Example
{
  "protocol": "sdk2-cache-v1",
  "code": "invalid_request",
  "retryAction": "none",
  "fallback": "none"
}

Headers

Section titled “Headers”
Cache-Control
required
string
Allowed value: no-store

禁止缓存绑定、票据、状态及模型响应。

410

Section titled “410”

Ticket_expired、mapping_expired 或 receipt_expired

Media typeapplication/json
One of:
object
protocol
required
Allowed value: sdk2-cache-v1
requestId
required
string
>= 1 characters <= 128 characters /^[A-Za-z0-9][A-Za-z0-9._~-]*$/
code
required
string
Allowed values: invalid_request protocol_version_mismatch unauthorized forbidden stale_revision stale_generation request_id_conflict projection_stale ticket_expired mapping_expired receipt_expired payload_too_large unsupported_capability capacity_exceeded epoch_unavailable mapping_unavailable result_unknown
status
required
integer
>= 400 <= 503
retryAction
required
string
Allowed values: none same-request query-status refresh-projection
fallback
required
Allowed value: none
message
required
string
>= 1 characters <= 256 characters
Example
{
  "protocol": "sdk2-cache-v1",
  "code": "invalid_request",
  "retryAction": "none",
  "fallback": "none"
}

Headers

Section titled “Headers”
Cache-Control
required
string
Allowed value: no-store

禁止缓存绑定、票据、状态及模型响应。

413

Section titled “413”

Payload_too_large

Media typeapplication/json
One of:
object
protocol
required
Allowed value: sdk2-cache-v1
requestId
required
string
>= 1 characters <= 128 characters /^[A-Za-z0-9][A-Za-z0-9._~-]*$/
code
required
string
Allowed values: invalid_request protocol_version_mismatch unauthorized forbidden stale_revision stale_generation request_id_conflict projection_stale ticket_expired mapping_expired receipt_expired payload_too_large unsupported_capability capacity_exceeded epoch_unavailable mapping_unavailable result_unknown
status
required
integer
>= 400 <= 503
retryAction
required
string
Allowed values: none same-request query-status refresh-projection
fallback
required
Allowed value: none
message
required
string
>= 1 characters <= 256 characters
Example
{
  "protocol": "sdk2-cache-v1",
  "code": "invalid_request",
  "retryAction": "none",
  "fallback": "none"
}

Headers

Section titled “Headers”
Cache-Control
required
string
Allowed value: no-store

禁止缓存绑定、票据、状态及模型响应。

422

Section titled “422”

Unsupported_capability

Media typeapplication/json
One of:
object
protocol
required
Allowed value: sdk2-cache-v1
requestId
required
string
>= 1 characters <= 128 characters /^[A-Za-z0-9][A-Za-z0-9._~-]*$/
code
required
string
Allowed values: invalid_request protocol_version_mismatch unauthorized forbidden stale_revision stale_generation request_id_conflict projection_stale ticket_expired mapping_expired receipt_expired payload_too_large unsupported_capability capacity_exceeded epoch_unavailable mapping_unavailable result_unknown
status
required
integer
>= 400 <= 503
retryAction
required
string
Allowed values: none same-request query-status refresh-projection
fallback
required
Allowed value: none
message
required
string
>= 1 characters <= 256 characters
Example
{
  "protocol": "sdk2-cache-v1",
  "code": "invalid_request",
  "retryAction": "none",
  "fallback": "none"
}

Headers

Section titled “Headers”
Cache-Control
required
string
Allowed value: no-store

禁止缓存绑定、票据、状态及模型响应。

429

Section titled “429”

Capacity_exceeded

Media typeapplication/json
One of:
object
protocol
required
Allowed value: sdk2-cache-v1
requestId
required
string
>= 1 characters <= 128 characters /^[A-Za-z0-9][A-Za-z0-9._~-]*$/
code
required
string
Allowed values: invalid_request protocol_version_mismatch unauthorized forbidden stale_revision stale_generation request_id_conflict projection_stale ticket_expired mapping_expired receipt_expired payload_too_large unsupported_capability capacity_exceeded epoch_unavailable mapping_unavailable result_unknown
status
required
integer
>= 400 <= 503
retryAction
required
string
Allowed values: none same-request query-status refresh-projection
fallback
required
Allowed value: none
message
required
string
>= 1 characters <= 256 characters
Example
{
  "protocol": "sdk2-cache-v1",
  "code": "invalid_request",
  "retryAction": "none",
  "fallback": "none"
}

Headers

Section titled “Headers”
Cache-Control
required
string
Allowed value: no-store

禁止缓存绑定、票据、状态及模型响应。

500

Section titled “500”

原 TWP 资金或供应商错误，保持原错误合同。

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"
  }
}

Headers

Section titled “Headers”
Cache-Control
required
string
Allowed value: no-store

禁止缓存绑定、票据、状态及模型响应。

502

Section titled “502”

原 TWP 资金或供应商错误，保持原错误合同。

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"
  }
}

Headers

Section titled “Headers”
Cache-Control
required
string
Allowed value: no-store

禁止缓存绑定、票据、状态及模型响应。

503

Section titled “503”

Epoch_unavailable、mapping_unavailable 或 result_unknown；未知结果不得自动重新执行或回退旧接口。

Media typeapplication/json
One of:
object
protocol
required
Allowed value: sdk2-cache-v1
requestId
required
string
>= 1 characters <= 128 characters /^[A-Za-z0-9][A-Za-z0-9._~-]*$/
code
required
string
Allowed values: invalid_request protocol_version_mismatch unauthorized forbidden stale_revision stale_generation request_id_conflict projection_stale ticket_expired mapping_expired receipt_expired payload_too_large unsupported_capability capacity_exceeded epoch_unavailable mapping_unavailable result_unknown
status
required
integer
>= 400 <= 503
retryAction
required
string
Allowed values: none same-request query-status refresh-projection
fallback
required
Allowed value: none
message
required
string
>= 1 characters <= 256 characters
Example
{
  "protocol": "sdk2-cache-v1",
  "code": "invalid_request",
  "retryAction": "none",
  "fallback": "none"
}

Headers

Section titled “Headers”
Cache-Control
required
string
Allowed value: no-store

禁止缓存绑定、票据、状态及模型响应。

504

Section titled “504”

原 TWP 资金或供应商错误，保持原错误合同。

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"
  }
}

Headers

Section titled “Headers”
Cache-Control
required
string
Allowed value: no-store

禁止缓存绑定、票据、状态及模型响应。