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

{
  "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

{ "prompt": "a red square on white" }

Add image_url to run edit mode.

Merge Videos

POST /api/v1/tools/merge_videos

{
  "video_urls": ["https://cdn.example/a.mp4", "https://cdn.example/b.mp4"],
  "transition": "fade"
}

transition is none, fade, or dissolve.

Response

toolName · string

crop_image, gpt_image_2, or merge_videos.

output · object

Provider output, including the result URL.

assets · object[]

{ url, mimeType, filename? } after durable copy when storage is configured.

creditCost · string

Credits charged for this call.

providerRunId · string

Magica run id.

durationMs · integer

{
  "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.