Objects

The Objects API scripts everything Object Studio does for props and products. You create an object, generate candidate main images, approve one, and add angle, material and variation variants and motion clips. Image and video nodes then reuse the object, so the same lantern, car or chair looks the same in every shot.

The routes work on every edition and take a bearer token: a personal API token (ndr_…), an OAuth app token (ndr_app_…), or your session token on Community edition. Every route is scoped to the caller. See Authentication.

Endpoints

What an object holds

The asset buckets

Reference photos

A mood board travels with the object. Every node that uses the object receives these photos as extra references, even without a wired image, and each photo's kind tells the model what it is for.

You can add up to 20 photos, and any number of each kind. For a hero prop or a signature product, add three to six photos before the first generation: the first results are then much more faithful.

List objects

GET /v1/objects returns your active objects, newest first. Add archived=true for the archive, or projectId for one project. Without limit, the route returns the full list. With limit (at most 500), it returns one page and a nextCursor; pass it back as cursor until it is null.

curl "https://app.nodaro.ai/v1/objects?limit=100" \
  -H "Authorization: Bearer $NODARO_API_KEY"

import { createClient, StaticTokenAuth } from '@nodaro/sdk'

const client = createClient({
  baseUrl: 'https://app.nodaro.ai',
  auth: new StaticTokenAuth(process.env.NODARO_API_KEY!),
})

const page = await client.objects.list({ limit: 100 })
const next = await client.objects.list({ limit: 100, cursor: page.nextCursor! })
const { objects: archived } = await client.objects.listArchived()

nodaro objects list --json
nodaro objects list --archived

GET /v1/objects/:id returns one object with pendingJobs. An archived object returns 404 not_found, the same answer as an object that does not exist.

Create or update an object

POST /v1/objects creates an object when the body has no id, and updates it when it has one. A create needs nodeId and name; use any label for nodeId, such as "scripted", when there is no canvas node.

On an update, only the fields you send are written. The asset buckets are never written by an update, so a save cannot overwrite a variant that a job is adding. Send expectedUpdatedAt, the object's current updatedAt, to refuse the update when someone changed the object since you read it: the route then answers 409 concurrent_modification.

curl -X POST https://app.nodaro.ai/v1/objects \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "nodeId": "scripted",
    "name": "Antique Lantern",
    "description": "Weathered brass lantern with hand-engraved filigree",
    "category": "tool",
    "style": "realistic"
  }'

const { id } = await client.objects.create({
  nodeId: 'scripted',
  name: 'Antique Lantern',
  description: 'Weathered brass lantern with hand-engraved filigree',
  category: 'tool',
  style: 'realistic',
})

const object = await client.objects.get(id)
await client.objects.update(id, { styleLock: false, expectedUpdatedAt: object.updatedAt })

nodaro objects create "Antique Lantern" --node-id scripted \
  --description "Weathered brass lantern with hand-engraved filigree" \
  --category tool --style realistic

nodaro objects update <id> --style-lock false

A create returns { id }. An update returns { id, updatedAt }.

What Style Lock changes

• On (default). Every angle, material and variation is generated from the approved main image. The variant keeps the proportions, the silhouette and the defining details. Nodes that use the object also receive its canonical description. Use it for anything that must look like the same item in every shot.
• Off. Variants are generated from text only. Nodes still receive the canonical description, but only as guidance, so the model may reinterpret the design. Use it to explore alternatives or compare looks.

Generate candidate main images

POST /v1/generate-object starts one job per candidate and returns jobIds at once, one id per candidate. A single-candidate request also returns jobId. Poll the jobs with the Jobs API.

With attachToObjectId and a count of 1, the result becomes the object's main image when the job completes. With several candidates nothing is attached; approve the one you prefer.

curl -X POST https://app.nodaro.ai/v1/generate-object \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Antique Lantern", "count": 4 }'

const { jobIds } = await client.objects.generate({
  name: 'Antique Lantern',
  description: 'Weathered brass lantern with hand-engraved filigree',
  count: 4,
})

nodaro objects generate --name "Antique Lantern" --count 1 \
  --attach-to-object-id <id> --watch

{
  "jobIds": [
    "5e2a8c1f-3b7d-4f9a-a6c2-8d1e4b7f0a3c",
    "6f3b9d2a-4c8e-4a1b-b7d3-9e2f5c8a1b4d",
    "7a4c1e3b-5d9f-4b2c-c8e4-1f3a6d9b2c5e",
    "8b5d2f4c-6e1a-4c3d-d9f5-2a4b7e1c3d6f"
  ]
}

seedPromptHint is also accepted by generate-object-asset and generate-object-motion. It lets you compose a catalog choice, such as a vehicle or a material, into the prompt without wiring a picker node.

Generate a variant

POST /v1/generate-object-asset generates one variant and returns { jobId }. Send attachToObjectId, attachToColumn and attachName to append { name: attachName, url } to the bucket when the job completes.

curl -X POST https://app.nodaro.ai/v1/generate-object-asset \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Antique Lantern",
    "assetType": "materials",
    "variant": "gold",
    "attachToObjectId": "2c7e9a4b-1d3f-4e8a-9b6c-5f0d2a7e3b1c",
    "attachToColumn": "materials",
    "attachName": "gold"
  }'

await client.objects.generateAsset({
  name: 'Antique Lantern',
  assetType: 'variations',
  variant: 'weathered',
  attachToObjectId: id,
  attachToColumn: 'variations',
  attachName: 'weathered',
})

nodaro objects generate-asset --asset-type materials --variant gold \
  --attach-to-object-id <id> --attach-to-column materials --watch

Animate the main image

POST /v1/generate-object-motion turns an image of the object into a short camera-move clip, such as a slow rotation, a hover or a drone orbit. Use the clips as B-roll or as the start of a longer video. The route returns { jobId }.

sourceImageUrl is required; there is no fallback, so pass the approved main image. With attachToObjectId and attachName, the clip is appended to motionClips when it completes; you do not send a column.

curl -X POST https://app.nodaro.ai/v1/generate-object-motion \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Antique Lantern",
    "motionPrompt": "slow 360 rotation, soft golden rim light",
    "sourceImageUrl": "https://cdn.nodaro.ai/objects/lantern-main.png",
    "provider": "kling-turbo",
    "attachToObjectId": "2c7e9a4b-1d3f-4e8a-9b6c-5f0d2a7e3b1c",
    "attachName": "rotate-360"
  }'

const lantern = await client.objects.get(id)

await client.objects.generateMotion({
  name: 'Antique Lantern',
  motionPrompt: 'slow 360 rotation, soft golden rim light',
  sourceImageUrl: lantern.sourceImageUrl!,
  provider: 'kling-turbo',
  attachToObjectId: id,
  attachName: 'rotate-360',
})

nodaro objects generate-motion --name "Antique Lantern" \
  --motion-prompt "slow 360 rotation, soft golden rim light" \
  --source-image-url "https://cdn.nodaro.ai/objects/lantern-main.png" \
  --provider kling-turbo --attach-to-object-id <id> --attach-name "rotate-360" --watch

The price of a clip is the model's image-to-video price:

Approve a main image

POST /v1/objects/:id/approve-main-image sets a completed candidate as the main image and, in the same call, writes canonicalDescription: the text that later prompts use to describe the object. The body is { candidateJobId, expectedUpdatedAt? }, and the candidate must be a completed job that belongs to you.

The route returns { sourceImageUrl, canonicalDescription }. When writing the description fails, the main image is still set and canonicalDescription is an empty string; the SDK returns null instead. Call POST /v1/objects/:id/llm-caption to try again. That route returns { canonicalDescription }, answers 502 when the description cannot be written, and 400 main_image_required when there is no main image yet. It does not take expectedUpdatedAt: it is always safe to repeat.

curl -X POST https://app.nodaro.ai/v1/objects/2c7e9a4b-1d3f-4e8a-9b6c-5f0d2a7e3b1c/approve-main-image \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "candidateJobId": "6f3b9d2a-4c8e-4a1b-b7d3-9e2f5c8a1b4d" }'

const approved = await client.objects.approveMainImage(id, jobIds[1])
if (approved.canonicalDescription === null) {
  await client.objects.recaption(id)
}

nodaro objects approve-main-image <id> --candidate-job-id <jobId>
nodaro objects recaption <id>

Archive, restore and delete an object

• Archive returns { success: true, archived: true }. Archiving an archived object changes nothing.
• Restore returns { id, name }. When an active object has the same name, ignoring case, Nodaro adds a (restored) suffix and returns the new name.
• Delete for good returns { success: true, permanent: true } and removes the object and every file it references: the main image, the variants, the clips and the reference photos. It works only on an archived object; an active one returns 400 not_archived. Archive first, then delete.

Pick a variant when you run an app

When a workflow with an Object/Props Asset node is published as an app, the object becomes one of the app's inputs. Pass "<bucket>/<variant>" to use a variant as the object's main image for that run, for example "materials/gold". Write the variant name in lowercase with hyphens for spaces: polished-brass matches a variant named Polished Brass. An unknown bucket or variant falls back to the main image. See Workflows for running apps.

Use the object in other generations

Pass the object's asset URLs as reference images to Generate Image or Generate Video; explicit URLs are the simplest choice for code. In a workflow, wire the object node into the image node, or mention a variant in the prompt, for example @lantern:1:materials/gold for an object named Lantern. When you wire an object without a mention, Nodaro also looks for variant names in your prompt: "gold finish" selects materials/gold. See Objects.

Use it from MCP

There are no MCP tools to create, update, archive, restore or delete objects: generate_object creates them, and the other changes go through REST, the SDK or the CLI. See the MCP tools reference.

Credits

Errors