# 文件上传(大文件)

**Base URL:** `https://openapi.tripo3d.ai/v3`

**Endpoint:** `POST /files/presign`

获取预签名上传 URL，文件直传存储——**大文件上传性能更优**。 客户端无需 SDK，仅需标准 HTTP PUT 即可完成上传。 建议文件超过 60MB 时使用；小文件也可使用 文件上传（multipart，最大 150MB）。上传流程
- 调用 `POST /v3/files/presign`，传入 `format`，获取 `presigned_url` 与 `file_token`。
- 使用 **HTTP PUT** 将文件直传到 `presigned_url`（直达存储，无需 Auth 头）。
- 在后续 API 的 `input` 字段中使用 `file_token`（如 导入模型、重拓扑、格式转换）。




## Request Parameters

### format

- **Type:** string
- **Required:** 必选

文件扩展名，不含前导点（如 glb、fbx、png）。


- 图片：`jpeg`、`jpg`、`png`、`webp`、`bmp`、`tiff`。
- 模型：`glb`、`gltf`、`fbx`、`obj`、`stl`、`3mf`、`usdz`。


## Response Fields

### presigned_url

- **Type:** string
- **Required:** 必选

预签名 PUT URL，30 分钟内有效。客户端使用 HTTP PUT 直传文件到该 URL。
### file_token

- **Type:** string
- **Required:** 必选

文件引用 token（如 `file_abc123`）。上传完成后在其他 API 的 `input` 字段中使用。
### expires_in

- **Type:** integer
- **Required:** 必选

预签名 URL 有效期（秒），固定为 1800（30 分钟）。

## Request Example

### curl

```
# Step 1: Get presigned URL
curl -s -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"format":"glb"}' \
  https://openapi.tripo3d.ai/v3/files/presign

# Step 2: Upload file directly to storage (no Auth needed)
curl -X PUT \
  -H "Content-Type: application/octet-stream" \
  -T model.glb \
  "<presigned_url from step 1>"

# Step 3: Create task using file_token
curl -s -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"default","input":"<file_token from step 1>"}' \
  https://openapi.tripo3d.ai/v3/models/import
```

### Python

```
import requests

API_KEY = "YOUR_API_KEY"
BASE = "https://openapi.tripo3d.ai"
headers = {"Authorization": f"Bearer {API_KEY}"}

# 1. Get presigned URL
resp = requests.post(f"{BASE}/v3/files/presign",
                     json={"format": "glb"}, headers=headers)
data = resp.json()["data"]
presigned_url = data["presigned_url"]
file_token = data["file_token"]

# 2. Upload file directly to storage
with open("model.glb", "rb") as f:
    put_resp = requests.put(presigned_url, data=f,
                            headers={"Content-Type": "application/octet-stream"})
    assert put_resp.status_code == 200

# 3. Create task with file_token
task_resp = requests.post(f"{BASE}/v3/models/import",
    json={"model": "default", "input": file_token},
    headers=headers)
print(task_resp.json())
```

### JavaScript

```
import fs from 'fs';

const API_KEY = 'YOUR_API_KEY';
const BASE = 'https://openapi.tripo3d.ai';

// 1. Get presigned URL
const presignRes = await fetch(`${BASE}/v3/files/presign`, {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({ format: 'glb' }),
});
const { data } = await presignRes.json();
const { presigned_url, file_token } = data;

// 2. Upload file directly to storage
const fileBuffer = fs.readFileSync('model.glb');
await fetch(presigned_url, {
  method: 'PUT',
  headers: { 'Content-Type': 'application/octet-stream' },
  body: fileBuffer,
});

// 3. Create task with file_token
const taskRes = await fetch(`${BASE}/v3/models/import`, {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({ model: 'default', input: file_token }),
});
console.log(await taskRes.json());
```


## Response Example

### 预签名响应

```json
{
  "code": 0,
  "data": {
    "presigned_url": "https://storage.example.com/bucket/path/input.glb?X-Amz-Signature=...",
    "file_token": "file_abc123",
    "expires_in": 1800
  }
}
```