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
- Create an account and verify your email address to open your own API console.
- 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.
- Send a Bearer Key with every request. Add an
Idempotency-Keyto paid requests (recommended) and keep it when retrying a request whose response was lost. - Save the returned task ID and your original
Idempotency-Key. Resume querying that task after a timeout; do not submit a second paid generation. - 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"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_IDto 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_URLto your own PNG/JPEG HTTPS URL or an owned asset:// reference obtained through the Asset library guide.max_imagesincludes 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.pyafter 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
5xxdoes not prove that creation failed. Do not generate a new request ID: query the saved task, or recover with the same path, exact payload andIdempotency-Key. The client does not automatically retry paid POSTs. APIErrorexposes code, status,request_idandretry_after. HandleINSUFFICIENT_BALANCEby pausing submissions and funding through the Billing API or console;KEY_LIMIT_EXCEEDEDrequires checking Key limits. For transient rate limiting, respectRetry-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_statusand only treatactual_usdas final after settled. Keep USD strings precise; usedecimal.Decimalin 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.
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"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")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))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))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"])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))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.# 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. SendAuthorization: Bearer <Key>, andContent-Type: application/jsonon every call except the multipart asset upload. Every response carriesX-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.codeis the ModelArk equivalent for existing Ark clients. - Times are RFC 3339 UTC strings, except native video
created_atandupdated_at, which are Unix seconds as in Ark. Money fields are decimal USD strings. - Unknown request fields and explicit null values are rejected with
400before 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-260628ordreamina-seedance-2-5-flash-261115.content: 1 to 51 items, each with type text,image_url,video_url,audio_urlordraft_taskand 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_typeauto, 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_fixedand inline flags such as --seed in the prompt are rejected.
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
}'{
"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-261028ordola-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,220pixels with aspect ratio 1/16 to 16.Optional:response_format(url orb64_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_generationother than disabled. See the layer endpoints below for multi-layer output. - When succeeded,
result.data[].urlholds signed private image links;b64_jsonrequests keepresult.data[].b64_jsonand 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_formatmust be url. Do not send background oroptimize_prompt_options.- Returns
202with the same task, auth, model permissions, idempotency and callback contract as generation. PollGET /api/v3/tasks/:id.result.datacontains the base image (z_index0) and each layer. Usez_indexfor composition andbounding_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_imagesat 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. Choosemax_imagesdeliberately to bound the hold.
{
"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. Supplyingtext_recognitionfalse is rejected. Use a uniqueIdempotency-Key, save the returned task id, then poll/api/v3/tasks/:id. - Read
result.data[].text_recognitionwhen present. Its text, lines, boxes, text runs and styles are returned without flattening; layerz_index,bounding_box, size and signed url remain available. No recognized text may be returned for an image without text.
{
"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_urlorimage_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 orogg_opus),sample_rate(8000, 16000, 24000 default, 32000, 44100 or 48000),speech_rateandloudness_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.urlis a signed link to the archived audio. result also keeps the provider fields, including its Base64 audio; preferresult.url.
Seedance 2.5 Draft to Final
Draft: send "draft": true with modeldreamina-seedance-2-5-260628and 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_typeor 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.
{
"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),expiredorunknown.failed,cancelledandexpiredare terminal;succeededis final for the generation but later becomesexpiredwhen its 72-hour retention ends, with billing unchanged (the native video query then answers410MEDIA_EXPIRED).unknownis not terminal: the outcome is being reconciled by the operator, so keep polling and do not resubmit; it ends assucceeded(then billed as below) orfailed(released).generation_status:queued,sending,submitted,running,succeeded,failedorunknown(the generation itself).billing_status:reserved(funds frozen),pending(funds frozen while usage is verified),settled(charged;actual_usdis set),released(hold returned, nothing charged),refunded(asettledcharge was returned).storage_status:pending,archiving,retry,ready(links work),failed(could not be archived),expiredorpurged(past the 72-hour retention).- When a charge is final: once status is succeeded and
billing_statusis settled,actual_usdnever 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 withMEDIA_ARCHIVE_FAILED). - Every failure, cancellation,
ServerOverloadedandTASK_EXPIREDends withbilling_statusreleased: nothing was charged.MEDIA_ARCHIVE_FAILEDends refunded when it had already been settled, otherwise released. Neither costs you anything. - Unsettled means frozen: while
billing_statusis reserved or pending, or status is unknown,reserved_usdstays 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 (chargeactual_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/:iduntilbilling_statusis settled, or released if the usage cannot be verified. reserved_usdis the amount currently frozen for the task (0 once it settles or is released);initial_reservation_usdis the amount frozen at acceptance.error_codeanderror_messageexplain failures, for exampleServerOverloaded(not sent within 30 minutes),TASK_EXPIRED(BytePlus did not run it withinexecution_expires_after),MEDIA_ARCHIVE_FAILED(output could not be stored), CANCELLED,PROHIBITED_CONTENT, or a ModelArk code such asOutputVideoSensitiveContentDetected.usage: video{completion_tokens, duration}; image{image_count, image_sizes}; audio{original_duration, duration}.price_snapshotis 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_atandlink_expires_at. Links last up to one hour; query again to refresh them. Media is kept 72 hours.trace: youridempotency_key, ourtask_idandrequest_id, and the BytePlus task, request and log IDs.GET /api/v3/tasks?q=<any of these>finds the task.
{
"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/:idreturns the Ark body. When the output is archived it is the BytePlus result withcontent.video_url(andcontent.last_frame_urlwhen requested) replaced by signed links, plusgeneration_status,billing_status,storage_statusand 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 exampleerror.codeMEDIA_ARCHIVE_FAILEDwhen archiving is impossible. unknown means the outcome is being reconciled. GET /api/v3/contents/generations/taskslists your videos:page_numandpage_size(1 to500, defaults 1 and 20),filter.status(queued, running, succeeded, failed, cancelled, unknown),filter.task_ids(repeat, up to500),filter.model,filter.service_tier(default only). Returns{"items":[...],"total":n}.GET /api/v3/taskslists 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 port443, 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 theGET /api/v3/tasks/:idbody ({"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-AgentJMovie-API-Callback/1.Signature: v1= hex(HMAC-SHA256(key, timestamp + "." + raw body)), where key is the lowercase hex SHA-256of 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
2xxwithin 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.
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"])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_urlincluded) or kind returns409with codeIDEMPOTENCY_CONFLICT(Arkerror.codeIdempotencyKeyConflict). Two simultaneous requests with one key create one task. - Without the header every request is a new paid task, and
trace.idempotency_keyis empty. - Use the top-level error code to decide recovery. A timeout, proxy error, HTTP
5xxor failed retry does not prove that an earlier attempt created no task. Keep the original path, payload andIdempotency-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) andX-RateLimit-Reset(seconds until it is full). A429also carriesRetry-Afterin 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_EXCEEDEDmeans wait for one to finish. 429RATE_LIMIT_EXCEEDED: waitRetry-After.429KEY_CONCURRENCY_EXCEEDED: too many of this Key's tasks are running; retry when one finishes.429KEY_LIMIT_EXCEEDED: the Key budget is spent; do not retry.- A per-IP guard also returns
429with an empty body andRetry-Afterwhen one address sends more than 360 requests in 180 seconds; nothing was accepted. WaitRetry-After, then resend with the sameIdempotency-Key. - During supplier capacity peaks a task waits in status queued; it fails with
ServerOverloadedand 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_KEY401AuthenticationError: no.ACCOUNT_DISABLED,KEY_OR_ACCOUNT_DENIED403AccessDenied(inactive Key or model not allowed): no.INSUFFICIENT_BALANCE402AccountOverdueError: after funding.KEY_LIMIT_EXCEEDED429AccountQuotaExceeded: no.ASSET_QUOTA_EXCEEDED403AccountQuotaExceeded(library full): after deleting assets.RATE_LIMIT_EXCEEDED429AccountRateLimitExceededandKEY_CONCURRENCY_EXCEEDED429ModelAccountConcurrentRequestsLimitExceeded: yes, later.INVALID_REQUEST,INVALID_REFERENCE,INVALID_CALLBACK_URL,INVALID_IDEMPOTENCY_KEY,UNSUPPORTED_REQUEST,TOKEN_ESTIMATE_TOO_LARGE,INVALID_FILTER,INVALID_PAGINATION,UNSUPPORTED_FILTER400InvalidParameter: no, fix the request.REQUEST_TOO_LARGEandMEDIA_TOO_LARGE413: no.IDEMPOTENCY_CONFLICT409IdempotencyKeyConflict: no.NOT_FOUND404ResourceNotFound: no.MEDIA_EXPIRED410ResourceExpired: no, the 72-hour retention ended.TASK_NOT_QUEUED409OperationDenied.InvalidState: no, the task can no longer be cancelled.TASK_ALREADY_CANCELLED409: no.CANCELLATION_UNCONFIRMEDandBILLING_PENDING409OperationDenied.InvalidState: retry later.OUTPUT_NOT_AVAILABLE404ResourceNotFound: the output is not archived or past retention.INTERNAL_ERROR,REFERENCE_SERVICE_UNAVAILABLE,SIGN_FAILED,STORAGE_UNAVAILABLE,DELETE_PENDING5xxInternalServiceError: yes, with the sameIdempotency-Keyfor creates.GENERATION_UNAVAILABLE503InternalServiceError: generation is paused by the operator; nothing was accepted.- Generation failures from BytePlus (for example
SensitiveContentDetected) appear on the task aserror_codewith status failed, not as an HTTP error.
Cancel and delete
POST /api/v3/contents/generations/tasks/:id/cancelworks 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:
409TASK_NOT_QUEUED. While a send is in flight or its outcome is unknown:409CANCELLATION_UNCONFIRMED. - Image and audio tasks cannot be cancelled.
DELETE /api/v3/contents/generations/tasks/:idcancels a queued video, or removes a finished one and its media from listings. Billing records are kept; deleting never reverses a charge.409TASK_ALREADY_CANCELLEDorBILLING_PENDINGwhen 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. Alast_frameneeds afirst_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 rolereference_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 adata:<mime>;base64,<data>URI. Videos cannot be Base64. The whole request body is capped at 64 MiB.
"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 andgroup_id. Images jpeg, png or webp up to 30 MiB; audio wav, mp3 orogg_opusup to 15 MiB; video mp4 or mov; any file up to256MiB 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. Returns202with status importing; pollGET /api/v3/assetsuntil 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 forexecution_expires_afterplus 15 minutes, otherwise the request is refused withINVALID_REFERENCE; a saved library copy has no such limit.GET /api/v3/assets: status (active default, importing, failed or all), kind,group_id,created_fromandcreated_to(YYYY-MM-DD), q (name contains), offset, limit. Returns items (each with id, referenceasset://<id>, kind, name, status,byte_size, width, height,duration_seconds,created_at) and usage{count, bytes, quota_count, quota_bytes}.GET /api/v3/assets/:idreturns{asset, url, link_expires_at}.PATCH /api/v3/assets/:idtakes{name?, group_id?}.DELETE /api/v3/assets/:idreturns{deleted:true}; the stored file is removed 72 hours and 15 minutes later, so tasks already running keep working.- Asset groups: GET, POST
{name}andPATCH /api/v3/asset-groups[/:id]{name},DELETE /api/v3/asset-groups/:id(its assets become ungrouped). Up to500groups. - Default quota: 1000 assets and 20 GiB per account; above it uploads return
403ASSET_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.
| Method | Path | Purpose |
|---|---|---|
| GET | /balance | Wallet snapshot |
| GET | /payment-methods | Network and checkout availability |
| POST | /topups | Create or replay a payment order |
| GET | /topups/{id} | Check payment and credit |
| GET | /topups | Recover and list orders |
| GET | /ledger | Reconcile credits and usage |
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/v3endpoints. Money and ledger IDs are strings. All responses are no-store; retainX-Request-Idfor support.
GET /billing/balance
No parameters. Requires either Billing Key permission. Does not charge the account.
| Field | Type | Meaning |
|---|---|---|
balance_usd | decimal string | Posted wallet balance. |
reserved_usd | decimal string | Funds held by unresolved tasks. |
available_usd | decimal string | balance − reserved; may be negative. |
spendable_usd | decimal string | max(available, 0). |
debt_usd | decimal string | max(−balance, 0). |
ledger_cursor | string | Latest ledger ID in the same consistent snapshot. |
as_of | UTC timestamp | Snapshot time. |
{
"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.
{
"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.
| Parameter | Location / type | Requirement |
|---|---|---|
Idempotency-Key | header · string | Required, 16–128 characters: letters, digits, dot, underscore, colon, hyphen. Persist before POST. |
amount_usd | JSON · string | Required, 30–100000 USD, at most 2 decimal places. No other body fields; maximum body 1 KiB. |
{"amount_usd":"100"}{
"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 returns409IDEMPOTENCY_CONFLICT.Idempotency-ReplayedandLocationheaders identify the result.- One open unpaid order per account. A different request key while an order is open returns
409ORDER_PENDING, including for the same amount. Recover it withGET /topups. After a timeout, retry the original key and amount; never invent a replacement payment. - New orders require a healthy chain scanner; otherwise
503BSC_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. Honor429Retry-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.
| Status | Meaning | Client action |
|---|---|---|
awaiting_payment | No matched finalized credit yet. | Pay only if your wallet has not already sent this order; otherwise keep polling. |
paid | The verified transfer was credited. | Reconcile amount_usd and tx_hash with the ledger. |
expired | Payment 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. |
{
"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.
| Query | Type | Usage |
|---|---|---|
limit | integer · optional | 1–100; default 20. |
before | string · optional | Use next_cursor from the previous response. Stop when next_cursor is null. |
{
"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.
| Query | Type | Usage |
|---|---|---|
limit | integer · optional | 1–100; default 20. |
before | string · optional | Use next_cursor from the previous response. Stop when next_cursor is null. |
{
"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_ofis the original ledger ID, or "0". Positive credit amounts are funds added;reserve_delta_usddescribes changes to task holds. Internal operator IDs, notes and private receipts are not exposed.
Payment rules and errors
| HTTP / code | Meaning | Action |
|---|---|---|
401 INVALID_API_KEY | Missing, expired or revoked credential | Use an active Billing Key. |
403 BILLING_SCOPE_REQUIRED | Wrong Key purpose or read-only Key used to create | Create a Key with the required billing permission. |
400 INVALID_AMOUNT / INVALID_IDEMPOTENCY_KEY | Invalid request | Correct input before retrying. |
409 IDEMPOTENCY_CONFLICT | Request key was bound to a different amount | Recover the original request; do not pay twice. |
409 ORDER_PENDING | An open order exists | GET /topups to recover it. |
429 RATE_LIMIT_EXCEEDED | Request limit exceeded | Wait Retry-After, reuse the same request key. |
503 BSC_UNAVAILABLE | New checkout unavailable | Wait; existing orders remain queryable. |
- BSC mainnet only (chain 56), using the exact USDT contract returned by the order. Transfer the exact
transfer_usdtonce; keep gas separate. A100.003217 USDT quote credits100USD. 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_urloraudio_urlreferences (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_urlreceives signed status updates. - The response returns the task id. Query
GET /api/v3/contents/generations/tasks/:iduntil status is succeeded, failed, cancelled or expired (unknown is not final: keep polling);content.video_urlappears 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_statusis 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.
InvalidParameteron 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-261028anddola-seedream-5-0-pro-260628with a prompt, optional image references, size (default 2K),response_formaturl orb64_jsonandoutput_formatpng or jpeg. Regular generation returns one image. Seedream 5.5 also offers/api/v3/images/layersand/api/v3/images/ocrfor a single input image; see their reference below for limits and per-layer billing. - Creation is asynchronous: it returns
202with the task id and aLocationheader. QueryGET /api/v3/tasks/:iduntil 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.
SensitiveContentDetectedor 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.0withtext_prompt, optional references (audio, or a single image) andaudio_configfor format and sample rate. - Creation is asynchronous: poll
GET /api/v3/tasks/:iduntil status is succeeded; its result field holds the audio output. Billing uses the actualoriginal_durationin 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 withtask_idbefore its 72-hour retention ends. URL import is asynchronous: it returns202with status importing, then active or failed withfailure_reason. - Organize assets with
/api/v3/asset-groupsand filterGET /api/v3/assetsbygroup_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
AccountQuotaExceededon 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 port443and return a supported format within the size limit. OUTPUT_NOT_AVAILABLEwhen 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-Keyis 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
409witherror.codeIdempotencyKeyConflict. - After a timeout or lost response, resend the same request with the same
Idempotency-Keyor 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, port443). 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 a2xxresponse within 5 seconds is retried three times. VerifyX-JMovie-Signature, which is v1= followed by the hex HMAC-SHA256 ofX-JMovie-Timestamp, a dot and the raw body, keyed with the hex SHA-256of 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
ServerOverloadedand 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_FAILEDwhilegeneration_statusremains succeeded, and the charge is refunded in full automatically.
Results and storage
- Use media only after
storage_statusis 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
410MEDIA_EXPIREDand 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-Keyderived 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
429instead of retrying immediately.
Endpoint index
GET/api/v3/billing/balanceQuery account balance with a Billing KeyGET/api/v3/billing/payment-methodsCheck BSC checkout availabilityPOST/api/v3/billing/topupsCreate an idempotent BSC USDT top-up orderGET/api/v3/billing/topups/:idQuery top-up payment and credit statusGET/api/v3/billing/topupsList your top-up historyGET/api/v3/billing/ledgerQuery your account ledgerPOST/api/v3/contents/generations/tasksCreate a video taskGET/api/v3/contents/generations/tasks/:idQuery a video taskGET/api/v3/contents/generations/tasksList your video tasksPOST/api/v3/contents/generations/tasks/:id/cancelRequest cancellation of a video taskDELETE/api/v3/contents/generations/tasks/:idDelete a video task and retained mediaPOST/api/v3/images/generationsGenerate one imagePOST/api/v3/images/layersDecompose a Seedream 5.5 image into layersPOST/api/v3/images/ocrExtract layers with rich-text OCRPOST/api/v3/tts/createGenerate Seed AudioGET/api/v3/tasks/:idQuery unified task states and refresh media linksGET/api/v3/tasksList your video, image and audio tasksPOST/api/v3/assetsUpload a reference assetPOST/api/v3/assets/importImport a reference asset from an allowed remote URLGET/api/v3/assetsList your reference assetsGET/api/v3/assets/:idQuery an authorized reference assetDELETE/api/v3/assets/:idDelete your reference assetGET/api/v3/portrait-verification/sessionsList your people and verification statesPOST/api/v3/portrait-verification/sessions/:id/linkResume an unexpired private verification linkPOST/api/v3/portrait-verification/sessions/:id/revokeWithdraw portrait use and request supplier group deletionPOST/api/v3/provider-resources/:id/revokeRemove an appearance and request supplier asset deletionPOST/api/v3/portrait-verification/sessionsStart the person's provider verificationGET/api/v3/portrait-verification/sessions/:idQuery your verification session metadataPOST/api/v3/portrait-verification/sessions/:id/refreshConfirm verification with the provider serverPOST/api/v3/portrait-assetsRegister a verified person's reference assetGET/api/v3/provider-resourcesList your registered provider resourcesPOST/api/v3/provider-resources/:id/refreshCheck the registered asset's current provider statusThe 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:
- Preset digital characters: free characters provided by BytePlus. Use asset://<preset ID> from the preset list in your console.
- 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.
- 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.
- 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.
- Use the Real-human library in your console, or your generation Key for the
/api/v3routes. Session creation and portrait registration require anIdempotency-Key. Start with{"name":"Private person label","consent":true}. The response includes id, status,expires_atandconsent_version, withh5_urlonly 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. - 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/callbackis only a return path: its resultCode is not proof of authorization. - 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.
- 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 andverification_state=provider_verified, corresponding to provider Active. - Use the returned reference, asset:// followed by the local resource UUID, in the matching
image_url.url,video_url.urloraudio_url.urlfield 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-Keyand 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_statusandstorage_statusare independent. Generation success does not mean verified settlement or completed storage.- Actual usage
- Video is settled using actual
completion_tokensat 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 actualoriginal_durationin 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 (
409TASK_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.