Video

POSThttps://api.aderra.ai/v1/videos/generations

Makes a clip of 5 to 15 seconds in one of four modes: from the prompt alone, from your most recent image, from references (images and earlier clips), or by editing an earlier clip. Video is priced per second, per model and mode: see Video models.

Request body

promptstringrequired

What happens in the clip. In image mode, the motion to add; in edit mode, the change to make.

modestringoptional

text, image, reference or edit: see Modes. Absent: image if you have a recent image, otherwise text. Send it, so a clip never depends on what you did before.

durationintegeroptional

Seconds, 5 to 15. Clamped into that range; the clamped length is what is made and paid for. Absent: 5.

modelstringoptional

A video model id from Video models. Absent, or a name Aderra does not know: the mode’s model (minimax-h3, or wan-edit for edits). A model that does not make the mode is refused with video_mode_unavailable.

explicitbooleanoptional

With mode and no model: use the mode’s uncensored model. It is used only when the prompt asks for nudity or sex; otherwise the clip is made by the standard model. Default false.

end_framebooleanoptional

image mode: use your two most recent images, the older as the first frame and the newer as the last. Default false.

image_countintegeroptional

reference mode: how many of your recent images to use, 0 to 9 (default 1; at most 8 are kept). edit mode: 1 to guide the edit with your most recent image (default 0).

reference_video_countintegeroptional

reference mode: how many of your recent clips to use, 0 to 3. Default 0.

source_videointegeroptional

edit mode: which clip to edit, counted back from the newest: 1 is your most recent clip. 1 to 20, default 1.

video_originstringoptional

Which clips source_video and reference_video_count count: generated (clips Aderra made) or upload (videos uploaded in the Aderra app). Absent: both.

cURL

curl https://api.aderra.ai/v1/videos/generations \
  --max-time 900 \
  -H "Authorization: Bearer $ADERRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Waves crash against a lighthouse at dusk, slow push in",
    "mode": "text",
    "duration": 5
  }'

Python

import os
import requests

r = requests.post(
    "https://api.aderra.ai/v1/videos/generations",
    headers={"Authorization": f"Bearer {os.environ['ADERRA_API_KEY']}"},
    json={
        "prompt": "Waves crash against a lighthouse at dusk, slow push in",
        "mode": "text",
        "duration": 5,
    },
    timeout=900,  # the call stays open until the clip is ready
)
r.raise_for_status()
clip = r.json()["data"][0]
video = requests.get(clip["url"], timeout=120)
open("clip.mp4", "wb").write(video.content)

Node

import fs from 'node:fs';

const r = await fetch('https://api.aderra.ai/v1/videos/generations', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.ADERRA_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    prompt: 'Waves crash against a lighthouse at dusk, slow push in',
    mode: 'text',
    duration: 5,
  }),
  signal: AbortSignal.timeout(900_000),
});
const { data } = await r.json();
const clip = await fetch(data[0].url);
fs.writeFileSync('clip.mp4', Buffer.from(await clip.arrayBuffer()));

Response

{
  "created": 1762948800,
  "data": [{ "url": "https://...", "duration_seconds": 5, "mode": "text" }]
}

Response: application/json

Modes

mode	What it makes	What it uses	Model (standard / explicit)
text	A clip from the prompt alone	Nothing else	minimax-h3 / sd-fast
image	Your most recent image, animated	1 image, or 2 with end_frame	minimax-h3 / minimax-h3-spicy
reference	A new clip that keeps the subject, style or motion of its references	Up to 8 images (image_count) and up to 3 earlier clips (reference_video_count); at least one	minimax-h3 / sd-fast
edit	An earlier clip, changed as the prompt says	1 clip (source_video), and optionally 1 image (image_count: 1)	wan-edit / sd-edit

The response’s mode says which mode ran.

Where the inputs come from

The request never carries an image, a video or a URL. Inputs are named by position, newest first, and come only from your own account:

• Images are the ones you made with /v1/images/generations, or sent as an image_url part to /v1/chat/completions, within roughly the last two hours. Aderra keeps your 8 most recent. To use a picture of your own, send it in a chat completion right before the video call.
• Clips are the ones this account made in the last 7 days, through the API or in the Aderra app, and videos uploaded in the Aderra app (kept for 7 days). source_video: 1 is the newest. video_origin limits the count to one kind. Aderra keeps only the link the model returned, not the file, so edit a clip soon after making it.

For example, to animate a photo from its first frame to a second photo:

{ "prompt": "She turns and walks out of frame", "mode": "image", "end_frame": true }

To make a new clip from your two latest images and your latest clip:

{ "prompt": "The same character, now running through rain", "mode": "reference",
  "image_count": 2, "reference_video_count": 1 }

To edit the clip before your latest one:

{ "prompt": "Make it snow", "mode": "edit", "source_video": 2 }

Only your own images, or people who agreed

Use images and videos of yourself, or of people who agreed to it, and never of anyone under 18. Sexual or intimate images of a real person made without their consent are against the content policy, and a crime in many countries.

Uncensored video

explicit: true picks each mode’s uncensored model (sd-fast, minimax-h3-spicy or sd-edit), within the content policy. It is used only when the prompt asks for nudity or sex; any other prompt is made by the standard model, at the standard price. Naming an uncensored model in model works the same way.

sd-fast cannot use images as references: in reference mode with explicit, send image_count: 0 and at least one reference_video_count. Images are refused with reference_images_unavailable.

Prices

Each model’s price per second, for each mode, is in the Video models table. A clip costs that price times its length, held before the clip is made and charged only when it is delivered.

In GET /v1/usage/prices, each video entry’s per_second is the model’s text and image price. A reference clip costs more: $0.18 a second on minimax-h3, $0.30 on sd-fast.

How it works

• The call is synchronous and slow. The connection stays open until the clip is finished: seconds for a short text clip, several minutes for an edit or an uncensored clip. Aderra gives up after 9 minutes, and charges nothing. Set your HTTP client’s timeout to at least 10 minutes. If the connection drops, the clip may still be made and charged.
• Download the clip straight away. data[0].url points to the finished file. Aderra does not keep a copy, and the link does not last.
• Refusals. When a standard model refuses the prompt, Aderra rewords it once and tries again; prompt_rewritten: true then appears in the response. An image clip still refused may be made once more on minimax-h3-open, at that model’s price. A clip refused in the end is not charged.

Building a multi-user product?

Recent images and clips are shared by every key on your account. Send one user’s image and their video request back to back, and don’t run two users’ videos at the same moment on one account.

Errors

Status	error	What to do
400	invalid_json, missing_prompt	Send a JSON body with a non-empty prompt
400	invalid_duration	duration must be a whole number above 0
400	invalid_mode	mode must be one of modes in the response
400	invalid_image_count, invalid_reference_video_count	A whole number from 0 to max in the response
400	invalid_source_video, invalid_end_frame, invalid_video_origin, invalid_explicit	Fix the field’s value
400	image_required	image mode with no recent image: generate or send an image first
400	end_frame_requires_two_images	end_frame needs two recent images
400	reference_required	reference mode found no image or clip to use
400	source_video_required	edit mode found no clip at that position
400	reference_images_unavailable	The model takes only clips as references: send image_count: 0
400	video_mode_unavailable	The model does not make that mode: drop model, or pick one from Video models
402	api_wallet_empty, key_spend_cap_reached	Add funds, or raise the key’s cap
422	video_content_refused	The model refused the prompt. Not charged. Reword it
502	video_failed	The model failed. Not charged. Try again

The 400 errors from image_required down also carry a message in plain English. See Errors for the shapes and the limits every endpoint shares.