# Quickstart

> Make your first request and walk away with a vertical MP4 clip.

In this guide you check the key with a call that charges nothing, analyze a video, generate the clips and download the best one rendered.

**You will need:** a Cut.Pro account, an API key and `curl`. The complete examples at the end use Node.js 18+ or Python 3.9+.

## 1. Create the key

Open [API keys](https://cut.pro/studio/me/api-keys), click **New key** and copy the value. It appears only once.

```bash
export CUTPRO_API_KEY="paste_your_key_here"
```

## 2. Check the key

`GET /workspace` charges no credits and shows which workspace the key operates on.

```bash
curl https://api.cut.pro/api/v1/workspace \
  -H "X-Api-Key: $CUTPRO_API_KEY"
```

```json title="200 OK"
{
  "id": "7401220118845503",
  "name": "Ana's Studio",
  "is_personal": true,
  "status": "active",
  "role": "admin",
  "plan_name": "Pro",
  "plan_is_free": false,
  "credits": 120,
  "credits_unlimited": false,
  "created_at": "2026-03-02T14:11:09.000Z"
}
```

Got `401 UNAUTHORIZED`? The key is wrong or was revoked. Got `400 MISSING_WORKSPACE_ID`? The key reaches more than one workspace: see [Authentication](/en/authentication#key-with-more-than-one-workspace).

## 3. Analyze the video

Analyzing is free. The response carries the clipping cost and your balance.

```bash
curl -X POST https://api.cut.pro/api/v1/clips/info \
  -H "X-Api-Key: $CUTPRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ" }'
```

```json title="200 OK"
{
  "id": "7412908365112823",
  "title": "Rick Astley - Never Gonna Give You Up",
  "platform": "youtube",
  "duration": 213,
  "credits_cost": 4,
  "current_balance": 120
}
```

Keep the `id`: it is the `video_id` for the next steps.

## 4. Generate the clips

> This is the step that charges. The `credits_cost` amount leaves the balance immediately, and comes back if you cancel before it finishes.

```bash
curl -X POST https://api.cut.pro/api/v1/clips \
  -H "X-Api-Key: $CUTPRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "video_id": "7412908365112823" }'
```

```json title="201 Created"
{
  "id": "7412908371004912",
  "video_id": "7412908365112823",
  "status": "queued",
  "credits_charged": 4
}
```

## 5. Wait for it to finish

Poll the submission every 5 to 10 seconds until `status` becomes `completed` or `failed`.

```bash
curl https://api.cut.pro/api/v1/clips/7412908365112823/submissions/7412908371004912 \
  -H "X-Api-Key: $CUTPRO_API_KEY"
```

```json title="200 OK"
{
  "id": "7412908371004912",
  "video_id": "7412908365112823",
  "status": "completed",
  "error_code": null,
  "clips_count": 9,
  "completed_at": "2026-10-29T18:04:51.000Z"
}
```

## 6. Get the best clip

Each clip has a score from 0 to 10. Sort by it and ask for one.

```bash
curl "https://api.cut.pro/api/v1/clips/7412908365112823/submissions/7412908371004912/clips?sort=rating&order=desc&limit=1" \
  -H "X-Api-Key: $CUTPRO_API_KEY"
```

```json title="200 OK"
{
  "clips": [
    {
      "id": "7412908412887301",
      "title": "The chorus everyone knows",
      "rating": 9.2,
      "start_time": 42.5,
      "end_time": 71.0,
      "language": "en",
      "has_template_applied": false,
      "edit_id": null
    }
  ],
  "pagination": { "current_page": 1, "total_pages": 9, "total_count": 9, "has_next_page": true, "has_previous_page": false, "limit": 1 }
}
```

## 7. Render and download

Request the clip render. Without a template, it comes out with the default settings.

```bash
curl -X POST https://api.cut.pro/api/v1/clips/7412908365112823/submissions/7412908371004912/clips/7412908412887301/render \
  -H "X-Api-Key: $CUTPRO_API_KEY"
```

```json title="202 Accepted"
{
  "id": "7412908490112774",
  "edit_id": "7412908488820131",
  "status": "queued",
  "output_resolution": "1080p",
  "from_cache": false,
  "download_url": null
}
```

Poll `GET /renders/7412908490112774` until `status` becomes `completed`, then ask for the link:

```bash
curl https://api.cut.pro/api/v1/renders/7412908490112774/download \
  -H "X-Api-Key: $CUTPRO_API_KEY"
```

```json title="200 OK"
{
  "url": "https://...",
  "filename": "the-chorus-everyone-knows.mp4"
}
```

The link is valid for 1 hour. Done: that is your clip.

## The whole flow in one file

Steps 3 to 7 chained, with the waiting handled. Swap the URL and run it.

**Node.js**

```js title="quickstart.mjs"
const API = "https://api.cut.pro/api/v1";
const headers = { "X-Api-Key": process.env.CUTPRO_API_KEY, "Content-Type": "application/json" };
const PENDING = ["queued", "active", "waiting_quality"];

async function call(path, init) {
	const response = await fetch(`${API}${path}`, { ...init, headers });
	const body = await response.json();
	if (!response.ok) throw new Error(`${response.status} ${body.code}`);
	return body;
}

const wait = (seconds) => new Promise((resolve) => setTimeout(resolve, seconds * 1000));

const video = await call("/clips/info", {
	method: "POST",
	body: JSON.stringify({ url: "https://www.youtube.com/watch?v=dQw4w9WgXcQ" }),
});
console.log(`${video.title}: ${video.credits_cost} credits`);

const submission = await call("/clips", { method: "POST", body: JSON.stringify({ video_id: video.id }) });
const base = `/clips/${video.id}/submissions/${submission.id}`;

let state = submission;
while (state.status !== "completed") {
	if (state.status === "failed") throw new Error(state.error_code);
	await wait(10);
	state = await call(base);
}

const { clips: [best] } = await call(`${base}/clips?sort=rating&order=desc&limit=1`);
const render = await call(`${base}/clips/${best.id}/render`, { method: "POST" });

let url = render.download_url;
while (!url) {
	await wait(10);
	const job = await call(`/renders/${render.id}`);
	if (job.status === "completed") url = (await call(`/renders/${render.id}/download`)).url;
	else if (!PENDING.includes(job.status)) throw new Error(job.status);
}

console.log(best.title, url);
```

**Python**

```python title="quickstart.py"

API = "https://api.cut.pro/api/v1"
HEADERS = {"X-Api-Key": os.environ["CUTPRO_API_KEY"]}
PENDING = ("queued", "active", "waiting_quality")

def call(path, method="GET", **kwargs):
    response = requests.request(method, f"{API}{path}", headers=HEADERS, **kwargs)
    body = response.json()
    if not response.ok:
        raise RuntimeError(f"{response.status_code} {body.get('code')}")
    return body

video = call("/clips/info", "POST", json={"url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"})
print(f"{video['title']}: {video['credits_cost']} credits")

submission = call("/clips", "POST", json={"video_id": video["id"]})
base = f"/clips/{video['id']}/submissions/{submission['id']}"

state = submission
while state["status"] != "completed":
    if state["status"] == "failed":
        raise RuntimeError(state["error_code"])
    time.sleep(10)
    state = call(base)

best = call(f"{base}/clips", params={"sort": "rating", "order": "desc", "limit": 1})["clips"][0]
render = call(f"{base}/clips/{best['id']}/render", "POST")

url = render["download_url"]
while not url:
    time.sleep(10)
    job = call(f"/renders/{render['id']}")
    if job["status"] == "completed":
        url = call(f"/renders/{render['id']}/download")["url"]
    elif job["status"] not in PENDING:
        raise RuntimeError(job["status"])

print(best["title"], url)
```

## Tweak the code

- **Cut only one section:** send `timeframe: { "start": 600, "end": 1800 }` in `POST /clips` to clip from minute 10 to 30.
- **Apply your style:** pass a `template_id` from `GET /templates` in `POST /clips` and every clip comes out with your captions and your framing.
- **Translate the captions:** `translate_to: "es"` in `POST /clips` generates the captions in Spanish. It costs more than plain clipping, and `credits_charged` shows how much was charged.
- **Use your own file:** replace step 3 with the [upload](/en/uploads), which returns the same `video_id`.

## Next steps

- [Publish the clip](https://cut.pro/docs/en/publishing): Use the render's `edit_id` to post to TikTok, Instagram and YouTube.
- [Clipping in detail](https://cut.pro/docs/en/clipping): Submission states, a source that is not live yet, retry and cancellation.
- [Errors](https://cut.pro/docs/en/errors): What each `code` means and what to do.