# Quickstart

> Faça sua primeira requisição e saia com um clipe vertical em MP4.

Neste guia você confere a chave com uma chamada que não cobra nada, analisa um vídeo, gera os clipes e baixa o melhor deles renderizado.

**Você vai precisar de:** uma conta na Cut.Pro, uma chave de API e `curl`. Os exemplos completos no fim usam Node.js 18+ ou Python 3.9+.

## 1. Crie a chave

Abra [Chaves de API](https://cut.pro/studio/me/api-keys), clique em **Nova chave** e copie o valor. Ele aparece uma vez só.

```bash
export CUTPRO_API_KEY="cole_sua_chave_aqui"
```

## 2. Confira a chave

`GET /workspace` não cobra créditos e mostra em qual workspace a chave opera.

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

```json title="200 OK"
{
  "id": "7401220118845503",
  "name": "Estúdio Ana",
  "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"
}
```

Recebeu `401 UNAUTHORIZED`? A chave está errada ou foi revogada. Recebeu `400 MISSING_WORKSPACE_ID`? A chave alcança mais de um workspace: veja [Autenticação](/authentication#chave-com-mais-de-um-workspace).

## 3. Analise o vídeo

Analisar é de graça. A resposta traz o custo da clipagem e o seu saldo.

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

Guarde o `id`: ele é o `video_id` dos próximos passos.

## 4. Gere os clipes

> Este é o passo que cobra. O valor de `credits_cost` sai do saldo na hora, e volta se você cancelar antes de terminar.

```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. Espere terminar

Consulte a submissão a cada 5 a 10 segundos até `status` virar `completed` ou `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. Pegue o melhor clipe

Cada clipe tem uma nota de 0 a 10. Ordene por ela e peça um só.

```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": "O refrão que todo mundo sabe",
      "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. Renderize e baixe

Peça o render do clipe. Sem template, ele sai com as configurações padrão.

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

Consulte `GET /renders/7412908490112774` até `status` virar `completed` e peça o 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": "o-refrao-que-todo-mundo-sabe.mp4"
}
```

O link vale 1 hora. Pronto: esse é o seu clipe.

## O fluxo inteiro em um arquivo

Os passos 3 a 7 encadeados, com a espera resolvida. Troque a URL e rode.

**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} créditos`);

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']} créditos")

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)
```

## Ajuste o código

- **Corte só um trecho:** mande `timeframe: { "start": 600, "end": 1800 }` em `POST /clips` para clipar do minuto 10 ao 30.
- **Aplique seu estilo:** passe um `template_id` de `GET /templates` em `POST /clips` e todo clipe sai com a sua legenda e o seu enquadramento.
- **Traduza a legenda:** `translate_to: "es"` em `POST /clips` gera as legendas em espanhol. Custa mais que a clipagem simples, e `credits_charged` mostra quanto saiu.
- **Use um arquivo seu:** troque o passo 3 pelo [upload](/uploads), que devolve o mesmo `video_id`.

## Próximos passos

- [Publique o clipe](https://cut.pro/docs/publishing): Use o `edit_id` do render para postar no TikTok, Instagram e YouTube.
- [Clipagem em detalhe](https://cut.pro/docs/clipping): Estados da submissão, fonte que ainda não foi ao ar, retry e cancelamento.
- [Erros](https://cut.pro/docs/errors): O que cada `code` significa e o que fazer.