Tools / Scene Compositor

Place Object in Scene

Composite object into scene. STOP: if user has not given you 2 image URLs, ask them to upload at toolrouter.com/dashboard/files. Do NOT use generate-image or any other tool to create inputs. Flash $0.08, Pro $0.15. Optional upscale.

Returns: Composited image with permanent URL, downloadable asset, and optional upscaled version

Parameters

object_image_url *stringURL of the object photo provided by the user. Must be a real photo — never AI-generated.

scene_image_url *stringURL of the scene/environment photo provided by the user. Must be a real photo — never AI-generated.

prompt *stringHow to place the object in the scene. Describe placement, angle, lighting, camera style.

modelstringCompositing model. flash (default, Gemini 3.1 Flash, $0.08) or pro (Gemini 2.5 Pro, $0.15, higher fidelity).

strengthnumberEdit strength 0-1. Lower preserves more of the original scene, higher allows more creative freedom. Default: 0.5.

upscalebooleanUpscale the composited result for higher resolution. Uses the image-upscale tool (SeedVR2 by default). Default: false.

upscale_factornumberUpscale factor (2-10). Only applies when upscale is true. Default: 2.

Example

Place a product on a street scene

curl -H "Authorization: Bearer $TOOLROUTER_API_KEY" \
  -d '{
  "tool": "scene-compositor",
  "skill": "place_object",
  "input": {
    "object_image_url": "https://placehold.co/400x400.png",
    "scene_image_url": "https://placehold.co/800x600.png",
    "prompt": "Place the product on the ground in the foreground of the scene, slightly angled. Natural lighting."
  }
}' \
  https://api.toolrouter.com/v1/tools/call

Check Image Status

Check on a pending composited image and retrieve it if ready. Use after place_object returns a pending result with fal_request_id.

Returns: Image status and URL if completed, or a message to try again

Parameters

fal_request_id *stringThe fal.ai request ID returned by place_object when the image was still generating.

fal_model_idstringThe fal.ai model ID. Default: fal-ai/nano-banana-2/edit.

Example

Check a pending image

curl -H "Authorization: Bearer $TOOLROUTER_API_KEY" \
  -d '{
  "tool": "scene-compositor",
  "skill": "check_image",
  "input": {
    "fal_request_id": "abc123-def456"
  }
}' \
  https://api.toolrouter.com/v1/tools/call

Quick Start

MCP (Claude Code)

claude mcp add --transport stdio \
  --env TOOLROUTER_API_KEY=YOUR_API_KEY \
  toolrouter -- npx -y toolrouter-mcp

REST API

curl -H "Authorization: Bearer $TOOLROUTER_API_KEY" \
  -d '{"tool":"scene-compositor","skill":"place_object","input":{}}' \
  https://api.toolrouter.com/v1/tools/call