> For the complete documentation index, see [llms.txt](https://getsquish.gitbook.io/squish/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://getsquish.gitbook.io/squish/zh/ru-men/quickstart-api.md).

# 快速开始：托管 API

**让 AI 能随机访问视频。** 托管 API 是通往与 CLI 和 MCP 服务器相同引擎的远程路径： `POST` 一个视频，返回带时间戳的 contact sheet JPG 以及包含每个单元格时间码的 JSON 元数据。当工作流无法运行本地工具时使用它——CI、无服务器环境、托管代理，或任何没有 ffmpeg 的机器。

{% hint style="info" %}
**这条路径是有意上传——上传到计算服务，而不是存储服务。** 上传的视频会在任务结束的那一刻被删除，无论成功还是失败；它不会被保留，也不会用于训练。输出表会在 capability URLs 上作为临时缓存保存（大约 24 小时），之后自动过期——请下载保存。需要更强的保障？在本地运行 Squish：the [CLI](/squish/zh/ru-men/quickstart-cli.md) 和 [MCP 服务器](/squish/zh/ru-men/quickstart-mcp.md) 永远不要上传你的视频。
{% endhint %}

## 获取一个密钥

1. 打开 [getsquish.app/api-keys](https://getsquish.app/api-keys) 并使用邮箱验证码登录。
2. 购买一个 credit 包（$3 = 30 · $9 = 120 · $29 = 500 credits）——或者跳过这一步：从未购买过任何东西的账号会在第一次请求时自动获得免费的每日额度。
3. 创建一个密钥并复制它 **一次**。密钥看起来像 `sq_live_` + 40 个十六进制字符；系统只存储哈希，因此丢失的密钥无法找回，只能替换。

## 首次请求

端点： `POST https://api.getsquish.app/v1/squish`。使用以下方式认证： `Authorization: Bearer <key>`；发送 `multipart/form-data` 并且只包含一个名为 **`video`**:

```bash
curl -s -X POST https://api.getsquish.app/v1/squish \
  -H "Authorization: Bearer sq_live_…" \
  -F "video=@clip.mov" \
  -F "density=3x3"
```

可选字段： `density` (`3x3`–`6x6`，默认 `3x3` ——更高的 density 每张表会消耗更多 credits）以及 `响应` (`json` 默认，或 `image` 可直接返回第一张表的 JPG，元数据在 `x-squish-job` 和 `x-credits-remaining` headers 中）。

## 响应内容

```json
{
  "job_id": "...",
  "input": "clip.mov",
  "duration": 10.0,
  "frames": 9,
  "sheets": 1,
  "density": "3x3",
  "credits_charged": 1,
  "credits_remaining": 33,
  "files": ["https://api.getsquish.app/v1/sheets/<job_id>/video.sheet-1.jpg"],
  "timecodes": [["0:00", "0:01", "0:02", "0:03", "0:05", "0:06", "0:07", "0:08", "0:10"]],
  "warnings": [],
  "contract": "squish-http-v0"
}
```

一次同步请求就覆盖整个生命周期——没有任务队列，没有轮询，没有 webhook；连接会在整个持续时间内保持打开状态（对典型片段来说是几秒）。 `job_id` 是收据：它会出现在表格 URL 以及你在 [getsquish.app/api-keys](https://getsquish.app/api-keys)。 `契约` 字段（`squish-http-v0`）是版本标记——解析它以检测破坏性变更。

## Credits 和每日免费额度

Credits 需预付，并按密度按每个输出表计费： `3x3` = 1 · `4x4` = 2 · `5x5` = 3 · `6x6` = 5。准确费用会在 **任何** 帧被提取之前就已知；如果在扣费后引擎失败，会自动退款。

一个 **从未购买过任何东西** （没有 web Pro，也没有 credit 包）会自动补到一个较低的下限——目前为 **7 credits** ——每 **UTC 日**最多一次，在当天第一次计费请求发现余额低于下限时触发。这是补到下限，而不是递增：未使用的额度不会累积，达到或高于下限时不会再发放任何额度，已购买的余额也不会被动用。

## 需要了解的限制

* 上传上限： **300 MB**。时长上限： **30 分钟**.
* 同一时间只处理一个任务，队列很短——超载时返回 `429 忙碌` （不会扣费；约 10–30 秒后可安全重试）。
* **目前 `start`/`end` 还没有 window。** 托管请求始终覆盖整个片段； `start`/`end` 这些字段会被忽略。本地 [CLI](/squish/zh/ru-men/quickstart-cli.md) 和 [MCP 服务器](/squish/zh/ru-men/quickstart-mcp.md) 接受 `start`/`end` 用于 [导航循环](/squish/zh/primitive/the-navigation-loop.md).
* 连通性： `GET https://api.getsquish.app/healthz` （无需认证）——可区分“API 挂了”和“我的请求有问题”。

完整错误表（`401` / `402` / `413` / `422` / `429` / `500` 包含 `已退款的` 字段）以及重试策略位于 [HTTP API 参考](/squish/zh/can-kao/http-api.md).

## 下一步

* [HTTP API 参考](/squish/zh/can-kao/http-api.md) ——错误、重试策略、限制和冻结的 contract。
* [隐私与数据流](/squish/zh/primitive/privacy-and-data-flow.md) ——三种处理路径（web、本地 CLI/MCP、托管 API）有何不同。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://getsquish.gitbook.io/squish/zh/ru-men/quickstart-api.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.