Import your existing images

Two tools, two destinations

The difference is what you intend to do with the image, and it is worth getting right the first time.

• import_image puts the picture in a project's timeline as a first-class image, alongside everything generated there. Use it for finished work you want to keep, browse, and search.
• upload_asset stores it as a reusable reference. It returns an asset id you can pass into generate_image.reference_asset_ids. Use it for the things you will point at repeatedly — a model, a backdrop, a product.

Importing into a project

Give it exactly one source: path for a local file or url for a remote one. Both together is an error, on purpose.

{
  "name": "import_image",
  "arguments": {
    "path": "./shoots/aw26/sneaker-01.jpg",
    "name": "Sneaker, overhead"
  }
}json

{
  "name": "import_image",
  "arguments": { "url": "https://cdn.example.com/hero.png" }
}json

You get back the new image's id and a URL. The hosted server at /api/mcp has no access to your filesystem, so it takes url only — path needs the local server.

Product shots

An asset uploaded with category: "product" and a project_id appears in that project's products column. Both are required — a product asset uploaded without a project is stored, but shows up in no project, which looks like the upload failed.

{
  "name": "upload_asset",
  "arguments": {
    "path": "./products/navy-sneaker.png",
    "category": "product",
    "project_id": "prj_abc123"
  }
}json

Where imports land

Omit project_id and the server resolves it: first the nearest .nsp.json walking up from the working directory, then the global default in your credentials file. Pin a repo to its own project by dropping this at its root:

{"default_project_id":"prj_abc123"}json

Or skip the file and let the agent call resolve_project with the folder name — it finds or creates, so it is safe to call every session. One project per folder keeps each repo's imagery searchable on its own.

What the scan costs, and why

Importing charges 3 credits plus storage. The 3 credits are the detection scan — the step that reads the objects, colors, textures, and scene out of the picture and writes the index that search runs against. Skip it and you have a file in a folder again.

For an image already in the library that was never scanned, run it directly:

{
  "name": "scan_image",
  "arguments": { "id": "gen_8f2c..." }
}json

Imports count against your storage quota. Have the agent call get_storage before a bulk import, and get_credits if you are near a daily cap.

Bringing in a backlog

There is no bulk endpoint — an agent loops. In practice that is what you want, because it can name each image as it goes and file it into the right project instead of dumping a folder into one bucket. Ask for a directory to be imported and read back what was found; the naming is worth more than the speed, since a described image is one you can retrieve.