Object Reveal

Any product, portrait or object materializes into its own scene, or breaks apart out of it, as a cinematic video.

The source photo→Liquid chrome, 4s

The same machinery as Logo Reveal pointed at a photograph instead of a mark. The clip keeps the source photo's own proportions, so a square product shot comes back square rather than reframed, and the subject is reproduced exactly while the prompt drives everything around it.

Billed per second of video. $0.25 per second standard, $1 with fine details: a 4 second clip is $1 or $4. Live rate from GET /v3/pricing.

A complete call

Materialize a product into its scene over 4 seconds.

curl -X POST "https://api.neurall.io/v3/files/upload" \
  -H "Authorization: nl-YOUR_API_KEY" \
  -F "files=@object.jpg"

{
  "files": [
    {
      "id": "f_9c21e0b4",
      "originalName": "object.jpg",
      "size": 512804
    }
  ]
}

curl -X POST "https://api.neurall.io/v3/generations" \
  -H "Authorization: nl-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "feature": "video/object-reveal",
    "args": {
      "image": "f_9c21e0b4",
      "prompt": "Thick golden resin pours into the empty scene, glowing where the light passes through, pooling and rising until it holds a clear suspended shape, then the resin drains away and vanishes leaving the subject exactly where it set. Warm, slow. Sound design: a thick viscous pour with a low golden hum.",
      "mode": "intro",
      "generateAudio": true,
      "fineDetails": false,
      "duration": 4
    }
  }'

{
  "generation": {
    "id": "5e08…",
    "feature": "video/object-reveal",
    "kind": "video",
    "status": "pending"
  }
}

# repeat every 5s or so until status is done, error or timeout
curl "https://api.neurall.io/v3/generations/9f2c1d84-6a3b-4f21-9c77-2f0a1b8e5d43" \
  -H "Authorization: nl-YOUR_API_KEY"

{
  "generation": {
    "status": "done",
    "output": {
      "video": "https://cdn.neurall.io/…/video.mp4",
      "mime": "video/mp4"
    }
  }
}

Arguments

imagestringrequired

The subject: a file id from POST /v3/files/upload. A photograph, a product shot, a portrait, anything with a clear subject.

• PNG, JPEG, WebP, GIF, HEIC or AVIF, up to 30 MB and 30 megapixels per file, 10 files per upload request.
• An uploaded file is deleted 24 hours after it lands, so upload again for a later render rather than caching an id.

How the prompt refers to this

args.imageThe subject

Call it "the subject" if the prompt needs to place it. Everything else you write is read as the scene and the effect around it.

promptstringrequired

The motion direction: the effect, the scene, the mood. Describe what happens around the subject, never the subject itself, and never how long a beat lasts.

• At most 2000 characters.

mode'intro' | 'outro'defaults to 'intro'

intro materializes the subject into its scene; outro starts on it and takes it apart.

fineDetailsbooleandefaults to false

The quality tier. Off is the everyday choice; on costs several times more and earns it when the subject carries small text, labels or fine texture, where the cheaper renderer visibly softens.

• This is the only quality control. There is no model argument: the engine is chosen server-side and the billing rate follows this flag, so the price can never disagree with what rendered.

generateAudiobooleandefaults to true

Generated sound design, faded out at the end. Named generateAudio, not audio: audio is a file id everywhere else in the API, so the boolean was renamed for what the server does with it.

duration4 | 6 | 8defaults to 8

Clip length in seconds, billed per second.

• Exactly 4, 6 or 8.

Never describe the subject's appearance. The render has the photograph; describing it invites a redraw.

Output

Once status is done, the generation carries an output object with these fields. On any other status, output is absent.

videostring

The finished reveal, as a URL. An MP4, with sound unless generateAudio was false.

• A signed URL that expires 24 hours after the request (expiresAt on the generation). Download the file rather than hotlinking it.

mimestring

The clip's MIME type, e.g. video/mp4.

Limits and failure

Duration

Exactly 4, 6 or 8 seconds.

Prompt

At most 2000 characters.

Render time

Typically 2 to 4 minutes. A generation that has not finished in 15 minutes is marked timeout and refunded.

Concurrency

Your plan caps how many generations run at once. Over it the API answers 429 with a Retry-After header.

Output lifetime

API-created outputs expire 24 hours after the request. Download the file rather than hotlinking it.

Deletion

DELETE /v3/generations/{id} removes the generation and its rendered assets immediately, rather than waiting for the 24 hour expiry. It does not refund anything and cannot cancel a render already in flight.

Failure

A failed or timed-out generation is refunded automatically.

Worth knowing

• Template prompts pace in beats rather than seconds, so the same prompt holds at 4, 6 and 8 seconds.
• The renderer is never named, in the response or in an error. Pick a tier and a duration; we keep the engine current underneath you.