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

# Quickstart: seu primeiro clipe

> Do link do vídeo ao MP4 renderizado, com requisições reais

Este guia percorre o fluxo completo da API com `curl`. Antes de começar, [gere uma chave de API](/api-reference/autenticacao) e guarde-a em `SUA_CHAVE`.

<Note>
  Todos os exemplos usam a URL base `https://api.cut.pro/api/v1` e enviam a chave no header `X-Api-Key`. Se a sua chave for multi-workspace, adicione também `X-Workspace-Id`.
</Note>

<Steps>
  <Step title="Analise o vídeo (sem custo)">
    Veja metadados e o custo em créditos antes de gastar nada.

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

    A resposta traz `video_id`, `credits_cost` e `current_balance`. Guarde o `video_id`.

    <Tip>
      Quer clipar um arquivo do seu computador em vez de uma URL? Veja [Enviando um vídeo](/api-reference/enviando-video) para o fluxo de upload.
    </Tip>
  </Step>

  <Step title="Envie para clipagem">
    Submeta o vídeo. **Os créditos são debitados imediatamente.** O `timeframe` é opcional — omita para processar o vídeo inteiro, ou restrinja a um trecho (em segundos) para economizar créditos.

    ```bash theme={null}
    curl -X POST https://api.cut.pro/api/v1/clips \
      -H "X-Api-Key: SUA_CHAVE" \
      -H "Content-Type: application/json" \
      -d '{
        "video_id": "VIDEO_ID",
        "strategy_id": "STRATEGY_ID",
        "timeframe": { "start": 0, "end": 1800 }
      }'
    ```

    A resposta traz `submission_id`, `status` e `credits_charged`. Guarde o `submission_id`.

    <Tip>
      `strategy_id`, `template_id` e `source_language` (`auto`, `en`, `pt`) são opcionais. Liste suas estratégias e templates com `GET /templates` para obter os IDs.
    </Tip>
  </Step>

  <Step title="Acompanhe até concluir">
    Faça polling na submissão. O `status` passa por `queued → downloading → transcribing → video_analysis → analyzing → finalizing → completed` (ou `failed`).

    ```bash theme={null}
    curl https://api.cut.pro/api/v1/clips/VIDEO_ID/submissions/SUBMISSION_ID \
      -H "X-Api-Key: SUA_CHAVE"
    ```

    Quando `status` for `completed`, `clips_count` indica quantos clipes foram gerados.
  </Step>

  <Step title="Busque os clipes gerados">
    ```bash theme={null}
    curl https://api.cut.pro/api/v1/clips/VIDEO_ID/submissions/SUBMISSION_ID/clips \
      -H "X-Api-Key: SUA_CHAVE"
    ```

    Cada clipe traz `id`, `title`, `rating` (a nota da IA), `start_time`, `end_time`, `play_url` e `download_url`. Ordene por `rating` para pegar os melhores primeiro.
  </Step>

  <Step title="Renderize um clipe">
    Gere o MP4 final de um clipe. Para aplicar um visual antes, chame `POST .../apply_template` na submissão.

    ```bash theme={null}
    curl -X POST \
      https://api.cut.pro/api/v1/clips/VIDEO_ID/submissions/SUBMISSION_ID/clips/CLIP_ID/render \
      -H "X-Api-Key: SUA_CHAVE"
    ```

    A resposta traz `render_id` e `status`. Se `from_cache` for `true`, o `download_url` já vem pronto.
  </Step>

  <Step title="Acompanhe o render">
    ```bash theme={null}
    curl https://api.cut.pro/api/v1/renders/RENDER_ID \
      -H "X-Api-Key: SUA_CHAVE"
    ```

    O `status` passa por `queued → active → completed` e `progress` vai de 0 a 100.
  </Step>

  <Step title="Baixe o MP4">
    Com o render `completed`, pegue a URL de download.

    ```bash theme={null}
    curl https://api.cut.pro/api/v1/renders/RENDER_ID/download \
      -H "X-Api-Key: SUA_CHAVE"
    ```

    A resposta traz `url` (link assinado para o arquivo) e `filename`.
  </Step>
</Steps>

## E agora?

<CardGroup cols={2}>
  <Card icon="send" title="Publique nas redes" href="/api-reference/postagem">
    Leve os clipes renderizados para o TikTok, Instagram, YouTube e mais com `POST /posts`.
  </Card>

  <Card icon="coins" title="Workspace e créditos" href="/api-reference/saldo">
    Entenda o consumo de créditos e como consultar o saldo do workspace.
  </Card>
</CardGroup>