JMovie API
On this page

JMovie API documentation, Uncensored Adult NSFW

Python examples for Seedance 2.5 Flash video, Seedream 5.5 images, layers and OCR, and Seed Audio 1.0 speech. Use Bearer authentication, idempotent requests and one task polling endpoint.

Quickstart

  1. Create an account and verify your email address to open your own API console.
  2. Create your Keys in the console. Fund your wallet from $30 through the Billing API or Console → Billing. Matched BSC USDT transfers are credited automatically.
  3. Send a Bearer Key with every request. Add an Idempotency-Key to paid requests (recommended) and keep it when retrying a request whose response was lost.
  4. Save the returned task ID and your original Idempotency-Key. Resume querying that task after a timeout; do not submit a second paid generation.
  5. Poll the task and check generation, billing and storage separately. Download generated media once storage is ready, before its 72-hour expiry.
curl -X POST https://api.j-movie.com/api/v3/contents/generations/tasks \
  -H "Authorization: Bearer $JMOVIE_API_KEY" \
  -H "Idempotency-Key: $JMOVIE_REQUEST_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "dreamina-seedance-2-5-260628",
    "content": [{"type":"text", "text":"A serene coastal town at sunset"}],
    "duration": 5,
    "resolution": "720p",
    "ratio": "16:9"
  }'

# Save the returned id. On a timeout, resend with the same Idempotency-Key: it returns the same task, never a second one.
curl https://api.j-movie.com/api/v3/contents/generations/tasks/$TASK_ID \
  -H "Authorization: Bearer $JMOVIE_API_KEY"

Start with Python: setup, model examples and task recovery

Python integration examples

Use Python 3.10+ and requests to call Seedance 2.5 Flash video, Seedream 5.5 images, layers and OCR, or Seed Audio 1.0 speech. These copyable HTTP examples need no proprietary SDK. Save the shared client as jmovie_client.py, then save ONE model example as run_example.py in the same folder.

  • Create and fund your API account, then create a server-side Key with the requested model enabled. Keep the Key in an environment variable or secret manager; never put it in browser code or a public repository.
  • Set JMOVIE_REQUEST_ID to a unique, persistent ID for this business operation before submitting. A different model example is a different paid operation and needs its own ID. Save the exact path and payload with that ID in your job store; save the returned task ID before starting polling. The print statement demonstrates the handoff, not durable job storage.
  • For layers or OCR, set JMOVIE_IMAGE_URL to your own PNG/JPEG HTTPS URL or an owned asset:// reference obtained through the Asset library guide. max_images includes the base image and bounds the reservation. OCR is a paid layer decomposition task with text recognition, not free text-only recognition.
  • Run python run_example.py after saving the files. Each example creates ONE paid task and polls it for up to about five minutes. Requests also have separate connect/read timeouts; the polling deadline does not cancel a request already in progress or the server task.
  • A connection error, timeout, invalid gateway response or HTTP 5xx does not prove that creation failed. Do not generate a new request ID: query the saved task, or recover with the same path, exact payload and Idempotency-Key. The client does not automatically retry paid POSTs.
  • APIError exposes code, status, request_id and retry_after. Handle INSUFFICIENT_BALANCE by pausing submissions and funding through the Billing API or console; KEY_LIMIT_EXCEEDED requires checking Key limits. For transient rate limiting, respect Retry-After (seconds or HTTP date) before retrying the same operation. Fix validation/authentication errors before retrying. A polling HTTP error means query the same task again, not create another task.
  • unknown is not a failed task. If polling times out or your process restarts, use the resume example below. Media readiness and financial settlement are separate: read billing_status and only treat actual_usd as final after settled. Keep USD strings precise; use decimal.Decimal in accounting.
  • Result URLs are private signed links valid for up to one hour; media retention is 72 hours. Download promptly with a separate unauthenticated HTTP request. Never forward your API Bearer Key to a media URL, CDN or third-party host. Query the task again to refresh a link within retention.
Set up a local Python environment (macOS/Linux shell)
python3 -m venv .venv
source .venv/bin/activate
python -m pip install requests
export JMOVIE_API_KEY="<your-server-side-key>"
export JMOVIE_REQUEST_ID="<unique-persistent-business-operation-id>"
# For layers/OCR only: use your own real image, not this placeholder.
export JMOVIE_IMAGE_URL="https://your-storage.example/source.png"
Shared client — save as jmovie_client.py
import os
import time
from urllib.parse import quote

import requests

BASE_URL = "https://api.j-movie.com/api/v3"


class APIError(RuntimeError):
    def __init__(self, response):
        try:
            body = response.json()
        except ValueError:
            body = {}
        if not isinstance(body, dict):
            body = {}
        self.code = body.get("code", "HTTP_ERROR")
        self.status = response.status_code
        self.request_id = response.headers.get("X-Request-Id", "")
        self.retry_after = response.headers.get("Retry-After")
        super().__init__(
            f"{self.status} {self.code}; request_id={self.request_id}; "
            f"retry_after={self.retry_after}"
        )


def api_request(method, path, *, payload=None, request_id=None):
    headers = {"Authorization": "Bearer " + os.environ["JMOVIE_API_KEY"]}
    if request_id is not None:
        if not request_id.strip():
            raise ValueError("Use a persistent business request ID")
        headers["Idempotency-Key"] = request_id
        headers["Prefer"] = "respond-async"
    response = requests.request(
        method, BASE_URL + path, headers=headers, json=payload,
        timeout=(10, 30), allow_redirects=False,
    )
    if not 200 <= response.status_code < 300:
        raise APIError(response)
    return response.json()


def create_task(path, payload, request_id):
    # One POST only. Save the request ID and exact payload BEFORE calling.
    # After a lost response, recover using the SAME path, payload and ID.
    if not isinstance(request_id, str) or not request_id.strip():
        raise ValueError("Use a persistent business request ID")
    body = api_request("POST", path, payload=payload, request_id=request_id)
    task_id = body["id"]  # Every model create response has a task ID.
    print("Save task ID:", task_id, flush=True)
    return task_id


def wait_for_task(task_id, *, wait_seconds=300):
    deadline = time.monotonic() + wait_seconds
    while time.monotonic() < deadline:
        # All models use this wrapped query response, including video.
        task = api_request("GET", "/tasks/" + quote(task_id, safe=""))["data"]
        if task["status"] == "succeeded" and task["storage_status"] == "ready":
            return task  # billing_status may still be pending.
        if task["status"] in ("failed", "cancelled", "expired"):
            raise RuntimeError(
                f"Task {task_id}: {task['status']} {task.get('error_code', '')}"
            )
        # queued, running and unknown: query again; never create again.
        time.sleep(min(5, max(0, deadline - time.monotonic())))
    raise TimeoutError(f"Resume polling task {task_id}; do not resubmit")
Seedance 2.5 Flash video — save as run_example.py
import json
import os
from jmovie_client import create_task, wait_for_task

task_id = create_task("/contents/generations/tasks", {
    "model": "dreamina-seedance-2-5-flash-261115",
    "content": [{"type": "text", "text": "A coastal town at sunset"}],
    "duration": 5, "resolution": "720p", "ratio": "16:9",
}, os.environ["JMOVIE_REQUEST_ID"])
task = wait_for_task(task_id)
print(json.dumps(task["result"], indent=2))
Seedream 5.5 image — save as run_example.py
import json
import os
from jmovie_client import create_task, wait_for_task

task_id = create_task("/images/generations", {
    "model": "dola-seedream-5-5-261028",
    "prompt": "A minimal product photograph of a ceramic cup",
    "size": "2K", "response_format": "url",
}, os.environ["JMOVIE_REQUEST_ID"])
task = wait_for_task(task_id)
print(json.dumps(task["result"]["data"], indent=2))
Seedream 5.5 layers — save as run_example.py
import os
from jmovie_client import create_task, wait_for_task

task_id = create_task("/images/layers", {
    "model": "dola-seedream-5-5-261028",
    "image": os.environ["JMOVIE_IMAGE_URL"],
    "size": "auto",
    "layer_decomposition_options": {"max_images": 10},
}, os.environ["JMOVIE_REQUEST_ID"])
task = wait_for_task(task_id)
for layer in task["result"]["data"]:
    print(layer.get("z_index"), layer.get("bounding_box"), layer["url"])
Seedream 5.5 rich-text OCR — save as run_example.py
import json
import os
from jmovie_client import create_task, wait_for_task

task_id = create_task("/images/ocr", {
    "model": "dola-seedream-5-5-261028",
    "image": os.environ["JMOVIE_IMAGE_URL"],
    "size": "auto",
    "layer_decomposition_options": {"max_images": 10},
}, os.environ["JMOVIE_REQUEST_ID"])
task = wait_for_task(task_id)
for layer in task["result"]["data"]:
    if "text_recognition" in layer:
        print(json.dumps(layer["text_recognition"], ensure_ascii=False, indent=2))
Seed Audio 1.0 speech — save as run_example.py
import os
from jmovie_client import create_task, wait_for_task

task_id = create_task("/tts/create", {
    "model": "seed-audio-1.0",
    "text_prompt": "The morning train leaves from platform two.",
    "audio_config": {"format": "wav", "sample_rate": 24000},
}, os.environ["JMOVIE_REQUEST_ID"])
task = wait_for_task(task_id)
print(task["result"]["url"])  # Private, signed audio URL.
Resume an existing task — no new generation or payment
# Set JMOVIE_TASK_ID to the task ID you saved earlier.
import json
import os
from jmovie_client import wait_for_task

task = wait_for_task(os.environ["JMOVIE_TASK_ID"])
print(json.dumps(task, ensure_ascii=False, indent=2))

Request and response reference

Exact fields, values and examples for every call. The same reference is included in /llms.txt for AI agents.

Generation APIs

Conventions

  • Base URL https://api.j-movie.com/api/v3. Create Keys yourself in the console (API keys, Create Key); creating or revoking one needs a sign-in within the last 15 minutes. Send Authorization: Bearer <Key>, and Content-Type: application/json on every call except the multipart asset upload. Every response carries X-Request-Id; quote it with the task id when contacting support.
  • Two body shapes exist. The native video endpoints (/contents/generations/tasks) return the bare Ark body. Unified tasks (/tasks), assets and asset groups wrap their data as {"success":true,"data":{...}}.
  • Errors always use {"code":"<JMovie code>","error":{"code":"<Ark code>","message":"...","param":"","type":"..."}}. Branch on the top-level code; error.code is the ModelArk equivalent for existing Ark clients.
  • Times are RFC 3339 UTC strings, except native video created_at and updated_at, which are Unix seconds as in Ark. Money fields are decimal USD strings.
  • Unknown request fields and explicit null values are rejected with 400 before anything is charged.

Create a video task

POST /api/v3/contents/generations/tasks. Returns 200, or 202 when you send Prefer: respond-async, with the native task body and a Location: /api/v3/tasks/<id> header.

  • model: dreamina-seedance-2-0-260128, dreamina-seedance-2-0-fast-260128, dreamina-seedance-2-0-mini-260615, dreamina-seedance-2-5-260628 or dreamina-seedance-2-5-flash-261115.
  • content: 1 to 51 items, each with type text, image_url, video_url, audio_url or draft_task and exactly one payload.
  • resolution: 480p, 720p (default), 1080p or 4k. Seedance 2.5 and 2.0 accept all four; Fast, Mini and 2.5 Flash allow 480p and 720p only. Flash does not support Draft or Final.
  • ratio: 16:9, 4:3, 1:1, 3:4, 9:16, 21:9 or adaptive (default). duration: 4 to 15 seconds (4 to 30 on 2.5 and 2.5 Flash), default 5; -1 means the model maximum.
  • Optional: generate_audio, watermark, return_last_frame, output_format (mp4; mov on 2.5 and 2.5 Flash), service_tier (default only), priority (0 to 9), safety_identifier (ASCII, at most 64 bytes), execution_expires_after (3600 to 259200 seconds, default 172800), callback_url.
  • Seedance 2.5 and 2.5 Flash: with reference media, omni_reference_task_type auto, reference, edit or extend. edit needs a reference video of at least 4 s, ratio adaptive and duration -1; extend needs a reference video and ratio adaptive.
  • There is no seed parameter; camera_fixed and inline flags such as --seed in the prompt are rejected.
Request
curl https://api.j-movie.com/api/v3/contents/generations/tasks \
  -H "Authorization: Bearer $JMOVIE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1842-video" \
  -d '{
    "model": "dreamina-seedance-2-0-mini-260615",
    "content": [{"type": "text", "text": "A paper boat drifts across a calm pond at sunrise."}],
    "resolution": "480p",
    "duration": 4
  }'
Response 200
{
  "id": "0a443c53-5cc3-41c0-8a5d-f4ac310ae216",
  "model": "dreamina-seedance-2-0-mini-260615",
  "status": "queued",
  "generation_status": "queued",
  "billing_status": "reserved",
  "storage_status": "pending",
  "service_tier": "default",
  "created_at": 1793370063,
  "updated_at": 1793370063,
  "trace": {
    "task_id": "0a443c53-5cc3-41c0-8a5d-f4ac310ae216",
    "request_id": "202610301421032674730498268d9d6SNEDS4rE",
    "idempotency_key": "order-1842-video",
    "upstream": {"provider": "byteplus", "task_id": "", "request_id": "", "log_id": "", "client_request_id": ""}
  }
}

Create an image task

POST /api/v3/images/generations returns 202 {"id","status","task"} and a Location header. Poll GET /api/v3/tasks/:id. Regular generation returns one image; Seedream 5.5 also supports layer bundles.

  • model: dola-seedream-5-5-261028 or dola-seedream-5-0-pro-260628. prompt: 1 to 20000 characters for regular generation.
  • image: optional reference image, a URL string or an array of 1 to 10 (asset://, https:// or data: URI).
  • size: 1K, 1.5K, 2K (default) or WIDTHxHEIGHT between 921,600 and 4,624,220 pixels with aspect ratio 1/16 to 16.
  • Optional: response_format (url or b64_json), output_format (png or jpeg), background, watermark, optimize_prompt_options.mode (standard or fast), callback_url. Seedream 5.5 supports opaque, transparent or auto background; transparent output requires png and can start from text or ordinary references. Seedream 5.0 Pro supports opaque or transparent; transparent requires exactly one reference image with alpha.
  • Not available: n, stream true, sequential_image_generation other than disabled. See the layer endpoints below for multi-layer output.
  • When succeeded, result.data[].url holds signed private image links; b64_json requests keep result.data[].b64_json and also provide artifacts[].url. Files are retained for 72 hours; query again to refresh the one-hour links.
  • Seedream 5.5 catalog units: $0.020 per output up to 2,601,123 pixels, $0.035 above; every input reference costs $0.008, including the first. Your account pricing factor applies. Seedream 5.0 Pro keeps its separate rates.

Decompose an image into layers

POST /api/v3/images/layers is a convenience endpoint for Seedream 5.5. It defaults model to dola-seedream-5-5-261028 and enables layer_decomposition. You can also send these native fields to /images/generations.

  • Send exactly one owned asset:// reference, public https:// URL or data: image. The source must be PNG or JPEG, at most 30 MiB and 262,144 to 36,000,000 pixels. prompt is optional.
  • layer_decomposition_options.max_images: integer 2 to 100, default 30, including the base image. text_recognition: boolean, default false. size: auto (default), 1K, 1.5K or 2K. response_format must be url. Do not send background or optimize_prompt_options.
  • Returns 202 with the same task, auth, model permissions, idempotency and callback contract as generation. Poll GET /api/v3/tasks/:id. result.data contains the base image (z_index 0) and each layer. Use z_index for composition and bounding_box.absolute [left, top, right, bottom] in the output base-image coordinate system; array order is preserved, not a composition guarantee.
  • All images are archived privately before delivery. OCR and layer metadata are preserved. Missing recognition fields mean the supplier did not return them; do not invent text or geometry.
  • The reservation covers max_images at the higher output tier plus the one $0.008 input, multiplied by your account factor. Settlement uses each actual output size, including the base image; unused reservation is released. OCR has no separate surcharge. Choose max_images deliberately to bound the hold.
POST /api/v3/images/layers (Bearer auth and Idempotency-Key required for safe retries)
{
  "model": "dola-seedream-5-5-261028",
  "image": "asset://YOUR_IMAGE_ID",
  "layer_decomposition_options": {"max_images": 10},
  "size": "auto"
}

Recognize rich text while extracting layers

POST /api/v3/images/ocr uses the same layer contract and sets layer_decomposition_options.text_recognition to true. This is a paid Seedream 5.5 layer task, not a separate text-only OCR model.

  • Send image and optionally max_images, size and prompt as for /images/layers. Supplying text_recognition false is rejected. Use a unique Idempotency-Key, save the returned task id, then poll /api/v3/tasks/:id.
  • Read result.data[].text_recognition when present. Its text, lines, boxes, text runs and styles are returned without flattening; layer z_index, bounding_box, size and signed url remain available. No recognized text may be returned for an image without text.
POST /api/v3/images/ocr
{
  "image": "asset://YOUR_IMAGE_ID",
  "layer_decomposition_options": {"max_images": 10},
  "size": "auto"
}

Create an audio task

POST /api/v3/tts/create always returns 202 {"id","status","task"} with a Location header.

  • model: seed-audio-1.0. text_prompt: 1 to 3000 characters.
  • references: optional list; each item has exactly one of speaker (speaker://<id>; public and cloned speakers are not available yet), audio_url, audio_data (raw Base64), image_url or image_data (raw Base64). Up to 3 audio references or 1 image reference, not mixed. Audio references at most 30 s and 10 MiB; images jpeg, png or webp up to 10 MiB.
  • audio_config: format (wav, mp3, pcm or ogg_opus), sample_rate (8000, 16000, 24000 default, 32000, 44100 or 48000), speech_rate and loudness_rate (-50 to 100), pitch_rate (-12 to 12), enable_subtitle.
  • watermark: {"aigc_watermark": bool, "aigc_metadata": {"enable", "content_producer", "produce_id", "content_propagator", "propagate_id"}}.
  • When succeeded, result.url is a signed link to the archived audio. result also keeps the provider fields, including its Base64 audio; prefer result.url.

Seedance 2.5 Draft to Final

  • Draft: send "draft": true with model dreamina-seedance-2-5-260628 and resolution 480p.
  • Final: a new request whose content is exactly one {"type":"draft_task","draft_task":{"id":"<the Draft task id from this API>"}}. Its resolution defaults to and must be 1080p; do not send duration, ratio, generate_audio, omni_reference_task_type or draft.
  • The Draft must be your own succeeded Draft whose duration is known. It stays usable for 14 days after creation (7 days for Drafts created before 2026-10-28 10:00 UTC+8), even after its media retention ends.
  • Draft and Final are two tasks, each billed from its own actual usage.
Final request
{
  "model": "dreamina-seedance-2-5-260628",
  "content": [{"type": "draft_task", "draft_task": {"id": "5d0f7c1e-6a2b-4e8f-9b3c-2a1d4e5f6a7b"}}]
}

Tasks & delivery

The task object and statuses

GET /api/v3/tasks/:id returns {"success":true,"data":<task>} for every kind, and the 202 create response for image and audio carries the same object as task. Use it to bill your own users.

  • status: queued, running, succeeded, failed, cancelled (video), expired or unknown. failed, cancelled and expired are terminal; succeeded is final for the generation but later becomes expired when its 72-hour retention ends, with billing unchanged (the native video query then answers 410 MEDIA_EXPIRED). unknown is not terminal: the outcome is being reconciled by the operator, so keep polling and do not resubmit; it ends as succeeded (then billed as below) or failed (released).
  • generation_status: queued, sending, submitted, running, succeeded, failed or unknown (the generation itself).
  • billing_status: reserved (funds frozen), pending (funds frozen while usage is verified), settled (charged; actual_usd is set), released (hold returned, nothing charged), refunded (a settled charge was returned).
  • storage_status: pending, archiving, retry, ready (links work), failed (could not be archived), expired or purged (past the 72-hour retention).
  • When a charge is final: once status is succeeded and billing_status is settled, actual_usd never changes again; charge your user that amount. A settled charge is refunded only if archiving fails, which can happen only before status reaches succeeded (it then ends failed with MEDIA_ARCHIVE_FAILED).
  • Every failure, cancellation, ServerOverloaded and TASK_EXPIRED ends with billing_status released: nothing was charged. MEDIA_ARCHIVE_FAILED ends refunded when it had already been settled, otherwise released. Neither costs you anything.
  • Unsettled means frozen: while billing_status is reserved or pending, or status is unknown, reserved_usd stays frozen in your wallet. It is neither charged nor available to spend, and it can stay frozen until the operator reconciles the task. Freeze the same amount for your own user: do not charge it and do not return it until the task settles (charge actual_usd) or is released (return it all).
  • pending means the output exists but BytePlus usage is still being verified. succeeded can arrive while billing is still pending, and no callback is sent when billing later settles, so poll GET /api/v3/tasks/:id until billing_status is settled, or released if the usage cannot be verified.
  • reserved_usd is the amount currently frozen for the task (0 once it settles or is released); initial_reservation_usd is the amount frozen at acceptance.
  • error_code and error_message explain failures, for example ServerOverloaded (not sent within 30 minutes), TASK_EXPIRED (BytePlus did not run it within execution_expires_after), MEDIA_ARCHIVE_FAILED (output could not be stored), CANCELLED, PROHIBITED_CONTENT, or a ModelArk code such as OutputVideoSensitiveContentDetected.
  • usage: video {completion_tokens, duration}; image {image_count, image_sizes}; audio {original_duration, duration}. price_snapshot is the price row locked at acceptance.
  • artifacts: one entry per archived output with id, kind, url, mime_type, format, byte_size, width, height, duration_seconds, verified, expires_at and link_expires_at. Links last up to one hour; query again to refresh them. Media is kept 72 hours.
  • trace: your idempotency_key, our task_id and request_id, and the BytePlus task, request and log IDs. GET /api/v3/tasks?q=<any of these> finds the task.
GET /api/v3/tasks/:id (succeeded video, abridged)
{
  "success": true,
  "data": {
    "id": "0a443c53-5cc3-41c0-8a5d-f4ac310ae216",
    "kind": "video",
    "model": "dreamina-seedance-2-0-mini-260615",
    "status": "succeeded",
    "generation_status": "succeeded",
    "billing_status": "settled",
    "storage_status": "ready",
    "actual_usd": "0.1562869",
    "reserved_usd": "0",
    "initial_reservation_usd": "0.33",
    "usage": {"completion_tokens": 40594, "duration": 4},
    "error_code": "",
    "artifacts": [{"id": "...", "kind": "video", "url": "https://...signed...", "mime_type": "video/mp4", "duration_seconds": "4.041667", "link_expires_at": "2026-10-30T15:30:00Z", "expires_at": "2026-11-02T14:21:03Z"}],
    "trace": {"task_id": "0a443c53-...", "request_id": "...", "idempotency_key": "order-1842-video", "upstream": {"provider": "byteplus", "task_id": "amk-...", "request_id": "...", "log_id": "...", "client_request_id": "0a443c53-..."}},
    "created_at": "2026-10-30T14:21:03Z"
  }
}

Native video query and list

  • GET /api/v3/contents/generations/tasks/:id returns the Ark body. When the output is archived it is the BytePlus result with content.video_url (and content.last_frame_url when requested) replaced by signed links, plus generation_status, billing_status, storage_status and trace.
  • status stays running until the video is archived, so a client that waits for succeeded can always download. A failure is {"status":"failed","error":{"code":"...","message":"..."}} in the same body, for example error.code MEDIA_ARCHIVE_FAILED when archiving is impossible. unknown means the outcome is being reconciled.
  • GET /api/v3/contents/generations/tasks lists your videos: page_num and page_size (1 to 500, defaults 1 and 20), filter.status (queued, running, succeeded, failed, cancelled, unknown), filter.task_ids (repeat, up to 500), filter.model, filter.service_tier (default only). Returns {"items":[...],"total":n}.
  • GET /api/v3/tasks lists every kind: offset (default 0) and limit (default 50, max 100), q for an exact identifier. Returns {"success":true,"data":{"items":[...],"total":n}}.

Callbacks

  • Add callback_url (public HTTPS on port 443, at most 2048 characters, no credentials or private addresses) to any create request.
  • You receive a POST on each status change to queued, running, succeeded, failed, cancelled or expired. unknown is never sent. succeeded is sent only after the output is archived.
  • Body: for video, exactly what the native video query returns at that moment; for image and audio, exactly the GET /api/v3/tasks/:id body ({"success":true,"data":...}).
  • Headers: X-JMovie-Event-Id (<task_id>:<status>, use it to deduplicate), X-JMovie-Timestamp (Unix seconds), X-JMovie-Signature (v1=<hex>), User-Agent JMovie-API-Callback/1.
  • Signature: v1= hex(HMAC-SHA256(key, timestamp + "." + raw body)), where key is the lowercase hex SHA-256 of the API Key that created the task, used as its ASCII text. Compare in constant time and reject timestamps older than a few minutes.
  • Answer any 2xx within 5 seconds. Redirects are not followed. A failed delivery is retried after 5, 15 and 45 seconds, each attempt re-signed with a new timestamp, then that status is dropped. Order is not guaranteed and billing changes send no callback; polling remains the source of truth.
Python
import hashlib, hmac, time

def verify(api_key: str, headers: dict, body: bytes) -> bool:
    key = hashlib.sha256(api_key.encode()).hexdigest().encode()
    ts = headers["X-JMovie-Timestamp"]
    if abs(time.time() - int(ts)) > 300:
        return False
    expected = "v1=" + hmac.new(key, ts.encode() + b"." + body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, headers["X-JMovie-Signature"])
Node.js
import { createHash, createHmac, timingSafeEqual } from 'node:crypto'

export function verify(apiKey, headers, rawBody) {
  const key = createHash('sha256').update(apiKey).digest('hex')
  const ts = headers['x-jmovie-timestamp']
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false
  const expected = 'v1=' + createHmac('sha256', key).update(ts + '.').update(rawBody).digest('hex')
  const got = headers['x-jmovie-signature'] ?? ''
  return got.length === expected.length && timingSafeEqual(Buffer.from(got), Buffer.from(expected))
}

Idempotency and retries

  • Idempotency-Key: optional, at most 128 characters, unique per account (shared by all its Keys). A key is never reusable, even after the task is deleted.
  • Repeating the same key with the same JSON (key order and whitespace do not matter) returns the original task with the original status code and Idempotent-Replayed: true; it is not charged again. The same key with a different body (callback_url included) or kind returns 409 with code IDEMPOTENCY_CONFLICT (Ark error.code IdempotencyKeyConflict). Two simultaneous requests with one key create one task.
  • Without the header every request is a new paid task, and trace.idempotency_key is empty.
  • Use the top-level error code to decide recovery. A timeout, proxy error, HTTP 5xx or failed retry does not prove that an earlier attempt created no task. Keep the original path, payload and Idempotency-Key; query the saved task or recover the create with those same values. Never use a new key merely because the outcome is uncertain.
  • BytePlus submission is protected too: the task ID is sent as the supplier client token, so a lost supplier response is re-sent without a second generation.

Rate limits and concurrency

  • Every authenticated response carries X-RateLimit-Limit (burst of the tightest bucket), X-RateLimit-Remaining (whole requests left) and X-RateLimit-Reset (seconds until it is full). A 429 also carries Retry-After in seconds.
  • Defaults per Key: 180 creates/min, i.e. 3/s (burst 15), and 600 queries/min, i.e. 10/s (burst 40). Per account: 300 creates/min, 5/s (burst 30), and 2400 queries/min, 40/s (burst 120). Your administrator can change these; replays count as queries. Each Key also limits how many of its tasks run at once; KEY_CONCURRENCY_EXCEEDED means wait for one to finish.
  • 429 RATE_LIMIT_EXCEEDED: wait Retry-After. 429 KEY_CONCURRENCY_EXCEEDED: too many of this Key's tasks are running; retry when one finishes. 429 KEY_LIMIT_EXCEEDED: the Key budget is spent; do not retry.
  • A per-IP guard also returns 429 with an empty body and Retry-After when one address sends more than 360 requests in 180 seconds; nothing was accepted. Wait Retry-After, then resend with the same Idempotency-Key.
  • During supplier capacity peaks a task waits in status queued; it fails with ServerOverloaded and is not charged if it cannot be sent within 30 minutes.

Error codes

Top-level code, HTTP status, Ark error.code, and whether to retry.

  • INVALID_API_KEY 401 AuthenticationError: no. ACCOUNT_DISABLED, KEY_OR_ACCOUNT_DENIED 403 AccessDenied (inactive Key or model not allowed): no.
  • INSUFFICIENT_BALANCE 402 AccountOverdueError: after funding. KEY_LIMIT_EXCEEDED 429 AccountQuotaExceeded: no. ASSET_QUOTA_EXCEEDED 403 AccountQuotaExceeded (library full): after deleting assets.
  • RATE_LIMIT_EXCEEDED 429 AccountRateLimitExceeded and KEY_CONCURRENCY_EXCEEDED 429 ModelAccountConcurrentRequestsLimitExceeded: yes, later.
  • INVALID_REQUEST, INVALID_REFERENCE, INVALID_CALLBACK_URL, INVALID_IDEMPOTENCY_KEY, UNSUPPORTED_REQUEST, TOKEN_ESTIMATE_TOO_LARGE, INVALID_FILTER, INVALID_PAGINATION, UNSUPPORTED_FILTER 400 InvalidParameter: no, fix the request. REQUEST_TOO_LARGE and MEDIA_TOO_LARGE 413: no.
  • IDEMPOTENCY_CONFLICT 409 IdempotencyKeyConflict: no. NOT_FOUND 404 ResourceNotFound: no. MEDIA_EXPIRED 410 ResourceExpired: no, the 72-hour retention ended.
  • TASK_NOT_QUEUED 409 OperationDenied.InvalidState: no, the task can no longer be cancelled. TASK_ALREADY_CANCELLED 409: no. CANCELLATION_UNCONFIRMED and BILLING_PENDING 409 OperationDenied.InvalidState: retry later. OUTPUT_NOT_AVAILABLE 404 ResourceNotFound: the output is not archived or past retention.
  • INTERNAL_ERROR, REFERENCE_SERVICE_UNAVAILABLE, SIGN_FAILED, STORAGE_UNAVAILABLE, DELETE_PENDING 5xx InternalServiceError: yes, with the same Idempotency-Key for creates. GENERATION_UNAVAILABLE 503 InternalServiceError: generation is paused by the operator; nothing was accepted.
  • Generation failures from BytePlus (for example SensitiveContentDetected) appear on the task as error_code with status failed, not as an HTTP error.

Cancel and delete

  • POST /api/v3/contents/generations/tasks/:id/cancel works only for videos still queued in this API. They are cancelled and fully released: {"success":true,"data":{"id":"...","status":"cancelled"}}.
  • Once a video has been sent to BytePlus it cannot be cancelled: 409 TASK_NOT_QUEUED. While a send is in flight or its outcome is unknown: 409 CANCELLATION_UNCONFIRMED.
  • Image and audio tasks cannot be cancelled.
  • DELETE /api/v3/contents/generations/tasks/:id cancels a queued video, or removes a finished one and its media from listings. Billing records are kept; deleting never reverses a charge. 409 TASK_ALREADY_CANCELLED or BILLING_PENDING when it does not apply yet.

Reference assets

Image, video and audio inputs

A media item is {"type":"image_url","image_url":{"url":"..."},"role":"..."}; video_url and audio_url have the same shape. text and draft_task items take no role.

  • Image roles: first_frame (default), last_frame, reference_image. A last_frame needs a first_frame, and frame images cannot be mixed with reference media. On 2.5 and 2.5 Flash, frame images require ratio adaptive.
  • Video items must use role reference_video; audio items must use role reference_audio.
  • At most 9 reference images, 3 videos and 3 audios per request (30, 10 and 10 on Seedance 2.5; 10, 5 and 5 on 2.5 Flash). Flash allows up to 30 seconds of total video and 30 seconds of total audio.
  • Images: at most 30 MiB, 300 to 6000 px per side, aspect ratio 0.4 to 2.5, jpeg, png or webp. Videos: mp4 or mov, at most 200 MiB, 2 to 15 s (30 s on 2.5 and 2.5 Flash), 24 to 60 fps. Audio: wav or mp3, at most 15 MiB.
  • url accepts asset://<asset id> from your library, a public https:// URL (downloaded and checked before submission), or for images and audio a data:<mime>;base64,<data> URI. Videos cannot be Base64. The whole request body is capped at 64 MiB.
Reference image plus a library reference video
"content": [
  {"type": "text", "text": "The character in Image 1 walks into the scene of Video 1."},
  {"type": "image_url", "image_url": {"url": "asset://71fbf5ab-8856-4759-a568-cbcef98340e4"}, "role": "reference_image"},
  {"type": "video_url", "video_url": {"url": "asset://9c2d6a5e-1f0b-4c33-8a8e-3d7f0b1c2e44"}, "role": "reference_video"}
]

Asset library API

  • POST /api/v3/assets: multipart form with file, kind (image, video or audio), optional name and group_id. Images jpeg, png or webp up to 30 MiB; audio wav, mp3 or ogg_opus up to 15 MiB; video mp4 or mov; any file up to 256 MiB and 600 s. These are storage limits: each model's input limits above are checked when a task uses the asset.
  • POST /api/v3/assets/import: {"kind","url","name","group_id"} with a public HTTPS url. Returns 202 with status importing; poll GET /api/v3/assets until active or failed (failure_reason).
  • POST /api/v3/assets/from-task: {"task_id","artifact_id"?,"name"?,"group_id"?} saves an output as an independent permanent copy before its 72-hour retention ends. A task output referenced directly must stay retained for execution_expires_after plus 15 minutes, otherwise the request is refused with INVALID_REFERENCE; a saved library copy has no such limit.
  • GET /api/v3/assets: status (active default, importing, failed or all), kind, group_id, created_from and created_to (YYYY-MM-DD), q (name contains), offset, limit. Returns items (each with id, reference asset://<id>, kind, name, status, byte_size, width, height, duration_seconds, created_at) and usage {count, bytes, quota_count, quota_bytes}.
  • GET /api/v3/assets/:id returns {asset, url, link_expires_at}. PATCH /api/v3/assets/:id takes {name?, group_id?}. DELETE /api/v3/assets/:id returns {deleted:true}; the stored file is removed 72 hours and 15 minutes later, so tasks already running keep working.
  • Asset groups: GET, POST {name} and PATCH /api/v3/asset-groups[/:id] {name}, DELETE /api/v3/asset-groups/:id (its assets become ungrouped). Up to 500 groups.
  • Default quota: 1000 assets and 20 GiB per account; above it uploads return 403 ASSET_QUOTA_EXCEEDED.

Funding & balance

Billing API: authenticate and automate

Create a Billing Key in Console → API keys. Query balance → create a BSC order → pay once from your wallet → poll the order → reconcile the ledger.

MethodPathPurpose
GET/balanceWallet snapshot
GET/payment-methodsNetwork and checkout availability
POST/topupsCreate or replay a payment order
GET/topups/{id}Check payment and credit
GET/topupsRecover and list orders
GET/ledgerReconcile credits and usage
Python · pip install requests; set JMOVIE_BILLING_KEY and a persistent JMOVIE_TOPUP_REQUEST_ID
import os
import time
import requests

BASE = "https://api.j-movie.com/api/v3/billing"
HEADERS = {"Authorization": f"Bearer {os.environ['JMOVIE_BILLING_KEY']}"}

def billing(method, path, *, payload=None, idempotency_key=None):
    headers = dict(HEADERS)
    if idempotency_key:
        headers["Idempotency-Key"] = idempotency_key
    response = requests.request(
        method, BASE + path, headers=headers, json=payload,
        timeout=(10, 30), allow_redirects=False,
    )
    if not 200 <= response.status_code < 300:
        raise RuntimeError(f"Billing HTTP {response.status_code}: {response.text}")
    return response.json()["data"]

def wait_for_credit(order_id, timeout=300):
    deadline = time.monotonic() + timeout
    while time.monotonic() < deadline:
        order = billing("GET", f"/topups/{order_id}")
        if order["status"] == "paid":
            return order
        # Even expired orders can credit if the transfer was included in time.
        time.sleep(10)
    raise TimeoutError(f"Credit not yet confirmed. Keep order {order_id}; do not pay again.")

balance = billing("GET", "/balance")
print(balance["spendable_usd"])  # Decimal USD string; use decimal.Decimal for math.

# Persist this ID in your database BEFORE the first POST.
# After a timeout, retry the SAME ID and amount to recover the original order.
order = billing("POST", "/topups", payload={"amount_usd": "100"},
                idempotency_key=os.environ["JMOVIE_TOPUP_REQUEST_ID"])
print(order["id"], order["status"])
if order["status"] == "awaiting_payment":
    print(order["chain_id"], order["token_contract"],
          order["receiving_address"], order["transfer_usdt"])
# Your wallet/treasury sends the exact amount once. Save its transaction hash.
# Replaying a POST is safe; repeating a blockchain transfer is NOT.

status = billing("GET", f"/topups/{order['id']}")
print(status["status"])
# After your wallet sends the payment, call wait_for_credit(order["id"]).
print(billing("GET", "/ledger?limit=20"))
  • In Console → API keys → Create Key, choose Billing: read only or Billing: read and create top-ups. Use that Key as Authorization: Bearer <Billing Key>. Creating and revoking Keys requires a recent sign-in.
  • Ordinary generation Keys cannot access billing. Billing Keys cannot generate content or manage assets. Zero balance, exhausted generation budgets and paused generation do not block billing; disabled accounts and expired/revoked Keys are rejected.
  • Base URL: https://api.j-movie.com/api/v3/billing. Success: {"success":true,"data":...}. Errors use the same top-level code and error object as other /api/v3 endpoints. Money and ledger IDs are strings. All responses are no-store; retain X-Request-Id for support.

GET /billing/balance

No parameters. Requires either Billing Key permission. Does not charge the account.

FieldTypeMeaning
balance_usddecimal stringPosted wallet balance.
reserved_usddecimal stringFunds held by unresolved tasks.
available_usddecimal stringbalance − reserved; may be negative.
spendable_usddecimal stringmax(available, 0).
debt_usddecimal stringmax(−balance, 0).
ledger_cursorstringLatest ledger ID in the same consistent snapshot.
as_ofUTC timestampSnapshot time.
200 response
{
  "success": true,
  "data": {
    "currency": "USD",
    "balance_usd": "800.000000000",
    "reserved_usd": "50.000000000",
    "available_usd": "750.000000000",
    "spendable_usd": "750.000000000",
    "debt_usd": "0.000000000",
    "as_of": "2026-11-17T15:00:00Z",
    "ledger_cursor": "184"
  }
}
  • A snapshot does not reserve funds for a new generation. Top-ups do not reset Key budgets or release task holds.

GET /billing/payment-methods

No parameters. Check availability before creating a new order. Always pay using the returned order values.

200 response
{
  "success": true,
  "data": {
    "items": [
      {
        "id": "bsc_usdt",
        "network": "BSC",
        "chain_id": 56,
        "token": "USDT",
        "token_contract": "0x55d398326f99059ff775485246999027b3197955",
        "token_decimals": 18,
        "available": true,
        "min_amount_usd": "30",
        "max_amount_usd": "100000",
        "amount_decimal_places": 2,
        "transfer_decimal_places": 6,
        "payment_window_seconds": 1800
      }
    ]
  }
}

POST /billing/topups

Requires Billing: read and create top-ups. Creates payment instructions; creating an order does not move funds or credit the balance.

ParameterLocation / typeRequirement
Idempotency-Keyheader · stringRequired, 16–128 characters: letters, digits, dot, underscore, colon, hyphen. Persist before POST.
amount_usdJSON · stringRequired, 30–100000 USD, at most 2 decimal places. No other body fields; maximum body 1 KiB.
Request JSON
{"amount_usd":"100"}
201 created / 200 replayed
{
  "success": true,
  "data": {
    "id": "e91c6c7e-7d8f-4b6e-b2a2-40058806a670",
    "payment_method": "bsc_usdt",
    "status": "awaiting_payment",
    "amount_usd": "100",
    "transfer_usdt": "100.003217",
    "receiving_address": "<use the address returned by your order>",
    "chain_id": 56,
    "token": "USDT",
    "token_contract": "0x55d398326f99059ff775485246999027b3197955",
    "created_at": "2026-11-17T15:00:01Z",
    "expires_at": "2026-11-17T15:30:00Z",
    "paid_at": null,
    "tx_hash": ""
  }
}
  • Content-Type: application/json. Idempotency is permanent and account-wide across Billing Key rotation. Same key and amount returns the original order, including paid or expired orders; a changed amount returns 409 IDEMPOTENCY_CONFLICT. Idempotency-Replayed and Location headers identify the result.
  • One open unpaid order per account. A different request key while an order is open returns 409 ORDER_PENDING, including for the same amount. Recover it with GET /topups. After a timeout, retry the original key and amount; never invent a replacement payment.
  • New orders require a healthy chain scanner; otherwise 503 BSC_UNAVAILABLE. Replays remain readable during checkout outages. POST is limited to 6 requests/minute per account, burst 2; normal Key/account query limits also apply. Honor 429 Retry-After.

GET /billing/topups/{id}

Requires either Billing Key permission. Returns the same order object as creation. Unknown and other-account IDs both return 404 NOT_FOUND.

StatusMeaningClient action
awaiting_paymentNo matched finalized credit yet.Pay only if your wallet has not already sent this order; otherwise keep polling.
paidThe verified transfer was credited.Reconcile amount_usd and tx_hash with the ledger.
expiredPayment window ended; no credit yet.If already sent, keep the original ID and transaction hash; do not pay again. A transfer included in time may credit later.
200 paid response
{
  "success": true,
  "data": {
    "id": "e91c6c7e-7d8f-4b6e-b2a2-40058806a670",
    "payment_method": "bsc_usdt",
    "status": "paid",
    "amount_usd": "100",
    "transfer_usdt": "100.003217",
    "receiving_address": "<use the address returned by your order>",
    "chain_id": 56,
    "token": "USDT",
    "token_contract": "0x55d398326f99059ff775485246999027b3197955",
    "created_at": "2026-11-17T15:00:01Z",
    "expires_at": "2026-11-17T15:30:00Z",
    "paid_at": "2026-11-17T15:05:00Z",
    "tx_hash": "0x<verified transaction hash>"
  }
}
  • Poll every 10 seconds with a bounded client timeout. A timeout is not a failed payment. Resume with the same order ID. Payment webhooks are not provided; generation callbacks do not report top-ups.

GET /billing/topups

Lists only your account’s orders, newest first. Useful for recovering an order created through either the API or console.

QueryTypeUsage
limitinteger · optional1–100; default 20.
beforestring · optionalUse next_cursor from the previous response. Stop when next_cursor is null.
200 response
{
  "success": true,
  "data": {
    "items": [
      {
        "id": "e91c6c7e-7d8f-4b6e-b2a2-40058806a670",
        "payment_method": "bsc_usdt",
        "status": "awaiting_payment",
        "amount_usd": "100",
        "transfer_usdt": "100.003217",
        "receiving_address": "<use the address returned by your order>",
        "chain_id": 56,
        "token": "USDT",
        "token_contract": "0x55d398326f99059ff775485246999027b3197955",
        "created_at": "2026-11-17T15:00:01Z",
        "expires_at": "2026-11-17T15:30:00Z",
        "paid_at": null,
        "tx_hash": ""
      }
    ],
    "next_cursor": null
  }
}

GET /billing/ledger

Lists your account’s immutable credits, reservations, settlements and reversals, newest first. Requires either Billing Key permission.

QueryTypeUsage
limitinteger · optional1–100; default 20.
beforestring · optionalUse next_cursor from the previous response. Stop when next_cursor is null.
200 response
{
  "success": true,
  "data": {
    "items": [
      {
        "id": "184",
        "type": "credit",
        "task_id": "",
        "amount_usd": "100",
        "reserve_delta_usd": "0",
        "balance_after_usd": "800",
        "reserved_after_usd": "50",
        "tx_hash": "0x<verified transaction hash>",
        "reversal_of": "0",
        "created_at": "2026-11-17T15:05:00Z"
      }
    ],
    "next_cursor": null
  }
}
  • Use ledger id to deduplicate; reversal_of is the original ledger ID, or "0". Positive credit amounts are funds added; reserve_delta_usd describes changes to task holds. Internal operator IDs, notes and private receipts are not exposed.

Payment rules and errors

HTTP / codeMeaningAction
401 INVALID_API_KEYMissing, expired or revoked credentialUse an active Billing Key.
403 BILLING_SCOPE_REQUIREDWrong Key purpose or read-only Key used to createCreate a Key with the required billing permission.
400 INVALID_AMOUNT / INVALID_IDEMPOTENCY_KEYInvalid requestCorrect input before retrying.
409 IDEMPOTENCY_CONFLICTRequest key was bound to a different amountRecover the original request; do not pay twice.
409 ORDER_PENDINGAn open order existsGET /topups to recover it.
429 RATE_LIMIT_EXCEEDEDRequest limit exceededWait Retry-After, reuse the same request key.
503 BSC_UNAVAILABLENew checkout unavailableWait; existing orders remain queryable.
  • BSC mainnet only (chain 56), using the exact USDT contract returned by the order. Transfer the exact transfer_usdt once; keep gas separate. A 100.003217 USDT quote credits 100 USD. The suffix identifies the order.
  • The transfer must be included in a block before expires_at, not merely broadcast. Finalized chain validation checks contract, receiver, receipt, amount and time. Clients cannot mark an order paid or submit a balance.
  • Wrong network/token/address, split payments, wrong amounts, duplicate transfers or late inclusion need support review. Keep order ID and transaction hash. Never resend simply to fix an unresolved status.

Capability guides

Seedance video

POST /api/v3/contents/generations/tasks
  • Models: Seedance 2.0, 2.0 Fast, 2.0 Mini, 2.5 and 2.5 Flash. Send content with one text prompt and optional image_url, video_url or audio_url references (your uploads or asset:// resources).
  • Defaults: resolution 720p, ratio adaptive, duration 5 seconds. 4k is available on Seedance 2.5 and 2.0. draft is available on Seedance 2.5 at 480p. Flash supports 480p/720p and 4 to 30 seconds, without Draft/Final. Optional callback_url receives signed status updates.
  • The response returns the task id. Query GET /api/v3/contents/generations/tasks/:id until status is succeeded, failed, cancelled or expired (unknown is not final: keep polling); content.video_url appears once the output is archived.

Results are not permanent: files are kept for 72 hours from generation and each signed link lasts up to 1 hour. Save results to your own storage promptly.

Troubleshooting

Status stays running after generation_status is succeeded
The output is being archived. Keep polling; it usually completes within seconds.
Status failed with MEDIA_ARCHIVE_FAILED
The output could not be stored before the supplier link expired. Its charge is refunded in full automatically.
InvalidParameter.TaskTypeConstraint on Seedance 2.5
Edit, extend and first-frame tasks need a matching ratio and duration. The gateway checks most of these before accepting; BytePlus may reject the rest later, and the task then fails without charge.
InvalidParameter on a reference
Check that the reference belongs to your account, has a supported format and stays retained for the execution window.

Seedream images

POST /api/v3/images/generations
  • Models dola-seedream-5-5-261028 and dola-seedream-5-0-pro-260628 with a prompt, optional image references, size (default 2K), response_format url or b64_json and output_format png or jpeg. Regular generation returns one image. Seedream 5.5 also offers /api/v3/images/layers and /api/v3/images/ocr for a single input image; see their reference below for limits and per-layer billing.
  • Creation is asynchronous: it returns 202 with the task id and a Location header. Query GET /api/v3/tasks/:id until status is succeeded; its result field holds the Ark image response (data[].url or data[].b64_json) and artifacts holds the signed links.
  • Send an Idempotency-Key: if the create request times out before you receive the task id, retrying with the same key returns the same task without paying twice.

Results are not permanent: files are kept for 72 hours from generation and each signed link lasts up to 1 hour. Save results to your own storage promptly.

Troubleshooting

Timeout without a response
Retry with the same Idempotency-Key, or find the task in your task list.
Status unknown
The supplier outcome could not be confirmed; the reservation is held for reconciliation. Do not resend with a new key.
SensitiveContentDetected or another supplier code
The supplier rejected the input. Nothing was charged; change the prompt or references.

Seed Audio

POST /api/v3/tts/create
  • Model seed-audio-1.0 with text_prompt, optional references (audio, or a single image) and audio_config for format and sample rate.
  • Creation is asynchronous: poll GET /api/v3/tasks/:id until status is succeeded; its result field holds the audio output. Billing uses the actual original_duration in seconds.

Results are not permanent: files are kept for 72 hours from generation and each signed link lasts up to 1 hour. Save results to your own storage promptly.

Troubleshooting

Raw PCM cannot be used as a reference
Request a container format such as WAV or MP3 if you plan to reuse the audio.
Audio and image references rejected together
Seed Audio accepts audio references or a single image reference, not both.

Asset library

POST /api/v3/assets · POST /api/v3/assets/import · POST /api/v3/assets/from-task
  • Ordinary images, videos and audio are stored by JMovie API until you delete them, and are referenced in generation requests as asset://<id>. At generation time the gateway sends the supplier a signed link that covers the execution window.
  • Upload a file with multipart kind and file (optional name and group_id), import from a public HTTPS URL, or save a generated output with task_id before its 72-hour retention ends. URL import is asynchronous: it returns 202 with status importing, then active or failed with failure_reason.
  • Organize assets with /api/v3/asset-groups and filter GET /api/v3/assets by group_id, kind and status. Each account has a quota, by default 1,000 assets and 20 GiB; inline references inside a generation request do not count.
  • Deleting an asset removes it from the library and from new requests at once. Tasks already accepted can still use it; the file itself is removed 72 hours and 15 minutes later.
  • Faces of real people are not ordinary assets: they need the Real-human library and the portrait verification flow described below.

Troubleshooting

AccountQuotaExceeded on upload, import or save
Delete assets you no longer need, or ask your account manager to raise the quota.
Import stays failed
Read failure_reason: the URL must be public HTTPS on port 443 and return a supported format within the size limit.
OUTPUT_NOT_AVAILABLE when saving a result
The output is past its 72-hour retention or not archived yet. Save results soon after they succeed.

Integration best practices

Retries and idempotency

  • Idempotency-Key is optional: without it every request creates a new task. We recommend sending one on every create. A client whose create request times out has no task ID; retrying with the same key returns the same task instead of paying twice. Always retry with the same key, never a new one.
  • Idempotency is account-wide: a retry through another Key of the same account returns the original task and is never charged twice. The same key with different request content returns 409 with error.code IdempotencyKeyConflict.
  • After a timeout or lost response, resend the same request with the same Idempotency-Key or query the task ID. Without a key a resend is a new paid task, so check your task list first.

Polling

  • Every create request (video, image and audio) accepts callback_url (public HTTPS, port 443). On every status change the gateway POSTs the same body as the matching task query; the succeeded callback is sent only after the output is archived, so its links work. A callback without a 2xx response within 5 seconds is retried three times. Verify X-JMovie-Signature, which is v1= followed by the hex HMAC-SHA256 of X-JMovie-Timestamp, a dot and the raw body, keyed with the hex SHA-256 of your API Key. Polling remains the source of truth.
  • All creation is asynchronous. Poll image and audio tasks every 1 to 2 seconds; they usually finish within seconds. For video, poll every 2 to 3 seconds for the first 30 seconds, then every 5 to 10 seconds. Or use callback_url. The gateway checks the supplier about every 2 seconds, so polling faster does not finish sooner.
  • During peaks a task can stay queued while BytePlus capacity for its model is full; it is sent automatically as capacity frees up. A task not sent within 30 minutes of acceptance fails with ServerOverloaded and is not charged.
  • Native video status stays running until the output is archived and downloadable. If archiving cannot complete before the supplier link expires, status becomes failed with MEDIA_ARCHIVE_FAILED while generation_status remains succeeded, and the charge is refunded in full automatically.

Results and storage

  • Use media only after storage_status is ready. Files are retained for 72 hours from generation; copy them to your own storage within that window.
  • Each signed link is valid for up to 1 hour. Do not store links long-term; query the task again to get a fresh link. After 72 hours, retrieval returns 410 MEDIA_EXPIRED and the media cannot be regenerated by replaying the request.

References

  • Use your own uploaded assets or verified portrait resources by their asset:// reference. A reference used by a video task must remain retained for the whole supplier execution window, execution_expires_after (default 48 hours) plus 15 minutes; a reference that would expire sooner is rejected.
  • A Draft can be turned into a final video for 14 days after it is created (7 days for Drafts created before 2026-10-28 10:00 UTC+8), even after its media retention ends.

Reconciliation

Store for every task: the platform task_id, the X-Request-Id response header, your Idempotency-Key and the trace object with the BytePlus upstream task_id, request_id and log_id. These identify the task in our records and in the supplier bill.

Limits and errors

Requests are limited by token buckets per Key and per account, with one bucket for paid creation (video, image and audio create requests) and another for everything else, such as polling. Replaying an accepted Idempotency-Key counts as a query. Defaults per Key are 3 creates/s (burst 15) and 10 queries/s (burst 40); per account 5 creates/s (burst 30) and 40 queries/s (burst 120). Your actual limits are shown in the console. A platform-wide creation limit can also apply at peaks. Responses carry X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. Each Key also has a concurrency limit and optional budgets.

POST /contents/generations/tasks · /images/generations · /images/layers · /images/ocr · /tts/create
Create bucket: per Key 3/s, burst 15; per account 5/s, burst 30.
All other /api/v3 requests
Query bucket: per Key 10/s, burst 40; per account 40/s, burst 120.

Errors on /api/v3 use the Ark envelope error.code, error.message, error.param and error.type, with the ModelArk code where one exists; our own code is also in the top-level code field. A successful create returns the task id; follow its status. A timeout, proxy error, HTTP 5xx or failed retry does not prove that an earlier attempt created no task. Keep the original Idempotency-Key and payload, recover the task and reconcile its billing state.

400 InvalidParameter
Invalid request or parameters. Fix the request; do not retry unchanged.
401 AuthenticationError
Check the Bearer Key; it may be revoked or expired.
402 AccountOverdueError
Available funds cannot cover the reservation. Pause new submissions and fund your active account through the Billing API or Console → Billing with BSC USDT; contact support if checkout is unavailable.
403 AccessDenied
The Key, account or model is not permitted.
409 IdempotencyKeyConflict
The Idempotency-Key was already used with different content. Use the original content or a new key for a new task.
410 ResourceExpired
The 72-hour retention ended. Task and billing records remain queryable.
429
AccountRateLimitExceeded: wait for Retry-After, then retry with exponential backoff and jitter. ModelAccountConcurrentRequestsLimitExceeded: Key concurrency reached; retry after running tasks finish. AccountQuotaExceeded: Key budget reached; ask for a budget change.
500 / 503 InternalServiceError
Temporary service condition. Retry the same request with the same Idempotency-Key after a backoff.

For resellers and relays

  • Pass a stable Idempotency-Key derived from your own request ID, so failover across your Keys never creates a second paid task.
  • Record the trace fields beside your own order for monthly reconciliation, and return only our signed links, never cached copies older than 1 hour.
  • Plan request rates and concurrency across all your Keys: account limits apply on top of each Key’s limits, so adding Keys does not raise the account ceiling. Spread traffic and back off on 429 instead of retrying immediately.

Endpoint index

GET/api/v3/billing/balanceQuery account balance with a Billing Key
GET/api/v3/billing/payment-methodsCheck BSC checkout availability
POST/api/v3/billing/topupsCreate an idempotent BSC USDT top-up order
GET/api/v3/billing/topups/:idQuery top-up payment and credit status
GET/api/v3/billing/topupsList your top-up history
GET/api/v3/billing/ledgerQuery your account ledger
POST/api/v3/contents/generations/tasksCreate a video task
GET/api/v3/contents/generations/tasks/:idQuery a video task
GET/api/v3/contents/generations/tasksList your video tasks
POST/api/v3/contents/generations/tasks/:id/cancelRequest cancellation of a video task
DELETE/api/v3/contents/generations/tasks/:idDelete a video task and retained media
POST/api/v3/images/generationsGenerate one image
POST/api/v3/images/layersDecompose a Seedream 5.5 image into layers
POST/api/v3/images/ocrExtract layers with rich-text OCR
POST/api/v3/tts/createGenerate Seed Audio
GET/api/v3/tasks/:idQuery unified task states and refresh media links
GET/api/v3/tasksList your video, image and audio tasks
POST/api/v3/assetsUpload a reference asset
POST/api/v3/assets/importImport a reference asset from an allowed remote URL
GET/api/v3/assetsList your reference assets
GET/api/v3/assets/:idQuery an authorized reference asset
DELETE/api/v3/assets/:idDelete your reference asset
GET/api/v3/portrait-verification/sessionsList your people and verification states
POST/api/v3/portrait-verification/sessions/:id/linkResume an unexpired private verification link
POST/api/v3/portrait-verification/sessions/:id/revokeWithdraw portrait use and request supplier group deletion
POST/api/v3/provider-resources/:id/revokeRemove an appearance and request supplier asset deletion
POST/api/v3/portrait-verification/sessionsStart the person's provider verification
GET/api/v3/portrait-verification/sessions/:idQuery your verification session metadata
POST/api/v3/portrait-verification/sessions/:id/refreshConfirm verification with the provider server
POST/api/v3/portrait-assetsRegister a verified person's reference asset
GET/api/v3/provider-resourcesList your registered provider resources
POST/api/v3/provider-resources/:id/refreshCheck the registered asset's current provider status

The native video list accepts page_num and page_size, plus filter.status, filter.task_ids, filter.model and filter.service_tier. Pagination starts at 1; the default page size is 20. filter.status selects the generation state; only the default service tier is supported.

Video list responses contain top-level items and total, with no data envelope. Returned records belong only to your API account.

Native video polling may report status=running with generation_status=succeeded while archiving is in progress. It reports status=succeeded once private media links are ready; billing_status must still be checked independently. Use the unified task endpoint for explicit generation, billing and storage states.

Image and audio creation returns 202 with the task id and a Location header. The unified task endpoint reports status queued, running, succeeded, failed, expired or unknown; when succeeded, result holds the Ark-format output and artifacts holds the signed links.

Reuse of a Draft, edited video, extended video or reference asset is restricted to assets that your API account is permitted to use.

Reference uploads and imports currently support JPEG, PNG and WebP images; MP4 and MOV video; and WAV, MP3 and Ogg (Opus) audio. Real format, dimensions and duration are validated, and each model has its own capability limits. Seed Audio accepts audio references or a single image reference, not both together.

The local verified flag means media checked: it only confirms file checks, storage and API-account ownership. It is not a certification and does not prove supplier portrait authorization. Ordinary Seedream image references and Seed Audio audio or image references follow their own model protocols and provider content policies; they do not share the Seedance portrait-enrollment flow.

Generated PCM audio can be downloaded in its original raw format. Without a trusted audio profile, raw PCM cannot be reused as a reference; use a supported container with verifiable audio metadata instead.

Using faces in Seedance

Seedance 2.0 and 2.5 block ordinary references that contain real human faces. These are the compliant ways to use faces:

  1. Preset digital characters: free characters provided by BytePlus. Use asset://<preset ID> from the preset list in your console.
  2. Private virtual portraits: fictional characters you own, created from your Material library and reviewed by BytePlus before use. They must not resemble any real person.
  3. Your own model outputs: BytePlus trusts original face-containing outputs of Seedance 2.0 and 2.5 and Seedream 5.0 from the same account for 30 days. Whether an output reused through our archived copy keeps that trust is not yet confirmed.
  4. Authorized real people through liveness verification: coming later.

In prompts, refer to references by type and position, such as Image 1, Video 1 or Audio 1, never by asset ID.

Reference formats: images accept a URL, Base64 or asset://; videos accept a URL or asset:// only, not Base64; audio accepts a URL, Base64 or asset://.

BytePlus output links last 24 hours and allow at most 100 downloads. JMovie API archives one copy and gives you signed links instead, so neither limit applies within the 72-hour retention.

Real-person references

Seedance 2.0 and 2.5 do not accept ordinary direct image or video references containing real human faces. An ordinary upload or URL is not proof of portrait authorization. The person shown must complete the official verification and consent process, and each portrait asset must be registered with the provider.

The server must confirm the provider status is Active before an asset can be used as a reference. Assets that are processing, failed, unverified or owned by another API customer cannot be used.

Already authorized real-person assets and provider-approved digital-character (virtual portrait) assets can be assigned to your API account by an administrator, then verified through the independent BytePlus control plane. This requires the same supplier account and project, an Active asset, a matching AIGC or LivenessFace group, exact permitted Seedance models and the source file, either a byte-identical copy you own or one the gateway fetches from BytePlus and keeps in your asset library. A registered portrait stays usable as long as its source asset exists; deleting the source, revoking the resource or a failed BytePlus re-check ends it. A registered ID or operator checkbox alone cannot enable inference. Library verification is unavailable until its independent credentials and project binding have been configured and validated.

Ark library asset IDs are for Seedance video references, not Seedream image references or Seed Audio voice IDs. Public and cloned speaker IDs remain unavailable until their exact supplier catalog or authorization can be verified. Do not use a portrait-library asset as a substitute for voice authorization.

Enrolling new real people through liveness verification is not part of this release; the steps below describe the existing flow, which stays disabled unless your administrator enables it.

Real-human enrollment is available only when the administrator explicitly enables it with independent control-plane credentials, invited access and Advanced Creation Rights. The console shows whether enrollment is configured. The person must complete consent and live verification on BytePlus, not upload biometric captures to JMovie API. Consent is once per person; every new appearance still requires consistency checks and Active status.

  1. Use the Real-human library in your console, or your generation Key for the /api/v3 routes. Session creation and portrait registration require an Idempotency-Key. Start with {"name":"Private person label","consent":true}. The response includes id, status, expires_at and consent_version, with h5_url only in the first response. Keep it confidential and send it only to the subject. GET and list responses never include the credential. POST the session link endpoint with {} to resume an unexpired awaiting-user link.
  2. The person shown opens the official H5 page, reviews the authorization purpose and completes consent and face verification themselves. The callback at /api/jmovie/portrait-verification/callback is only a return path: its resultCode is not proof of authorization.
  3. POST an empty JSON object to the session refresh endpoint. The gateway queries the provider result and checks the real-person asset group on the server. Provider credentials and verification tokens are never returned to your application. Continue only after the server reports status=verified.
  4. Upload or import the reference into your own API account, then POST portrait-assets with session_id, source_asset_id, name, models (exact allowed Seedance IDs) and consent:true. The source must show the verified person and be active and media checked. A registered portrait resource stays valid while its source asset exists and never outlives an earlier source expiry. Provider processing and consistency checks still apply. Poll the resource refresh endpoint with an empty JSON object until status=active, inference_enabled=true and verification_state=provider_verified, corresponding to provider Active.
  5. Use the returned reference, asset:// followed by the local resource UUID, in the matching image_url.url, video_url.url or audio_url.url field of a Seedance request. The gateway checks API-account ownership, provider project, verified group, current status and allowed model before resolving it to the supplier asset. Generation rechecks the provider status, so a revoked asset cannot rely on an earlier active result. Do not replace the local reference with a raw supplier ID or put an asset ID in the text prompt.

The 30-minute deadline applies to the verification link, not an already verified person. Future appearances reuse the verified group. Use image 1 or video 1 in prompts according to input order, not the asset ID itself.

Removal requires {"confirm":true}. Local use is blocked first; supplier deletion is a separate state. An active authorization may prevent group deletion. Unknown or interrupted supplier operations require manual reconciliation, are never automatically repeated and are not reported as deleted. Already submitted generation tasks are not cancelled.

A lost response or timeout during session or asset creation can leave submission_unknown. Query the existing record and request reconciliation; do not automatically resubmit a creation request, do not switch to a new Idempotency-Key to bypass the uncertain result, and do not assume that authorization succeeded. Status queries do not create a new verification session or regenerate an asset.

BytePlus portrait requirements · BytePlus private real-person library protocol

Billing and recovery

Idempotency
The same account, Idempotency-Key and request content return the existing task, through any of the account’s Keys. Different content returns a conflict. Provider request IDs are tracing IDs, not an assumed provider idempotency guarantee.
Separate states
generation_status, billing_status and storage_status are independent. Generation success does not mean verified settlement or completed storage.
Actual usage
Video is settled using actual completion_tokens at the applicable rate per million tokens, not a fixed per-second price. Images use the successful output pixel tier and chargeable reference-image count. Audio uses actual original_duration in seconds, not playback duration after a speed change.
Cancellation and deletion
Only a video still queued in JMovie API can be cancelled, and it is released in full. Once sent to BytePlus it can no longer be cancelled (409 TASK_NOT_QUEUED). Image and audio tasks cannot be cancelled. Deleting a completed result does not reverse its generation bill.
Native video DELETE cancels a queued task or removes a terminal task from native retrieval and listings. Internal actual usage and the financial ledger are retained. A running or unknown request still requires confirmed cancellation or reconciliation; deleting a record is not proof of a refund.
Unknown outcome
A timeout, truncated provider response or worker crash after submission is kept for reconciliation. A lost submission is re-sent only with the same supplier client token, so BytePlus never runs it twice; otherwise we do not resend, change provider or refund an uncertain paid generation.
Missing usage
The reservation remains held until trusted actual usage is available. An estimate is never presented as the actual bill.
Budget month
Monthly Key budgets follow the UTC month in which the task is accepted. Finishing in the next month does not move or lose its reservation.
Debt
If verified usage exceeds the hold and available funds, the debt is recorded and new paid tasks are blocked. Later confirmed funding, including BSC top-ups, clears debt first.

Policies

Generated files and derivatives are retained for 72 hours from generation success. Archive retries, queries and reuse do not extend retention. Task records, actual usage and bills remain available after files expire.

After media expiry, native result retrieval returns HTTP 410 with MEDIA_EXPIRED. Replaying the same paid request does not regenerate expired media. Use the unified task endpoint to inspect retained task and billing records.

Private media is delivered directly from Singapore Spaces using a signed URL valid for up to one hour, never beyond the remaining 72-hour retention window. Query an authorized task to refresh the link while the media is retained. Private signed media is not CDN-cached or CDN-accelerated; the API process does not proxy these downloads.

Uploaded reference inputs have a separate lifecycle; they are not automatically expired under the generated-media rule.

Administrative changes require a browser sign-in within the last 15 minutes. Refreshing an access token does not restart that window, and a personal access token cannot replace browser reauthentication. AUTH_REAUTH_REQUIRED means sign in again before making the change. A rejected operation is not automatically retried.

Provider content policies apply. Errors such as PROHIBITED_CONTENT are returned as recognizable provider codes. We do not bypass supplier restrictions.

Changelog

2026-11-20

  • Seedance 2.5 accepts 4k output, billed at the official 4K token rates. Seedance 2.0 4k is unchanged. Draft to Final stays 480p to 1080p.

2026-11-17

  • The reference now covers Seedream 5.5 image generation, layers and rich-text OCR, plus Seedance 2.5 Flash parameters and pricing.
  • Billing Keys support balance, BSC USDT top-up creation, order status, history and ledger APIs. The reference includes Python examples, parameter tables and response JSON, also available in /llms.txt.

2026-10-30

  • Create and revoke your own Keys in the console after a recent sign-in. New Keys run up to 10 tasks at once.
  • A full request and response reference with examples, status and error tables and callback verification code; it is also in /llms.txt.
  • Video and image submissions use a supplier client token, so a lost submission is re-sent without a second generation. A video already sent to BytePlus can no longer be cancelled.
  • Tasks not sent within 30 minutes of acceptance fail with ServerOverloaded and are not charged (was one hour).
  • Seedance 2.5 Final can use a Draft for 14 days after it is created, independent of media retention.
  • Native video status shows queued while a task is being sent, and a task whose output could not be archived reports MEDIA_ARCHIVE_FAILED on every kind.
  • Asset library: groups, quotas, asynchronous URL import, saving generated outputs and delayed deletion.
  • Tasks wait in the queue for free BytePlus capacity per model and retry supplier rate limits automatically, instead of failing at once.
  • An output that cannot be archived before the supplier link expires is now refunded in full automatically.
  • Self-service virtual portraits where enabled, preset digital characters as asset:// references, and video references limited to URL or asset://.
  • Image and audio creation is now asynchronous: it returns 202 with a task id instead of waiting for the result, and Prefer: respond-async is no longer needed. Read the output from the result field of GET /api/v3/tasks/:id.
  • Idempotency-Key is optional; the same key with different content still returns 409.
  • callback_url is accepted for video, image and audio, with signed delivery after archiving.
  • Errors on /api/v3 use the Ark error envelope and ModelArk codes.

Frequently asked questions

How do I integrate JMovie API with Python?

The Python integration examples on /docs#ref-python include environment setup, a shared requests client and runnable examples for Seedance 2.5 Flash video, Seedream 5.5 images, layers and rich-text OCR, and Seed Audio 1.0 speech. Save the task ID and poll GET /api/v3/tasks/:id. Resume polling after a timeout; reuse the same business request ID and payload if the create response was lost.

How do I create a Seedance video task?

POST /api/v3/contents/generations/tasks with a Bearer Key and a unique Idempotency-Key. Save the returned task ID and poll GET /api/v3/contents/generations/tasks/:id. After a timeout, resend with the same Idempotency-Key or query the task; never use a new key for the same task.

How do I generate a Seedream image or Seed Audio clip?

POST /api/v3/images/generations for Seedream 5.5 or 5.0 Pro and POST /api/v3/tts/create for Seed Audio 1.0. Query unified task state at GET /api/v3/tasks/:id.

Is JMovie API compatible with BytePlus ModelArk (Ark) requests?

Requests use Ark-style /api/v3 paths and fixed BytePlus model IDs, and errors use the Ark envelope with the ModelArk code where one exists. Every creation, including images and audio, is asynchronous: it returns a task id to poll or a signed callback_url delivery.

How do JMovie API callbacks work?

Send callback_url (public HTTPS, port 443) on any create request. The gateway POSTs the task body on every status change, sends succeeded only after the output is archived, and signs each delivery with X-JMovie-Signature. Polling remains the source of truth.