Reusable AI Characters and Backgrounds: The Library
Save an AI-drawn character or a background once and use it in every video by its ID: how the Nureta Library works over the API, its limits and its rules.
Published · 3 min read
Most video APIs forget your cast between calls. You describe her again, attach the same photo again, and hope the next render looks like the last one. The Library fixes that: you draw a character or a place once, save the version you like, and every later video uses it by an ID such as chr_... or bg_.... It is live in the API and on the Library page of the console.
What the Library is
The Library is a store of saved characters and backgrounds that belongs to your account. No other account can see or use your items. A character is a person the library drew from your description. A background is a place: one the library drew, or a photo of a place that you upload. Each saved item gets an ID you pass into a video task, so the same face, body and room come back in every render without re-uploading anything.
Step 1: describe it and draw two images
Send a description as fields: for a character, the sex, an age group (20s to 50+), a style (realistic, anime, 3D, illustration or your own words) and optional appearance, hair, body and outfit; for a background, the location, the time of day and the mood. The API checks the description first, then draws 2 candidate images, usually in under a minute. A generation costs $0.10. If the check refuses it, or no image could be drawn, the $0.10 is refunded automatically.
curl -s -X POST "$NURETA_URL/api/v3/library/generations" \
-H "Authorization: Bearer sk-..." \
-H "Content-Type: application/json" \
-d '{"kind": "character",
"spec": {"sex": "female", "age_group": "20s", "style": "realistic",
"hair": "long dark brown hair, loose waves"},
"prompt": "brown eyes, a warm smile"}'
# => 202 {"id": "gen_...", "status": "checking", ...} then poll GET /api/v3/library/generations/gen_...Step 2: save the one you want
Saving is free. Pass the ref of the candidate you picked (for example gen_...#0) and, if you like, a name; without one, the API names it for you. On the console's Library page, one click on Save keeps the picked image at once. The candidate you did not pick is never saved, and unsaved candidates are deleted after 14 days. A saved item is kept for 1 year after you save it, then it is deleted.
curl -s -X POST "$NURETA_URL/api/v3/library/items" \
-H "Authorization: Bearer sk-..." -H "Content-Type: application/json" \
-d '{"from": "gen_...#0", "name": "Mira"}'
# => 201 {"id": "chr_...", "ref": "library:chr_...", "kind": "character", "source": "generated", ...}Saving a background you upload
You can also save a photo of a place as a background: upload it (see Upload a reference image), then save it with kind: "background", the image URL and consent: true. Consent means you have the right to use the image, and anyone who appears in it is an adult who agreed to be shown. The API checks the image before it saves it and stores a clean JPEG with EXIF and GPS data removed. A character can never be uploaded: that request is refused with library_upload_character_refused.
Step 3: use it in any video
Add the item to the content of a video task as a library_item. A character works as a reference image of a person; a background works as a reference image of the place. In edit-mode storyboards, the image fields take library:chr_... and library:bg_.... See Library items in a video for the details.
curl -s -X POST "$NURETA_URL/api/v3/contents/generations/tasks" \
-H "Authorization: Bearer sk-..." -H "Content-Type: application/json" \
-d '{"model": "seahorse-480p", "content": [
{"type": "text", "text": "She sits on the sofa and waves at the camera."},
{"type": "library_item", "library_item": {"id": "chr_..."}},
{"type": "library_item", "library_item": {"id": "bg_..."}}
]}'The video is priced and checked like any video with an uploaded image: from $0.94 for 5 seconds on seahorse-480p. A library item is not available for first or last frames, for image tasks, or with the direct Seedance models.
Limits
| Limit | Value |
|---|---|
| Saved items | 200 characters and 200 backgrounds, each kept for 1 year after saving |
| Generations | 100 per day, 2 running at a time |
| Saves | 20 uploaded backgrounds per day; saving a generated candidate does not count |
| Upload checks | 40 per day, one upload save at a time |
| Unsaved candidates | Deleted after 14 days |
Renaming and deleting
Rename an item or add a note with PATCH; its look never changes, so to change a character, draw a new one and save it. DELETE removes an item at once: a new task that uses it then fails with library_item_not_found, while a task that is already running finishes first. For the full reference, see the Library section of the docs, and for keeping a cast consistent with your own photos, see Using Reference Images for Consistent Faces.