种子字段的对外类型改成普通数字,不再导出 bigint

- shared-contracts:多视图请求与文生 / 图生参数的 seed 注记从 `bigint | null` 改成 `number | null`,并写明只支持 JS 安全整数范围(2^53-1)内的取值;Rust 侧仍是 `Option<i64>`,反序列化行为不变
- packages/shared:重新生成 model3d 绑定,seed 变成 `number | null`,请求体可以直接 JSON 序列化(带 bigint 的请求在 JSON.stringify 阶段必定抛错);顺带补上此前漏生成的多视图请求文档注释(「多视图生 3D」→「多视图生成 3D」)
- docs/technical:在 Tripo Provider 集成方案里写明 seed 为什么按 number 导出、代价是超出 2^53-1 的取值无法从 TS 侧精确构造
This commit is contained in:
2026-09-24 19:17:42 +08:00
parent c39798e491
commit 5748cf303f
7 changed files with 23 additions and 18 deletions
@@ -22,6 +22,8 @@ task 尚未完成时 `output` 为空;完成后 `output` 必须是与 task type
生成结果 DTO 中的 `poll_after_ms`、`updated_at_micros` 与 `size_bytes` 以 TypeScript `number` 导出:毫秒级轮询间隔与几十 MB 的产物字节数远低于 2^53,微秒时间戳在 2^53 内也可精确表示(约到公元 2255 年),因此不做 `bigint`/`string` 特殊处理;若将来出现超过 2^53 的取值再评估。
生成参数里的 seed(`image_seed`、`model_seed`、`texture_seed`)同样以 TypeScript `number` 导出,不导出成 `bigint`:请求最终是 JSON 文本,JSON 没有大整数类型,带 `bigint` 的请求体在 `JSON.stringify` 阶段就会直接抛错。代价是前端能精确表示的取值上限为 2^53-1(JS 安全整数),超出该范围的种子没法从 TS 侧精确构造;Rust 侧仍按 `i64` 反序列化,手工构造的请求可以传更大取值。
## 三个入口的输入
- text-to-model:`prompt` 必填,上限 1024 字符;`negative_prompt` 上限 255 字符。空白 prompt 在提交前拒绝。
@@ -17,8 +17,8 @@ import type { Model3dTextureVersion } from '../common/Model3dTextureVersion';
export type Model3dImageToModelParams = {
model: Model3dModelVersion;
enableImageAutofix?: boolean | null;
modelSeed?: bigint | null;
textureSeed?: bigint | null;
modelSeed?: number | null;
textureSeed?: number | null;
texture?: boolean | null;
pbr?: boolean | null;
textureQuality?: Model3dTextureQuality | null;
@@ -10,7 +10,7 @@ import type { Model3dTextureVersion } from '../common/Model3dTextureVersion';
import type { Model3dMultiviewInputs } from './Model3dMultiviewInputs';
/**
* 多视图生 3D 的请求:`inputs` 必填,其余生成参数可选。
* 多视图生成 3D 的请求:`inputs` 必填,其余生成参数可选。
*
* 严格反序列化:顶层与 `inputs` 分支都不接受未知字段,字段取值非法在反序列化阶段即拒绝;
* 组合合法性(模型能力、参数互斥)由 provider 侧提交前统一校验。
@@ -27,11 +27,11 @@ export type Model3dMultiviewToModelRequest = {
/**
* 模型随机种子;固定后可复现同一几何体。
*/
modelSeed?: bigint | null;
modelSeed?: number | null;
/**
* 贴图随机种子;固定后可复现同一贴图。
*/
textureSeed?: bigint | null;
textureSeed?: number | null;
/**
* 是否生成贴图;`false` 时只产出白模几何体。
*/
@@ -16,9 +16,9 @@ export type Model3dTextToModelParams = {
prompt: string;
model: Model3dModelVersion;
negativePrompt?: string | null;
imageSeed?: bigint | null;
modelSeed?: bigint | null;
textureSeed?: bigint | null;
imageSeed?: number | null;
modelSeed?: number | null;
textureSeed?: number | null;
texture?: boolean | null;
pbr?: boolean | null;
textureQuality?: Model3dTextureQuality | null;
@@ -19,11 +19,12 @@ pub struct Model3dImageToModelParams {
pub model: Model3dModelVersion,
#[ts(optional = nullable)]
pub enable_image_autofix: Option<bool>,
// seed 是 i64,JS `number` 表示不了全部取值,因此按 bigint 导出,避免静默舍入。
#[ts(type = "bigint | null")]
// seed 是 i64;对外只按 JSON 数字传递,前端能精确表示的上限是 2^53-1(JS 安全整数),
// 超出该范围的取值没法在前端精确构造,服务端仍按 i64 反序列化。
#[ts(type = "number | null")]
#[ts(optional = nullable)]
pub model_seed: Option<i64>,
#[ts(type = "bigint | null")]
#[ts(type = "number | null")]
#[ts(optional = nullable)]
pub texture_seed: Option<i64>,
#[ts(optional = nullable)]
@@ -79,13 +79,14 @@ pub struct Model3dMultiviewToModelRequest {
pub inputs: Model3dMultiviewInputs,
/// 模型版本;决定模型家族与可用的生成能力。
pub model: Model3dModelVersion,
// seed 是 i64,JS `number` 表示不了全部取值,因此按 bigint 导出,避免静默舍入。
// seed 是 i64;对外只按 JSON 数字传递,前端能精确表示的上限是 2^53-1(JS 安全整数),
// 超出该范围的取值没法在前端精确构造,服务端仍按 i64 反序列化。
/// 模型随机种子;固定后可复现同一几何体。
#[ts(type = "bigint | null")]
#[ts(type = "number | null")]
#[ts(optional = nullable)]
pub model_seed: Option<i64>,
/// 贴图随机种子;固定后可复现同一贴图。
#[ts(type = "bigint | null")]
#[ts(type = "number | null")]
#[ts(optional = nullable)]
pub texture_seed: Option<i64>,
/// 是否生成贴图;`false` 时只产出白模几何体。
@@ -19,14 +19,15 @@ pub struct Model3dTextToModelParams {
pub model: Model3dModelVersion,
#[ts(optional = nullable)]
pub negative_prompt: Option<String>,
// seed 是 i64,JS `number` 表示不了全部取值,因此按 bigint 导出,避免静默舍入。
#[ts(type = "bigint | null")]
// seed 是 i64;对外只按 JSON 数字传递,前端能精确表示的上限是 2^53-1(JS 安全整数),
// 超出该范围的取值没法在前端精确构造,服务端仍按 i64 反序列化。
#[ts(type = "number | null")]
#[ts(optional = nullable)]
pub image_seed: Option<i64>,
#[ts(type = "bigint | null")]
#[ts(type = "number | null")]
#[ts(optional = nullable)]
pub model_seed: Option<i64>,
#[ts(type = "bigint | null")]
#[ts(type = "number | null")]
#[ts(optional = nullable)]
pub texture_seed: Option<i64>,
#[ts(optional = nullable)]