> ## 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: your first clip

> From video link to rendered MP4, with real requests

This guide walks through the full API flow with `curl`. Before you start, [generate an API key](/docs/en/api-reference/autenticacao) and store it in `YOUR_KEY`.

<Note>
  All examples use the base URL `https://api.cut.pro/api/v1` and send the key in the `X-Api-Key` header. If your key is multi-workspace, also add `X-Workspace-Id`.
</Note>

<Steps>
  <Step title="Analyze the video (no cost)">
    See metadata and the credit cost before spending anything.

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

    The response includes `video_id`, `credits_cost`, and `current_balance`. Save the `video_id`.

    <Tip>
      Want to clip a file from your computer instead of a URL? See [Sending a video](/docs/en/api-reference/enviando-video) for the upload flow.
    </Tip>
  </Step>

  <Step title="Send for clipping">
    Submit the video. **Credits are debited immediately.** The `timeframe` is optional, omit it to process the whole video, or restrict it to a segment (in seconds) to save credits.

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

    The response includes `submission_id`, `status`, and `credits_charged`. Save the `submission_id`.

    <Tip>
      `strategy_id`, `template_id`, and `source_language` (`auto`, `en`, `pt`) are optional. List your strategies and templates with `GET /templates` to get the IDs.
    </Tip>
  </Step>

  <Step title="Track until done">
    Poll the submission. The `status` goes through `queued → downloading → transcribing → video_analysis → analyzing → finalizing → completed` (or `failed`).

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

    When `status` is `completed`, `clips_count` tells you how many clips were generated.
  </Step>

  <Step title="Fetch the generated clips">
    ```bash theme={null}
    curl https://api.cut.pro/api/v1/clips/VIDEO_ID/submissions/SUBMISSION_ID/clips \
      -H "X-Api-Key: YOUR_KEY"
    ```

    Each clip includes `id`, `title`, `rating` (the AI rating), `start_time`, `end_time`, `play_url`, and `download_url`. Sort by `rating` to get the best ones first.
  </Step>

  <Step title="Render a clip">
    Generate the final MP4 of a clip. To apply a visual first, call `POST .../apply_template` on the submission.

    ```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: YOUR_KEY"
    ```

    The response includes `render_id` and `status`. If `from_cache` is `true`, the `download_url` is already ready.
  </Step>

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

    The `status` goes through `queued → active → completed` and `progress` goes from 0 to 100.
  </Step>

  <Step title="Download the MP4">
    With the render `completed`, get the download URL.

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

    The response includes `url` (signed link to the file) and `filename`.
  </Step>
</Steps>

## What now?

<CardGroup cols={2}>
  <Card icon="send" title="Publish to social networks" href="/docs/en/api-reference/postagem">
    Take your rendered clips to TikTok, Instagram, YouTube, and more with `POST /posts`.
  </Card>

  <Card icon="coins" title="Workspace and credits" href="/docs/en/api-reference/saldo">
    Understand credit consumption and how to check your workspace balance.
  </Card>
</CardGroup>