> ## Documentation Index
> Fetch the complete documentation index at: https://docs.squarecloud.app/llms.txt
> Use this file to discover all available pages before exploring further.

# 创建 snapshot

> 为你的应用执行一次 snapshot。速率限制为每 5 秒 1 个请求。

<Warning>每个账户每 24 小时最多可执行 (RAM / 256) \* 2 次 snapshot。</Warning>

<ParamField header="Authorization" type="string" placeholder="API Key" required>
  你账户的 API 密钥。你可以在[账户设置](https://squarecloud.app/zh/account/security)中找到它。
</ParamField>

### 参数

<ParamField path="app_id" type="string" placeholder="Application ID" required>
  应用的 ID。你可以在应用控制面板的 URL 中找到它。
</ParamField>

### 软截止（soft deadline）行为

此路由遵循**软截止**模型 —— 它不再总是同步响应。

* 如果 snapshot 在 **约 90 秒** 内完成，路由将返回 `200 success` 以及一个签名下载 URL（有效期 30 天），与以前完全相同。
* 如果 snapshot 生成时间超过 **约 90 秒**，路由将**立即**返回 `202` 及代码 `SNAPSHOT_PROCESSING`。**这不是失败。** snapshot 会在后台继续生成，并会自行出现在 [snapshot 列表](/zh/api-reference/endpoint/apps/snapshots/list) 中，通常在约 2 分钟内。对于大型应用而言这是预期行为。

<Warning>
  不要将此 `POST` 端点用作轮询机制。要检查处于 `SNAPSHOT_PROCESSING` 状态的 snapshot 是否已完成，请使用 [列出 Snapshot](/zh/api-reference/endpoint/apps/snapshots/list)（`GET`）端点 —— **而非**再次 `POST`。在 snapshot 完成后重新 POST 会从头开始一个全新的 snapshot。
</Warning>

客户端应按如下方式对响应进行分支处理：

| 响应                                                      | 含义              | 应对方式                                                                                                  |
| ------------------------------------------------------- | --------------- | ----------------------------------------------------------------------------------------------------- |
| `status === "success"`                                  | snapshot 已就绪。   | 使用 `url` 下载它。                                                                                         |
| `status === "error"` 且 `code === "SNAPSHOT_PROCESSING"` | snapshot 仍在生成中。 | 等待约 2 分钟，然后通过 [列出 Snapshot](/zh/api-reference/endpoint/apps/snapshots/list)（`GET`）确认。**不要**重新 `POST`。 |
| `status === "error"` 且带有任何其他 `code`                     | 实际失败。           | 处理错误（见下文）。                                                                                            |

### 响应

<ResponseField name="status" type="string">
  指示调用是否成功。成功时为 `success`，否则为 `error`。
</ResponseField>

<ResponseField name="response" type="object">
  响应的内容。仅当 `status` 为 `success` 时存在。

  <Expandable title="切换对象">
    <ResponseField name="url" type="string">
      下载应用 snapshot 的 URL。
    </ResponseField>

    <ResponseField name="key" type="string">
      下载应用 snapshot 的密钥。
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="SNAPSHOT_PROCESSING" type="202">
  当 snapshot 超过约 90 秒的软截止时返回。snapshot 仍在后台生成，并会自行出现在 snapshot 列表中，通常在约 2 分钟内。这不是错误 —— 请等待并通过 `GET` 列表端点确认。
</ResponseField>

### 错误

snapshot 请求可能会以 `429 Too Many Requests` 被拒绝。使用 `code` 字段区分这两种情况：

<ResponseField name="KEEP_CALM" type="429">
  短期冷却 —— 你触发了每用户（每 5 秒 1 个请求）或每应用（每 180 秒 1 个请求）的限制。请稍后退避并重试。
</ResponseField>

<ResponseField name="DAILY_SNAPSHOTS_LIMIT_REACHED" type="429">
  已达每日配额 —— 账户已用尽其套餐的每日 snapshot 额度（每 24 小时 (RAM / 256) × 2 次）。随着滚动的 24 小时窗口推进，配额会释放；如需更高的每日额度，请升级套餐。
</ResponseField>

<ResponseExample>
  ```json 200 Success theme={null}
  {
      "status": "success",
      "response": {
          "url": "https://snapshots.squarecloud.app/applications/23457145698959364/a23d130fcc9ddaf2d288ae9599a4292c32.zip?AWSAccessKeyId=i06Xdad2dRD74Pm8Xly&Expires=1753081182&Signature=riWPedawcsouRAPGU5n3kGHnWoOuw%3D",
          "key": "AWSAccessKeyId=i06Xdad2dRD74Pm8Xly&Expires=1753081182&Signature=riWPedawcsouRAPGU5n3kGHnWoOuw%3D"
      }
  }
  ```

  ```json 202 SNAPSHOT_PROCESSING theme={null}
  {
    "status": "error",
    "code": "SNAPSHOT_PROCESSING"
  }
  ```

  ```json 429 KEEP_CALM theme={null}
  {
    "status": "error",
    "code": "KEEP_CALM",
    "message": "You already requested a snapshot recently. Please wait a minute before trying again. 1r/5s"
  }
  ```

  ```json 429 DAILY_SNAPSHOTS_LIMIT_REACHED theme={null}
  {
    "status": "error",
    "code": "DAILY_SNAPSHOTS_LIMIT_REACHED",
    "message": "You are being rate limited for daily snapshots. 8r/24h"
  }
  ```
</ResponseExample>