Documentation

Quickstart

1. Contact sales with your business details. Our team will contact you to agree on pricing, model access and Key limits.
2. Complete offline payment. After our team confirms receipt, we activate your account and issue your generation Key. There is no online checkout or self-service signup.
3. Send a Bearer Key and a unique Idempotency-Key with every paid request. Keep the same idempotency key when checking a request whose response was lost.
4. 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; polling is read-only. Do not repeat POST on a timeout.
curl https://api.j-movie.com/api/v3/contents/generations/tasks/$TASK_ID \
  -H "Authorization: Bearer $JMOVIE_API_KEY"

API reference

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.

Images and audio return the native-compatible result by default. To accept a durable background task immediately, send the following header; query the returned task ID through the unified task endpoint.

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 only confirms file checks, storage and API-account ownership. It 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.

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 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 a byte-identical owned source file for trustworthy dimensions and duration. 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.

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, be active and verified, and have been uploaded within the last 72 hours. A registered portrait resource expires no later than 72 hours after the source upload and never outlives an earlier source expiry; this does not automatically delete the original reference input. 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

Same generation Key, same Idempotency-Key and same request content return the existing task. 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

Cancellation is subject to provider confirmation. An uncertain cancellation is not a confirmed refund. 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. We do not automatically 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 offline funding 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.

This deployment is based on New API by QuantumNous. Corresponding modified source and build instructions are available from the source code link; credentials, customer data and production configuration are excluded.