Generations

A generation makes one image, video or song on request, outside any conversation. Each works the same way:

1. Start it. The answer is 202 Accepted with the generation, queued.
2. Poll it with GET until its status is completed, failed or canceled.
3. Collect its files. Once completed, they hold the result, each with a fresh download link — and they are the end user's own files from then on.

curl -s "$NEWEYES_API_BASE/v1/images/generations" -X POST \
  -H "Authorization: Bearer $NEWEYES_USER_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"prompt": "A sunlit reading nook with a green armchair, watercolor style"}'

{
  "object": "image",
  "id": "a81b…",
  "type": "generate",
  "status": "queued",
  "files": [],
  "created_at": "2026-10-19T08:10:00Z",
  "completed_at": null
}

curl -s "$NEWEYES_API_BASE/v1/images/$IMAGE_ID" \
  -H "Authorization: Bearer $NEWEYES_USER_TOKEN"

Status and errors

A generation is queued, then running, and ends completed, failed or canceled; once ended it does not change. A failed one names why in error.code:

error.code	Meaning
content_blocked	A content safety check refused the request or one of its inputs.
insufficient_credits	The project's balance ran out.
insufficient_available_credits	The project's credits are all held by work already under way.
invalid_input	An input could not be used — for example a video longer than the operation takes.
generation_failed	It did not produce a result.
timeout	It took too long.

Poll every few seconds for an image or a song, and every 10 seconds or so for a video, which can take minutes.

Images

Operation	Does
POST /v1/images/generations	Draws an image from prompt (up to 4,000 characters; put text that should appear in the image in quotes), optionally after up to 8 reference_images.
POST /v1/images/edits	Edits or combines 1 to 8 images as prompt describes, keeping what it does not mention. Refer to them by position: "the first image".
GET /v1/images, GET /v1/images/{image_id}	The user's image generations, newest first; one generation.

Videos

Operation	Does
POST /v1/videos	Makes a video from prompt, optionally starting from a first_frame image (and ending on a last_frame).
POST /v1/videos/edits	Changes part of a 3 to 15 second video as prompt describes — swaps an object, restyles it, adds something — keeping its length and its shots.
POST /v1/videos/remakes	Shoots a new take of the scene in video, as prompt describes.
POST /v1/videos/motion-transfers	Animates the person in image so they move as the person in video does.
POST /v1/videos/reframes	Changes only a video's frame shape (aspect_ratio) and resolution, extending the picture to fill the new frame.
POST /v1/videos/soundtracks	Lays an audio clip over a video in place of its own sound.
GET /v1/videos, GET /v1/videos/{video_id}	The user's video generations, newest first; one generation.
POST /v1/videos/{video_id}/cancel	Cancels a generation (below).

For POST /v1/videos:

• duration is 4 to 12 seconds (5 by default); resolution is 480p, 720p (the default) or 1080p; aspect_ratio is 16:9, 4:3, 1:1, 3:4, 9:16, 21:9 or auto (the default: follow the inputs); audio gives the video sound (on by default).
• quality: "pro" adds up to 15 seconds and 4k, and takes reference media: up to 9 reference_images, up to 3 reference_videos (15 seconds together at most), and up to 3 reference_audios (which need a reference image or video). Reference images do not combine with first_frame / last_frame.

An operation that takes a source video uses only part of a longer one: set start_seconds to where that part begins. Without it, a source longer than the operation takes fails with invalid_input. Each operation's limits are in the API reference.

Cancel a video

POST /v1/videos/{video_id}/cancel cancels a generation. A queued one ends canceled at once. One already rendering is asked to stop and stays running until that is settled: it then ends canceled — or completed, delivered and charged as usual, when the video was finished first. A generation that has ended is returned unchanged.

Music

POST /v1/music makes one song (an MP3 file) as prompt describes: its subject, instruments, voice or lyrics. genre, mood and tempo refine it. duration_seconds is only a hint: the result is usually a full song of about two minutes.

Limits and billing

• An end user may have three generations unfinished at a time, images, videos and music together. A fourth is refused with 429 rate_limited and Retry-After.
• Starting a generation needs a spendable balance on the project's billing account. A generation is charged when it produces its result; one that ends without delivering one is not charged.
• Send an Idempotency-Key, so a retry never starts a second generation.
• Inputs are file ids from POST /v1/files — or the files of an earlier generation.