Passing your own media

Every field that takes media (image_asset_id, reference_video_asset_ids, asset_id, and every other *_asset_id or *_asset_ids) takes either an asset id from your library or a public HTTPS URL of the file. Mix them freely in one call. There is no separate upload step.

curl -s https://mcp.morphic.com/v1/direct/tools/edit_image \
  -H "Authorization: Bearer $MORPHIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": {"prompt": "Put the bike on a beach at sunset", "image_asset_ids": ["https://cdn.example.com/products/bike.jpg"], "project_id": "01928f4e-…"}}'

Before the tool runs, each URL is fetched and added to project_id as an uploaded asset, free of charge. The tool then runs on it like any other asset. A URL needs the assets:write scope, and each distinct URL counts as one call against the free-call bucket.

• The URL must be HTTPS on a public host and serve the file itself, not a web page.
• For a file in your own storage, pass a signed URL (an S3 presigned GET, a GCS signed URL). Keep it valid until the call answers.
• Images, video, audio and documents (.pdf, .txt, .md, .srt) are accepted. The bytes are probed, so the extension is never trusted.
• A media file may be up to 100 MB, or your plan's upload limit when that is lower, and must arrive within 25 seconds.
• A URL named twice in one call is fetched once. A later call fetches it again; to reuse a file without fetching it again, pass the asset id list_assets shows for it.
• The call's input is checked against the tool's schema before any URL is fetched. A malformed call answers 400 invalid_request and fetches nothing.
• A URL that cannot be fetched or is not accepted answers 422 tool_refused naming the field, for example input.image_asset_ids[0]: The URL must use https. Nothing is started or charged. A file already added stays in the project, as it does when the tool itself refuses the call afterwards.
• analyze_video and analyze_audio take project_id only for this: send it when a media field holds a URL.
• plan_media steps take URLs too, each added to its step's project_id, so a quote adds those files to your library. Pass the asset ids list_assets then shows to the steps you run, rather than the URLs, to fetch each file once.

If you have any trouble or have any questions, feel free to reach out. We're happy to help. Write to us at support@morphic.com.