> ## Documentation Index
> Fetch the complete documentation index at: https://magica-adi.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Magica tools

> Direct Crop Image, GPT Image 2, and Merge Videos execution.

These routes call Magica end to end. They block until the provider finishes, up to 5 minutes, and return the result in the same HTTP response. A provider poll that exceeds that window is `504 TIMEOUT`.

A success also emits `tool.completed`. Result URLs are copied to object storage when it is configured.

## Crop Image

`POST /api/v1/tools/crop_image`

Provide exactly one complete rectangle: percent fields, pixel `x` / `y` / `width` / `height`, or `crop.{x,y,width,height}`.

```json theme={null}
{
  "image_url": "https://cdn.example/in.png",
  "x_percent": 0,
  "y_percent": 0,
  "width_percent": 50,
  "height_percent": 50
}
```

## GPT Image 2

`POST /api/v1/tools/gpt_image_2`

```json theme={null}
{ "prompt": "a red square on white" }
```

Add `image_url` to run edit mode.

## Merge Videos

`POST /api/v1/tools/merge_videos`

```json theme={null}
{
  "video_urls": ["https://cdn.example/a.mp4", "https://cdn.example/b.mp4"],
  "transition": "fade"
}
```

`transition` is `none`, `fade`, or `dissolve`.

## Response

<ResponseField name="toolName" type="string">
  `crop_image`, `gpt_image_2`, or `merge_videos`.
</ResponseField>

<ResponseField name="output" type="object">
  Provider output, including the result URL.
</ResponseField>

<ResponseField name="assets" type="object[]">
  `{ url, mimeType, filename? }` after durable copy when storage is configured.
</ResponseField>

<ResponseField name="creditCost" type="string">
  Credits charged for this call.
</ResponseField>

<ResponseField name="providerRunId" type="string">
  Magica run id.
</ResponseField>

<ResponseField name="durationMs" type="integer" />

```json theme={null}
{
  "toolName": "crop_image",
  "output": { "image_url": "https://…" },
  "assets": [{ "url": "https://…", "mimeType": "image/png" }],
  "creditCost": "0",
  "providerRunId": "…",
  "durationMs": 1200
}
```

Any other `{toolName}` returns `404 UNKNOWN_TOOL`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.