88API88API
User GuideAI ApplicationsAPI ReferenceHelp & Support
Video

Complete Video API Standard

Unified 88API video generation standard covering references, keyframes, polling, downloads, and errors.

This is the 88API standard for asynchronous video generation. Always use the public 88API model name and the public task id returned by the API.

All current public video models share the create, polling, and download lifecycle. Reference-media fields are model-family specific, however; do not apply one family's media example to every model.

Updated 2026-11-13. Model-specific parameters and examples now live on separate brand pages; see Brand pages. Reuse an accessible HTTPS reference directly, or upload a local file first. Then create a task, retrieve its result URL, and use that URL for playback, download, or another model's reference input. Storage support does not imply model support or automatic transcoding.

Task API (2026-09-15): Seedance (doubao-seedance-2.0, doubao-seedance-2.5, doubao-seedance-2.5-flash, doubao-seedance-2.0-fast, doubao-seedance-2.0-mini), Wan3, and MiniMax H3 use POST /v1/videos. Save the returned id and poll GET /v1/videos/{id}. Do not depend on task_id. All video models return results via polling; do not set callback_url. Model names and authentication are unchanged. The old /v1/video/generations endpoint is retained for transitional use on selected models only; new integrations must use /v1/videos.

Endpoints

PurposeMethod and path
Create a videoPOST https://api.88api.ai/v1/videos
Retrieve task statusGET https://api.88api.ai/v1/videos/{id}
Request an upload permitPOST https://api.88api.ai/v1/media/uploads
Upload file bytesPUT {upload_url} with the returned upload headers
Download the resultGET {url} using the completed response's URL
Legacy archived-video redirectGET https://api.88api.ai/v1/videos/{id}/content — not universal for every result
Authorization: Bearer sk-your-api-key
Content-Type: application/json
Accept: application/json

Keep API keys on your server. Never embed them in browser, mobile, or desktop client code.

Creating/querying tasks and requesting upload permits require Bearer authentication at api.88api.ai. Uploads use only the scoped X-Media-Upload-Token and MIME header returned in the permit. Public assets.88api.ai media reads require no Bearer or cookies. Never forward your API key to media URLs, official result hosts, or redirect destinations. Anyone holding a public URL can read the media during its lifetime; task details remain authenticated.

Basic text-to-video request

curl --request POST 'https://api.88api.ai/v1/videos' \
  --header 'Authorization: Bearer sk-xxxx' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "model": "doubao-seedance-2.5",
    "resolution": "720p",
    "prompt": "A silver sports car driving through a neon city at night, cinematic tracking shot",
    "duration": 8,
    "size": "16:9"
  }'

You may use an integer duration or a string seconds, for example "8".

Common request fields

FieldTypeRequiredDescription
modelstringyesExact public model name shown by 88API
promptstringconditionalPrompt; only selected reference-capable models allow it to be empty
negative_promptstringnoNegative prompt for multi-reference models; Veo uses metadata.negativePrompt
durationintegernoDuration in seconds; mutually exclusive with seconds
secondsstringnoDuration as a string
sizestringnoAspect ratio or size, such as 16:9 or 1280x720
imagestringnoOne reference image URL
imagesstring[]noReference image URLs; recommended image form
video / videosstring / string[]noGemini Omni requires these top-level fields; multi-reference families use metadata.referenceVideos
seedintegernoRandom seed
generate_audiobooleannoGenerate audio on models that explicitly support it
metadataobjectnoVideo/audio references, keyframes, and other extensions

Some models fix the output resolution in the public model name; resolution cannot override those. Others (for example Seedance, Google, MiniMax, Wan and Grok) select it with resolution. Field names also differ by brand; follow the brand pages.

Reference media

Reference images

Use the top-level images array for consistent behavior across current models:

{
  "model": "doubao-seedance-2.5",
  "resolution": "720p",
  "prompt": "Keep the same character identity and clothes, walking by the sea",
  "duration": 10,
  "size": "16:9",
  "images": [
    "https://cdn.example.com/character-front.jpg",
    "https://cdn.example.com/character-side.jpg"
  ]
}

Reference videos and audio for multi-reference models

For the Seedance and H3 families that support multiple references, put video and audio references in metadata (Wan recommends the media array; see Wan Video API):

{
  "model": "doubao-seedance-2.5",
  "resolution": "720p",
  "prompt": "Use the product appearance, camera motion, and sound rhythm from the references",
  "duration": 12,
  "size": "16:9",
  "images": ["https://cdn.example.com/product.jpg"],
  "metadata": {
    "referenceVideos": [
      "https://cdn.example.com/camera-motion.mp4"
    ],
    "referenceAudios": [
      "https://cdn.example.com/sound-reference.mp3"
    ]
  }
}

Do not submit multiple aliases for the same media type. For example, do not send both top-level images and metadata.referenceImages; compatibility aliases are selected, not guaranteed to be merged.

For reference images of minimax-h3, do not use top-level images; use metadata.referenceImages as described in MiniMax Video API.

First and last frames

{
  "model": "doubao-seedance-2.0",
  "prompt": "Smoothly transition from the morning frame to the night frame",
  "duration": 10,
  "size": "16:9",
  "metadata": {
    "firstFrame": "https://cdn.example.com/start.jpg",
    "lastFrame": "https://cdn.example.com/end.jpg"
  }
}

lastFrame requires firstFrame. For models marked as exclusive below, keyframes cannot be mixed with ordinary image, video, or audio references. Veo instead uses ordered images with metadata.video_mode, as described in Google Video API.

Media URL requirements

  • Use directly downloadable public HTTPS URLs for reference video/audio; local paths, blob: and data:video/... are not a portable reference-video protocol. Upload local files first.
  • URLs must not require cookies, login state, Referer, or custom headers.
  • Do not use localhost, private IPs, container hostnames, or intranet-only URLs.
  • Keep URLs valid for at least 60 minutes after task creation.
  • Recommended formats: JPG/PNG/WebP, MP4/MOV, and MP3/WAV.
  • Keep each reference video below 50 MB and each reference audio file below 15 MB when possible.
  • Only submit material you are authorized to use.

Local media: permit, upload, reference

Send JSON to POST /v1/media/uploads with your server-side Bearer key:

{
  "size": 1234567,
  "mime_type": "video/mp4",
  "sha256": "<SHA-256 of the raw file encoded as unpadded Base64URL>"
}

size is an integer from 1 to 100,000,000 bytes. sha256 encodes the 32-byte digest, not its hexadecimal string. Accepted MIME types: video/mp4, video/webm, video/quicktime; audio/mpeg, audio/wav, audio/ogg, audio/mp4, audio/flac; image/png, image/jpeg, image/webp, image/gif. Model-specific size, duration, codec and reference limits still apply.

The HTTP 200 receipt contains url, upload_url, method: "PUT", headers (Content-Type and X-Media-Upload-Token), and expires_at (Unix seconds). This expiry is the approximately 10-minute upload permit deadline, not the media retention deadline. The URL is not ready until the upload succeeds.

Send the original binary file to upload_url with the returned method and headers. Supply the exact Content-Length and MIME; browsers sending File/Blob calculate the length automatically. Do not send multipart/form-data, JSON Base64, your API key, or an unknown-length chunked stream.

curl --request PUT "$UPLOAD_URL" \
  --header 'Content-Type: video/mp4' \
  --header "X-Media-Upload-Token: $UPLOAD_TOKEN" \
  --data-binary @reference.mp4

HTTP 201 confirms storage and returns url, size, mime_type, and expires_at. This second expiry is the media retention deadline, 30 days from object upload. Use the returned URL in the target model's reference field only after success. The upload service does not transcode, compress or extract frames. Repeated PUTs cannot overwrite the object (409); after an ambiguous upload, HEAD the permit's URL before allocating another object. Browser apps should obtain permits through their own backend, without exposing a long-lived API key.

Current public model capabilities

Brand pages

Parameter names and media fields differ between brands. Read the brand page before integrating:

Brand pageModels
Seedancedoubao-seedance-2.0, doubao-seedance-2.5, doubao-seedance-2.5-flash, doubao-seedance-2.0-fast, doubao-seedance-2.0-mini
Googleveo-3.1, veo-3.1-fast, gemini-omni-flash-1.1, gemini-omni-flash-1.2
MiniMaxminimax-h3
Wanwan3.0-video, wan3.0-video-prime
Grokgrok-imagine-video, grok-imagine-video-1.5

Capability overview

Public modelDurationRatiosOutputImage/video/audio limitsKeyframesAudio control
doubao-seedance-2.04–15s; -1 allowed16:9, 4:3, 1:1, 3:4, 9:16, 21:9, adaptive480P/720P/1080P/4K, default 720P9 / 3 / 3yes, exclusive with ordinary referencesaudio on by default; can be turned off
doubao-seedance-2.54–30s; -1 allowedsame as above480P/720P/1080P, default 720P30 / 10 / 10yes, exclusive with ordinary referencesaudio on by default; can be turned off
doubao-seedance-2.5-flash4–30s; -1 allowedsame as above480P/720P, default 720P10 / 5 / 5yes, exclusive with ordinary references; with a first frame the ratio follows the first-frame imageaudio on by default; can be turned off
doubao-seedance-2.0-fast4–15s; -1 allowedsame as above480P/720P, default 720P9 / 3 / 3yes, exclusive with ordinary referencesaudio on by default; can be turned off
doubao-seedance-2.0-mini4–15s; -1 allowedsame as above480P/720P, default 720P9 / 3 / 3yes, exclusive with ordinary referencesaudio on by default; can be turned off
veo-3.14/6/8s; reference images 8s; extension adds 7s16:9, 9:16720P/1080P/4K3 / 0 / 0first frame, first and last frames, reference imagesnative audio; generate_audio can turn it off
veo-3.1-fastfixed 8s output16:9, 9:16fixed 720P output3 / 0 / 0first frame, first and last frames, reference imagesalways includes audio
gemini-omni-flash-1.13–10s, default 3s16:9, 9:16720P/1080P/4K10 / 3 / 0first frame, first and last framesno
gemini-omni-flash-1.23–15s, default 3s16:9, 9:16720P/1080P/4K10 / 3 / 0first frame, first and last framesno
minimax-h34–15s, default 5s16:9 (default), 9:16, 1:1, 4:3, 3:4, 21:9; 1080P/2K: 16:9, 9:16 only768P/1080P/2K (upscaled), default 768P9 (6 at 1080P/2K) / – / 3768P only, exclusivealways includes audio; not configurable
wan3.0-video2–30s, default 5s; -1 allowedadaptive (default), 16:9, 9:16, 1:1, 4:3, 3:4, 21:9480P/720P/1080P, default 1080P10 / 5 / 5 (in the media array)yes, exclusivenot configurable
wan3.0-video-primesame as abovesame as abovesame as abovesame as abovesame as abovenot configurable
grok-imagine-video1–15s, default 8s; up to 10s with reference images16:9, 9:16, 1:1, 4:3, 3:4, 3:2, 2:3 (via aspect_ratio)480P/720P14 / 0 / 0first frame only, not together with reference imagesno
grok-imagine-video-1.51–15s, default 8ssame as above480P/720P/1080P; up to 720P with a last frame, keyframes, reference images or reference voices14 (first/last frame and keyframes extra) / 0 / 0first and last frame plus up to 4 keyframes, can be combined with reference imagesno

Available models and account access may change. Use the live model list for discovery.

Model-specific rules that are easy to get wrong (see the brand pages above for the full rules):

  • Wan wan3.0-video*: send first frames, last frames and references in the media array (recommended). metadata.firstFrame/lastFrame/referenceImages/referenceVideos/referenceAudios (snake_case forms too), a top-level firstFrame/first_frame/lastFrame/last_frame and top-level images (1st = first frame, 2nd = last frame, at most 2) are also converted to media. Material fields that cannot be read return 400.
  • Grok treats aspect_ratio and ratio as equivalent; if you send several ratio fields, their values must match. One first frame at most; send the last frame in last_frame, keyframes in keyframes and reference images in reference_images, and grok-imagine-video-1.5 can also pick up to 3 preset voices with reference_audios. See the Grok Video API.
  • minimax-h3 takes reference images in metadata.referenceImages and first/last frames in metadata.firstFrame/lastFrame; the purpose of top-level images is not fixed, so state it explicitly with metadata.referenceImages / metadata.firstFrame. 480P and 4K have been retired.
  • Veo and Gemini Omni take reference videos in top-level video/videos, not metadata.referenceVideos. gemini-omni-flash has been retired; Gemini Omni and veo-3.1-fast do not support video extension, and veo-3.1-fast always outputs 720P, 8-second video with audio.
  • Seedance (doubao-seedance-2.0, doubao-seedance-2.5, doubao-seedance-2.5-flash, doubao-seedance-2.0-fast, doubao-seedance-2.0-mini) is billed by actual tokens. Reference media can use fields such as images, videos, audios and firstFrame/lastFrame, or the Volcengine Ark content array, either at the top level or in metadata. https:// image and video URLs are stored in an asset library automatically, so photos and videos of real people can be used as references. Results are Ark links that expire after 24 hours, and tasks cannot be cancelled once submitted. See the Seedance Video API.
  • seedance-2.0, seedance-2.5, seedance-2.0-mini and seedance-2.0-fast (billed per second) were retired on 2026-11-12; the earlier SD2.0, SD2.5 and the Seedance model names with the "官方版" suffix have also been retired. Switch to the model of the same name with the doubao- prefix. Uploading cannot add unsupported model capabilities.

Create response

{
  "id": "task_xxxxxxxxxxxxxxxxxxxxxxxx",
  "object": "video",
  "model": "doubao-seedance-2.5",
  "status": "queued",
  "progress": 0,
  "created_at": 1788249600
}

Save id. The standard interface does not guarantee task_id; new integrations must use id. HTTP 200 means the task was accepted, not that generation has finished.

Polling

curl 'https://api.88api.ai/v1/videos/task_xxx' \
  --header 'Authorization: Bearer sk-xxxx'
StatusMeaningAction
queuedwaitingkeep waiting
in_progressgeneratingkeep waiting
completedfinisheduse the returned result url
failedfailedinspect error.code and error.message
unknownunknownretry briefly, then contact support if persistent

Wait 3–5 seconds before the first query and poll every 10–15 seconds. Interactive clients may stop waiting after 15 minutes, persist the task ID and resume querying later. A client deadline does not cancel, fail or refund the task; per-request HTTP timeouts and server task deadlines are separate. Use status, not progress alone. Never create a duplicate simply because polling timed out.

On completion, read url (compatible aliases: video_url, result_url). The result URL may be on https://assets.88api.ai/media/... or be the model platform's original address; use it exactly as returned. Save the returned address rather than constructing a content path.

Downloading the result

After status=completed:

curl --fail --location "$RESULT_URL" --output result.mp4

Use the result URL returned by polling. Follow redirects without forwarding your API key. The old /v1/videos/{id}/content path redirects archived videos (307) for compatibility with older clients only; do not use it as a fixed way to fetch results. On a legacy 404, query the task for its actual URL instead of generating again.

Retention and cross-model reuse

Stored references and archived videos last 30 days from their respective object uploads. Reads, task queries and repeated references do not renew them. Direct URLs from the model platform follow the platform's own lifetime, which may be shorter than 30 days (Seedance results, for example, last only 24 hours); download them promptly. Expired media may return 410, or 404 after deletion; an existing task record does not guarantee that its bytes still exist. Copy results to your own storage for longer retention.

Public media supports GET, HEAD, single-range requests (206), and browser CORS. X-Media-Expires-At is Unix seconds. Caching does not extend retention or guarantee identical regional download speeds. Preserve any capability parameters on URLs returned by the API; do not add query parameters to assets URLs (400), replace domains, or strip required parameters.

A Veo output can become another model's video reference if that model supports video input and the file meets its limits. Put the complete result URL directly in that model's reference field, with no download/reupload step. veo-3.1 accepts an input video only for extension, veo-3.1-fast accepts no input video, and neither supports reference videos. Public URLs allow anyone holding them to read the file while available.

Complete upload and polling example

Node.js 22+; set server-side API_KEY and REFERENCE_FILE (an MP4). To resume without creating a new task, set TASK_ID. The example creates one paid generation; the next request body is printed only. It buffers at most one permitted file, so bound concurrency for large files.

// video-api-example.mjs — Node.js 22+, run with API_KEY, MODEL_ID, and REFERENCE_FILE.
import { readFile, stat } from "node:fs/promises";
import { createHash } from "node:crypto";

const apiKey = process.env.API_KEY;
if (!apiKey) throw new Error("Set API_KEY on your server");
const baseUrl = "https://api.88api.ai";
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

async function apiJSON(path, body) {
  // No automatic POST retry: a timed-out create may already have been accepted.
  const response = await fetch(baseUrl + path, {
    method: "POST",
    headers: { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json" },
    body: JSON.stringify(body),
    signal: AbortSignal.timeout(120000),
  });
  if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
  return response.json();
}

async function uploadMedia(file, mimeType) {
  const info = await stat(file);
  if (!info.isFile() || info.size < 1 || info.size > 100000000) {
    throw new Error("File must contain 1–100000000 bytes");
  }
  const bytes = await readFile(file);
  const permit = await apiJSON("/v1/media/uploads", {
    size: bytes.length, mime_type: mimeType,
    sha256: createHash("sha256").update(bytes).digest("base64url"),
  });
  const target = new URL(permit.upload_url);
  if (target.origin !== "https://assets.88api.ai" || permit.method !== "PUT") {
    throw new Error("Unexpected upload destination; do not send credentials");
  }
  const response = await fetch(target, {
    method: "PUT", headers: permit.headers, body: bytes,
    redirect: "error", signal: AbortSignal.timeout(120000),
  });
  // A 409/ambiguous upload is not automatically retried; HEAD permit.url first.
  if (response.status !== 201) throw new Error(`Upload HTTP ${response.status}`);
  return response.json();
}

async function waitForVideo(id, budgetMs = 15 * 60 * 1000) {
  const deadline = Date.now() + budgetMs;
  let delay = 4000;
  while (Date.now() < deadline) {
    await sleep(Math.min(delay, deadline - Date.now()));
    const remaining = deadline - Date.now();
    if (remaining <= 0) break;
    let response, state;
    try {
      response = await fetch(`${baseUrl}/v1/videos/${encodeURIComponent(id)}`, {
        headers: { Authorization: `Bearer ${apiKey}` },
        signal: AbortSignal.timeout(Math.min(30000, remaining)),
      });
      if (response.ok) state = await response.json();
    } catch {
      delay = Math.min(delay * 2, 60000);
      continue; // Retry a read, never create a replacement task.
    }
    if (response.status === 429 || response.status >= 500) {
      const retryAfter = response.headers.get("Retry-After");
      const seconds = retryAfter && /^\d+$/.test(retryAfter)
        ? Number(retryAfter)
        : (Date.parse(retryAfter || "") - Date.now()) / 1000;
      delay = Number.isFinite(seconds) && seconds > 0
        ? Math.max(1000, seconds * 1000)
        : Math.min(delay * 2, 60000);
      await response.body?.cancel();
      continue;
    }
    if (!response.ok) throw new Error(`Task ${id}: HTTP ${response.status}`);
    if (state.status === "completed") {
      const result = state.url || state.video_url || state.result_url;
      if (typeof result !== "string" || new URL(result).protocol !== "https:") {
        throw new Error(`Task ${id} completed without a usable HTTPS result URL`);
      }
      return result; // Keep official URLs and capability query parameters intact.
    }
    if (state.status === "failed") {
      throw new Error(`Task ${id}: ${state.error?.message || "video generation failed"}`);
    }
    if (!["queued", "in_progress", "unknown"].includes(state.status)) {
      throw new Error(`Task ${id}: unexpected status ${state.status}`);
    }
    delay = 12000;
  }
  throw new Error(`Stopped waiting for ${id}; save this ID and query later. Not cancelled.`);
}

async function main() {
  // Resume a saved task without uploading or creating another paid task.
  let id = process.env.TASK_ID;
  if (!id) {
    if (!process.env.MODEL_ID) throw new Error("Set MODEL_ID from GET /v1/models");
    if (!process.env.REFERENCE_FILE) throw new Error("Set REFERENCE_FILE");
    const media = await uploadMedia(process.env.REFERENCE_FILE, "video/mp4");
    const task = await apiJSON("/v1/videos", {
      model: process.env.MODEL_ID, prompt: "Preserve the subject and motion of the reference video and continue the shot",
      duration: 4, ratio: "16:9", metadata: { referenceVideos: [media.url] },
    });
    id = task.id;
    if (!id) throw new Error("Create response did not contain a task ID; do not blindly retry");
    console.log("Save task ID:", id); // Persist to your database in production.
  }
  const resultURL = await waitForVideo(id);
  console.log("Result URL:", resultURL); // This grants media access; do not log publicly.
  // This only shows the NEXT request body; it does not create a second paid task.
  console.log(JSON.stringify({
    model: process.env.MODEL_ID, prompt: "Preserve the subject and motion of the reference video and continue the shot",
    duration: 4, ratio: "16:9", metadata: { referenceVideos: [resultURL] },
  }, null, 2));
}

await main();

Retry and error rules

  • 400: invalid model, duration, ratio, field placement, or reference count.
  • 401: missing or invalid API key.
  • 403: the key cannot access the model or group.
  • 404: task not found, not owned by the account, or content not ready.
  • Upload409: object already exists; HEAD and reuse a confirmed successful upload.
  • Media410: expired; references do not renew retention (404 is possible after cleanup).
  • Upload415: file signature does not match its MIME type.
  • Media416: invalid or out-of-bounds Range; check length with HEAD.
  • 429: apply Retry-After or exponential backoff.
  • 5xx: status queries may be retried with backoff.
  • status=failed: the HTTP query succeeded but generation failed; inspect error.message.
  • unsupported_reference_media: unsupported model capability, not fixed by uploading.
  • must be a public HTTPS URL: upload local video first; no Blob, Data URL, HTTP or login-dependent URL.
  • input_download_failed: check upstream reachability, DNS/network and expiry, not just playback on your computer.

POST /v1/videos does not currently support custom idempotency keys. If a fully transmitted create request ends with an ambiguous network timeout, do not blindly resubmit it because duplicate tasks may be generated and billed.