The AI Maraya API

Quickstart

POST /v1/generations takes a multipart form (not JSON), so reference files can be attached directly. It returns 202 with the job id.

curl -X POST https://www.aimaraya.live/v1/generations \
  -H "Authorization: Bearer $AI_MARAYA_API_KEY" \
  -F category=video \
  -F model=vseed25 \
  -F prompt="A cinematic sunrise above Dubai, slow aerial push-in" \
  -F duration=5s \
  -F aspect_ratio=16:9 \
  -F resolution=720p

const form = new FormData();
form.append("category", "video");
form.append("model", "vseed25");
form.append("mode", "refs");
form.append("prompt", "@image1 walks through a neon market at night.");
form.append("duration", "8s");
form.append("aspect_ratio", "16:9");
form.append("resolution", "720p");
form.append("files", imageBlob, "character.jpg");

const job = await fetch("https://www.aimaraya.live/v1/generations", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.AI_MARAYA_API_KEY}` },
  body: form, // do not set Content-Type; fetch adds the multipart boundary
}).then((r) => r.json());

// Poll until done (or pass webhook_url instead)
let status;
do {
  await new Promise((r) => setTimeout(r, 10_000));
  status = await fetch(`https://www.aimaraya.live/v1/generations/${job.id}`, {
    headers: { Authorization: `Bearer ${process.env.AI_MARAYA_API_KEY}` },
  }).then((r) => r.json());
} while (status.status === "queued" || status.status === "running");

console.log(status.status, status.output_url, status.error);

Request fields

Attach references with mode=refs. Each type is numbered separately in the order you send them: the 1st image is @image1, the 2nd image @image2, the 1st video @video1, the 1st audio file @audio1. Say in the prompt what each one is for (“@image1 is Mara”, “use the voice from @audio1”). Variants like @img1 or@Image 1 are normalised automatically.

• Seedance 2.5: up to 30 images, 10 videos and 10 audio files; all videos together and all audio together max 30 seconds.
• Images: JPG/PNG/WebP, at least ~300px per side. Videos: MP4 recommended; iPhone HEVC/.mov and small videos are converted automatically. Audio: MP3/WAV recommended; M4A/AAC/OGG converted automatically.
• Use original material. References detected as copyrighted (film/TV clips, commercial songs, celebrity photos) are rejected by the model; the job fails with that reason and the allowance is returned.
• Per-model limits are in GET /v1/models (caps.max_images, max_videos, max_audio).

curl -X POST https://www.aimaraya.live/v1/generations \
  -H "Authorization: Bearer $AI_MARAYA_API_KEY" \
  -F category=video \
  -F model=vseed25 \
  -F mode=refs \
  -F prompt="@image1 is Mara. @image2 is the yacht deck. Mara walks along @image2 at sunset, rain starting." \
  -F duration=10s \
  -F aspect_ratio=9:16 \
  -F resolution=720p \
  -F files=@mara.jpg \
  -F files=@yacht.jpg

curl -X POST https://www.aimaraya.live/v1/generations \
  -H "Authorization: Bearer $AI_MARAYA_API_KEY" \
  -F category=video \
  -F model=vseed25 \
  -F mode=refs \
  -F prompt="@image1 walks through @image2 at golden hour." \
  -F duration=10s \
  -F aspect_ratio=9:16 \
  -F resolution=720p \
  -F image_urls='["https://example.com/character.jpg","https://example.com/location.jpg"]'

Send a source video as @video1 with an editing instruction — replace, change, remove, add, edit — to edit that video instead of generating a new one (e.g. swap a person for @image1, change the background, remove an object). For an edit, the output follows the source video's length and aspect ratio; the duration and aspect_ratio you send are ignored. Source videos of 4–30 seconds are accepted; under 20 seconds gives the most stable results.

curl -X POST https://www.aimaraya.live/v1/generations \
  -H "Authorization: Bearer $AI_MARAYA_API_KEY" \
  -F category=video \
  -F model=vseed25 \
  -F mode=refs \
  -F prompt="Replace the man on the left in @video1 with @image1. Keep the scene, camera and motion." \
  -F files=@source.mp4 \
  -F files=@actor.jpg

There is no practical prompt length limit on Seedance (up to 20,000 characters). However, a video model renders one continuous clip and tends to follow only the first part of a very long, multi-shot prompt. So for video prompts over 2,500 characters we automatically rewrite the prompt into a compact, timestamped shot script ([0-4s] … [4-9s] …, or Shot 1 / Shot 2 on Seedance 2.0) that keeps every shot, every @ tag and every dialogue line — so later shots are no longer skipped. Your original prompt is kept on the job.

To send your prompt exactly as written, add -F parameters='{"optimize_prompt": false}'. Tip: for the best adherence, write your own prompt as timestamped segments and keep each generation to a few shots.

Model-specific hard caps: Kling 3.0 models accept at most 2,500 characters and Suno v5 at most 3,000 — longer prompts fail immediately with a clear message and no allowance used.

Request bodies over ~4 MB are rejected at the edge. For larger references (up to 100 MB each) upload in 2 MB chunks, then pass the uploadIds in uploaded_files. position sets where the file sits in the reference order (and therefore its @ number).

# 1) start
curl -X POST https://www.aimaraya.live/v1/uploads/init \
  -H "Authorization: Bearer $AI_MARAYA_API_KEY" -H "Content-Type: application/json" \
  -d '{"filename":"source.mp4","contentType":"video/mp4","size":38123456}'
# -> {"uploadId":"UPL","chunkSize":2097152,"totalChunks":19}

# 2) send each 2 MB chunk (index 0..totalChunks-1)
curl -X PUT "https://www.aimaraya.live/v1/uploads/UPL/chunk?index=0" \
  -H "Authorization: Bearer $AI_MARAYA_API_KEY" --data-binary @part-0

# 3) finish
curl -X POST https://www.aimaraya.live/v1/uploads/UPL/complete \
  -H "Authorization: Bearer $AI_MARAYA_API_KEY"

# 4) reference it (position = its place in the reference order)
  -F uploaded_files='[{"uploadId":"UPL","position":0}]'

Job status & errors

{
  "id": "PuTfR6cpcXMAOuqU",
  "status": "completed",          // queued | running | completed | failed | cancelled
  "progress": 100,
  "stage": "Done",
  "model": "vseed25",
  "type": "video",
  "output_url": "/api/files/maraya_video_PuTfR6cpcXMAOuqU.mp4",
  "error": "",                    // plain-language reason when status is "failed"
  "note": "",                     // extra info, e.g. why output settings differ
  "created_at": 1790415692
}

Endpoints