> 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/th/reference/http-api.md).

# Hosted API

API ที่โฮสต์ไว้จะแปลง **ที่อัปโหลดโดยตั้งใจ** วิดีโอให้เป็น JPEG แบบแผ่นสรุปภาพที่มีเวลาแปะกำกับ พร้อมข้อมูลเมตา JSON และรหัสเวลา ใช้เมื่อขั้นตอนการทำงานไม่สามารถรันเครื่องมือภายในเครื่องได้ [CLI](/squish/th/reference/cli.md)/[MCP](/squish/th/reference/mcp.md) เครื่องมือ (CI, ไร้เซิร์ฟเวอร์, ตัวแทนที่โฮสต์ไว้, ไม่มี ffmpeg). สำหรับขั้นตอนการทำงานภายในเครื่อง ให้ใช้ CLI/เซิร์ฟเวอร์ MCP แทน — มันประมวลผลทุกอย่างบนเครื่องของคุณและไม่อัปโหลดอะไรเลย ดู [ความเป็นส่วนตัวและการไหลของข้อมูล](/squish/th/the-primitive/privacy-and-data-flow.md).

สตริงสัญญา: `squish-http-v0` (ดู [ความเสถียรและการกำหนดเวอร์ชัน](/squish/th/reference/stability.md)).

## จุดเชื่อมต่อ

```
POST https://api.getsquish.app/v1/squish
```

คำขอแบบซิงโครนัสเพียงครั้งเดียวคือทั้งงาน — ไม่มี API คิวงาน, ไม่มีจุดเชื่อมต่อสำหรับตรวจสถานะแบบโพล, ไม่มีเว็บฮุก

## การยืนยันตัวตน

* ส่วนหัว: `Authorization: Bearer <key>`
* รูปแบบคีย์: `sq_live_` + อักขระฐานสิบหก 40 ตัว, สร้างบน [getsquish.app/api-keys](https://getsquish.app/api-keys) (ลงชื่อเข้าใช้ด้วย OTP ทางอีเมล).
* คีย์แบบข้อความธรรมดาจะแสดง **ครั้งเดียว** — ระบบเก็บไว้แค่แฮช SHA-256 ของมัน ดังนั้นคีย์ที่หายไปกู้คืนไม่ได้ ทำได้แค่สร้างใหม่
* หากคีย์หาย, รูปแบบไม่ถูกต้อง หรือถูกเพิกถอน จะคืน `401 invalid_key` ก่อนอ่านเนื้อหา

## คำขอ

`multipart/form-data` โดยมีช่องไฟล์เพียงช่องเดียว และต้องชื่อ **`video`** (`video=@clip.mov`); ส่วนไฟล์ส่วนอื่นจะถูกละเลย

ช่องข้อมูลในฟอร์มที่เลือกใส่ได้:

| ช่องข้อมูล   | ค่า                        | ค่าเริ่มต้น | หมายเหตุ                                                                         |
| ------------ | -------------------------- | ----------- | -------------------------------------------------------------------------------- |
| `density`    | `3x3`, `4x4`, `5x5`, `6x6` | `3x3`       | ความหนาแน่นที่สูงขึ้นจะใช้เครดิตต่อแผ่นมากขึ้น ([เครดิต](#credits-and-pricing)). |
| `การตอบกลับ` | `json`, `รูปภาพ`           | `json`      | `รูปภาพ` จะส่งคืน JPEG ของแผ่นแรกโดยตรง ([ด้านล่าง](#responseimage)).            |

{% hint style="warning" %}
**ยังไม่มีหน้าต่างซูม** API ที่โฮสต์ไว้ไม่รับ `start`/`end` — คำขอหนึ่งครั้งครอบคลุมทั้งคลิปเสมอ และ `start`/`end` ช่องข้อมูลที่คุณส่งไปจะถูกละเลย [ลูปการนำทาง](/squish/th/the-primitive/the-navigation-loop.md)ขั้นซูมของมันตอนนี้ใช้ได้เฉพาะใน CLI/MCP ภายในเครื่องเท่านั้น การรองรับหน้าต่างจะมาพร้อมช่วงวิดีโอ (อัปโหลดครั้งเดียว, บีบหลายแบบ).
{% endhint %}

## ผลลัพธ์ JSON

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

`ไฟล์` เป็น URL ความสามารถแบบชั่วคราว (ดู [วงจรชีวิตของงาน](#job-lifecycle)). ไฟล์แผ่นสรุปจะถูกตั้งชื่อเป็น `video.sheet-N.jpg` — เซิร์ฟเวอร์จะเก็บไฟล์ที่อัปโหลดไว้ภายใต้ชื่อคงที่ของมันเอง ดังนั้นชื่อไฟล์ต้นฉบับจะไม่ปรากฏใน URL เลย; มันจะถูกสะท้อนกลับใน `input` ช่องข้อมูลแทน (ดู [สัญญาชื่อไฟล์](/squish/th/reference/sheet-format.md#filename-contract)). `timecodes[][]` จะตรงกับป้ายกำกับที่ประทับบนพิกเซลของแผ่นเสมอ — รูปแบบ `m:ss`, ความละเอียดต่ำกว่าหนึ่งวินาที `m:ss.d` บนคลิปสั้น ๆ ที่การใช้ทั้งวินาทีแยกเซลล์ที่ติดกันไม่ออก (ดู [สเปกของรูปแบบแผ่น](/squish/th/reference/sheet-format.md#timecode-grammar)). คลิปยาวจะสร้างหลายแผ่นตามลำดับ — ให้อ่านทั้งหมด

### response=image

`response=image` จะส่งคืน **แผ่นแรก** JPEG โดยตรงแทน JSON โดยมีข้อมูลเมตาอยู่ในส่วนหัว: `x-squish-job` (รหัสงาน) และ `x-credits-remaining`. งานที่มีหลายแผ่นควรใช้โหมด JSON แบบค่าเริ่มต้น — โหมดภาพไม่มี URL สำหรับแผ่นอื่น ๆ และไม่มีรหัสเวลา

## ข้อผิดพลาด

| สถานะ | ข้อผิดพลาด             | ความหมาย                                                                                                       | วิธีแก้                                                                                                                                                                            |
| ----: | ---------------------- | -------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `401` | `invalid_key`          | ไม่มีคีย์, ถูกเพิกถอน หรือคีย์ผิด                                                                              | สร้าง/คัดลอกคีย์จาก [`/api-keys`](https://getsquish.app/api-keys).                                                                                                                 |
| `402` | `insufficient_credits` | ยอดคงเหลือต่ำเกินไป — สำหรับบัญชีที่ไม่เคยจ่าย ฟรีโควตาประจำวันถูกนำไปใช้โดยอัตโนมัติแล้วก่อนเกิดข้อผิดพลาดนี้ | เติมเงินที่ `/api-keys`, ลด `density`, หรือส่งคลิปที่สั้นลง; บัญชีที่ไม่เคยจ่ายยังสามารถรอวัน UTC ถัดไปได้                                                                         |
| `413` | `too_large`            | การอัปโหลดเกินขีดจำกัดปัจจุบัน (`max_mb` ในเนื้อหา)                                                            | ตัด/บีบอัด หรือใช้คลิปที่สั้นกว่า / ความหนาแน่นต่ำกว่า                                                                                                                             |
| `422` | `bad_request`          | รูปแบบคำขอผิด หรือ `density`/`การตอบกลับ` ค่า                                                                  | แก้คำขอให้ถูกก่อนลองใหม่                                                                                                                                                           |
| `422` | `unreadable_video`     | ไม่สามารถตรวจสอบไฟล์อัปโหลดว่าเป็นวิดีโอได้                                                                    | ส่งไฟล์วิดีโอจริงในคอนเทนเนอร์ที่ใช้กันทั่วไป                                                                                                                                      |
| `422` | `too_long`             | ระยะเวลาเกินขีดจำกัด (`max_s` ในเนื้อหา)                                                                       | ตัดคลิปหรือส่งคลิปที่สั้นกว่า                                                                                                                                                      |
| `429` | `busy`                 | ตัวประมวลผลงานเดี่ยวเต็มแล้ว                                                                                   | รอแล้วลองใหม่ภายหลัง                                                                                                                                                               |
| `500` | `processing_failed`    | เอนจินล้มเหลวหลังจากมีการคิดเงิน                                                                               | เนื้อหาคือ `{ "error": "processing_failed", "refunded": true\|false }` — **check `เครดิตที่คืน`**: `true` → ลองอีกครั้งหนึ่ง; `false` → การคิดเงินยังคงอยู่ ให้รายงานแทนการลองใหม่ |

## นโยบายการลองใหม่

สิ่งที่ลองใหม่ได้อย่างปลอดภัยขึ้นอยู่กับจังหวะที่เงินถูกเคลื่อนย้าย — เครดิตจะถูกหักแบบอะตอมมิก *หลังจาก* รู้ราคาที่แน่นอนแล้ว, *ก่อน* การแยกเฟรม:

* **`401`** **`402`** **`413`** **`422` — อย่าส่งซ้ำโดยไม่เปลี่ยน** ไม่มีการคิดเงิน; คำขอเดิมจะล้มเหลวแบบเดิม แก้สาเหตุก่อน (คีย์ใหม่, เติมเงิน, คลิปที่เล็ก/สั้นลง, แก้ช่องข้อมูลให้ถูกต้อง)
* **`429` — ลองใหม่ได้อย่างปลอดภัย** ไม่มี `Retry-After` ส่วนหัวใน `squish-http-v0`.
* **`500` — ให้อ่าน `เครดิตที่คืน` ในเนื้อหาก่อนลองใหม่** `refunded: true` (กรณีปกติ): ระบบคืนเงินอัตโนมัติแล้ว — ลองอีกครั้งหนึ่ง ถ้ายังล้มเหลวสองครั้งให้รายงาน `refunded: false` (พบไม่บ่อย): การคืนเงินอัตโนมัติเองล้มเหลว และการคิดเงินยังคงอยู่ — อย่า **ลองซ้ำแบบไม่ตรวจสอบ** ; ตารางการใช้งานบน `/api-keys` บันทึกต้นทุนสุทธิจริง
* **ไม่มีคีย์ idempotency.** คำขอที่ยอมรับทุกคำขอคือหนึ่งงานใหม่และหนึ่งการคิดเงินใหม่ — อย่าส่งคำขอที่อาจจะสำเร็จไปซ้ำแบบสุ่มสี่สุ่มห้า (การเชื่อมต่อหลุด *หลังจาก* ขณะประมวลผลก็ยังถูกคิดเงิน; ตรวจสอบตารางการใช้งานบน `/api-keys`).

## วงจรชีวิตของงาน

1. การอัปโหลดจะสตรีมลงดิสก์ (ไม่บัฟเฟอร์ในหน่วยความจำ).
2. ตรวจสอบ → วางแผน → คิดราคา → หักเครดิตแบบอะตอมมิก → แยกเฟรม → ส่งผลลัพธ์
3. การเชื่อมต่อจะเปิดค้างอยู่ตลอดช่วงเวลา (เป็นวินาทีสำหรับคลิปทั่วไป).
4. `job_id` ในผลลัพธ์เป็นใบเสร็จ: มันจะปรากฏใน URL ของแผ่น และในตารางการใช้งานของคุณบน `/api-keys`.

## วงจรชีวิตของข้อมูล

API ที่โฮสต์ไว้เป็น **บริการประมวลผล ไม่ใช่บริการจัดเก็บ** — งานแบบไร้สถานะที่มีแคชผลลัพธ์อายุสั้น ข้อมูลสองชนิดนี้อยู่บนเส้นทางคนละเส้น:

```
วิดีโอที่อัปโหลด ──► ประมวลผล ──► ลบทันทีที่งานจบ
                       │           (สำเร็จหรือล้มเหลว)
                       ▼
              แผ่นที่สร้างขึ้น ──► แคชชั่วคราว (~24 ชม.) ──► หมดอายุอัตโนมัติ
```

* **วิดีโอที่อัปโหลด** ใช้เพื่อประมวลผลคำขอที่ส่งมันมาเท่านั้น จากนั้นจะถูกลบทันทีที่งานจบ — ไม่ว่าจะสำเร็จหรือล้มเหลว ระบบจะไม่เก็บไว้ ไม่ใช้ฝึก และไม่มีคลังสื่อ
* **แผ่นที่สร้างขึ้น** เป็นแคชชั่วคราวที่ URL ความสามารถของมัน — เก็บไว้ราว 24 ชั่วโมง เพื่อให้คุณดาวน์โหลดหรือดึง URL มาใหม่ได้ จากนั้นจะหมดอายุและถูกลบอัตโนมัติ แคชนี้ไม่ใช่ที่เก็บ: ดาวน์โหลดทุกอย่างที่อยากเก็บไว้

ต้องการการรับประกันที่เข้มงวดกว่านี้? รัน Squish ภายในเครื่อง — [CLI](/squish/th/reference/cli.md) และ [MCP server](/squish/th/reference/mcp.md) จะไม่อัปโหลดวิดีโอของคุณเลย

## ขีดจำกัด

ขีดจำกัดปัจจุบันของ v0:

* ขนาดอัปโหลดสูงสุด: **300 MB**
* ขีดจำกัดระยะเวลา: **30 นาที**
* ประมวลผลได้ครั้งละหนึ่งงาน พร้อมคิวเล็ก ๆ; เมื่อโหลดเกินจะคืน `429 busy`
* ผลลัพธ์เป็นแบบชั่วคราว ไม่ใช่ที่เก็บถาวร

## เครดิตและราคา

เครดิตต้องจ่ายล่วงหน้าและคิดเงิน **ต่อแผ่นผลลัพธ์**, ตามความหนาแน่น:

| ความหนาแน่น | เครดิตต่อแผ่น |
| ----------- | ------------: |
| `3x3`       |             1 |
| `4x4`       |             2 |
| `5x5`       |             3 |
| `6x6`       |             5 |

แพ็กเกจปัจจุบัน: **$3 = 30 เครดิต · $9 = 120 เครดิต · $29 = 500 เครดิต.**

### โควต้าฟรีประจำวัน

บัญชีที่ **ไม่เคยซื้ออะไรเลย** (ไม่มี web Pro และไม่มีแพ็กเครดิต) จะถูกเติมขึ้นไปถึงขั้นต่ำเล็ก ๆ — ปัจจุบันคือ **7 เครดิต** — มากสุดเพียงครั้งเดียวต่อ **วัน UTC**, เมื่อคำขอที่มีราคาคิดเงินเป็นครั้งแรกของวันพบว่ายอดคงเหลือต่ำกว่าค่าต่ำสุด นี่เป็นการเติมให้ถึงค่าต่ำสุด ไม่ใช่การเพิ่มทีละนิด: โควต้าที่ไม่ได้ใช้จะไม่ทบกัน (ส่วนที่เหลือจากเมื่อวานจะลดสิ่งที่ได้รับวันนี้ ดังนั้นการใช้งานในหนึ่งวัน UTC จะไม่เกินค่าต่ำสุด), จะไม่มีการให้เมื่อถึงหรือสูงกว่าค่าต่ำสุด และยอดที่ซื้อไว้จะไม่ถูกแตะต้อง

## ตรวจสอบสถานะ

```
GET https://api.getsquish.app/healthz
```

ส่งคืน `{ "ok": true, "contract": "squish-http-v0", "version": "…" }` — ไม่ต้องยืนยันตัวตน มีประโยชน์ให้ตัวแทนแยก "API ล่ม" ออกจาก "คำขอของฉันผิด"

## แผ่นคืออะไร — และไม่ใช่อะไร

ดังนั้นให้ตัวแทนตั้งความคาดหวังให้ถูก:

* **เฉพาะภาพเท่านั้น.** แผ่นหนึ่งไม่มีเสียง พูด หรือบทถอดเสียง Squish มองเห็น; มันไม่ได้ยิน
* **แผนที่ลำดับ ไม่ใช่สิ่งทดแทนการเคลื่อนไหว** เฟรมถูกสุ่มตัวอย่างตลอดคลิป; เหตุการณ์ที่เกิดระหว่างจุดตัวอย่างจะมองไม่เห็น กริดที่ถี่ขึ้น (`4x4`–`6x6`) ช่วยลดช่องว่าง แต่ไม่ได้กำจัดมัน
* **ผลลัพธ์มีแค่ JPEG แบบแผ่นสรุปภาพเท่านั้น** (คุณภาพ 0.70), ความหนาแน่น `3x3`–`6x6`.
* **ไม่มีการวิเคราะห์ฝั่งเซิร์ฟเวอร์** 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/th/reference/http-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.