# Bring a still to life

`POST https://api.vidmoat.com/v1/ai/live-images`

- Scope: `ai.video`
- Cost: 8 credits per second

vidmoat-image-live-1 (pilot, enabled per account): animate a still with a depth-parallax camera move, ambient motion in one region, or a gentle object motion. Only what the still already shows moves. Returns a job to poll.

> **Note.** Priced per second: 8 credits a second, 2 to 10 seconds (40 for the 5-second default). The quote is the charge. Faces talking or blinking, people walking, vehicles driving and objects turning are refused before charging with a 400 that points to Generate a video. Every clip is measured before delivery; one that does not move, moves outside its region or drifts from the still ends FAILED and is refunded. Video only, no audio track. Uses the ai.video scope so the same key can poll the job.

### Body

- `image` (object, required): `{ "url": "https://..." }` or `{ "uploadId": "..." }` (an upload in your account). `imageUrl` is accepted instead.
- `prompt` (string, required): The motion, up to 500 characters: "slow push-in", "steam rises from the cup", "the sneaker floats".
- `durationSec` (integer, optional, default `5`): Whole seconds, 2 to 10. Billed on exactly this number.
- `aspectRatio` (enum, optional, default `source`): Output is 720p on the short side. One of `source`, `16:9`, `9:16`, `1:1`, `4:5`, `5:4`, `4:3`, `3:4`.
- `mode` (enum, optional, default `auto`): Force the method instead of reading it from the prompt. One of `auto`, `camera`, `ambient`, `object`.
- `move` (enum, optional): Camera move. One of `push`, `pull`, `drift`, `orbit`, `pan`.
- `region` (string, optional): What moves in ambient mode: water, waterfall, waves, clouds, smoke, steam, fire, leaves, wheat, grass, hair, flag, curtain and more.
- `motion` (enum, optional): Object motion on the cut-out subject. One of `float`, `bob`, `sway`, `tilt`, `drive`.
- `direction` (enum, optional): Direction of the move or flow. One of `up`, `down`, `left`, `right`.
- `strength` (number, optional, default `1`): 0.25 to 2.
- `box` (object, optional): `{ x, y, width, height }` as fractions of the frame: where the region or subject is.
- `loop` (boolean, optional, default `false`): Make the end meet the start. One-way moves (push, pull, drift, pan, drive) cannot loop and are refused.
- `seed` (integer, optional): For a repeatable result.
- `projectId` (string, optional): Project to attach the job to.
- `maxCredits` (number, optional): Never spend more than this.
- `quoteOnly` (boolean, optional): `true` returns the tier, method and price without starting a job.

## Response

Returns `202`.

### Response fields

- `id` (string): The job id. Poll it with Get a generation job.
- `status` (string): `PROCESSING`.
- `quote` (object): `{ credits, tier, motionClass, method }`.
- `credits` (object): `{ charged, remaining, basis }`.
- `poll` (string): The path to poll.

> **Tip: With a test key.** Test keys return a finished sample job at once and spend nothing.

## Errors

Besides the errors any request can get ([authentication](https://developer.vidmoat.com/developer/docs/authentication#when-a-request-is-refused), [rate limits](https://developer.vidmoat.com/developer/docs/rate-limits)):

| Status | Code | When |
| --- | --- | --- |
| 400 | [`invalid_request`](https://developer.vidmoat.com/developer/docs/errors#invalid_request) | No image or prompt, an unsupported option, a motion only Generate a video can make, or a quote above maxCredits. |
| 402 | [`plan_required`](https://developer.vidmoat.com/developer/docs/errors#plan_required) | Living images are not enabled on the account. |
| 402 | [`insufficient_credits`](https://developer.vidmoat.com/developer/docs/errors#insufficient_credits) | The balance cannot cover the call. Nothing ran. `remaining` is the balance. |
| 402 | [`quota_exceeded`](https://developer.vidmoat.com/developer/docs/errors#quota_exceeded) | A living image is already being made on the account. |
| 501 | [`not_configured`](https://developer.vidmoat.com/developer/docs/errors#not_configured) | The living-image worker is not available on this deployment. |
| 422 | [`prompt_rejected`](https://developer.vidmoat.com/developer/docs/errors#prompt_rejected) | The prompt failed the safety check. Nothing was charged. `field` names the field. |

## Request examples

```bash curl
curl -X POST https://api.vidmoat.com/v1/ai/live-images \
  -H "Authorization: Bearer $VIDMOAT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"image":{"url":"https://example.com/waterfall.jpg"},"prompt":"the waterfall flows","durationSec":5}'
```

```js Node
const res = await fetch('https://api.vidmoat.com/v1/ai/live-images', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.VIDMOAT_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    image: {
      url: 'https://example.com/waterfall.jpg',
    },
    prompt: 'the waterfall flows',
    durationSec: 5,
  }),
});
const data = await res.json();
if (!res.ok) throw new Error(data.error?.message ?? `HTTP ${res.status}`);
console.log(data);
```

```python Python
import os
import requests

res = requests.post(
    "https://api.vidmoat.com/v1/ai/live-images",
    headers={"Authorization": f"Bearer {os.environ['VIDMOAT_KEY']}"},
    json={
      "image": {
        "url": "https://example.com/waterfall.jpg",
      },
      "prompt": "the waterfall flows",
      "durationSec": 5,
    },
    timeout=60,
)
res.raise_for_status()
print(res.json())
```

## Example response

```json
{
  "id": "cm_job_2",
  "status": "PROCESSING",
  "model": "vidmoat-image-live-1",
  "durationSec": 5,
  "quote": { "credits": 40, "tier": "B", "motionClass": "ambient", "method": "masked cinemagraph" },
  "credits": { "charged": 40, "remaining": 5960, "basis": "8 credits/second, tier B" },
  "poll": "/api/v1/ai/jobs/cm_job_2"
}
```

---

Source: https://developer.vidmoat.com/developer/docs/api/generation/create-live-image
Previous: [Generate a video](https://developer.vidmoat.com/developer/docs/api/generation/create-video.md)
Next: [Get a generation job](https://developer.vidmoat.com/developer/docs/api/generation/get-generation-job.md)
All documentation: https://developer.vidmoat.com/llms-full.txt