Video generation in your workflow.
The website, API and plugin share your account balance, prices and task history. Upload references, check the quote, submit a task, then poll and download the result.
Generation spends credits. An API key budget limits spending from your existing balance; it does not add credits. Keep your key private. The full key is shown only once.
Quick start
- Sign in and open API / CLI. Create a key with a spending budget.
- Store the key on your own server or in an environment variable.
- Check the quote. For each new generation, choose a unique operation ID; preserve it and all task parameters when retrying.
Base URL: https://www.aplovn.com/v1
Authorization: Bearer YOUR_API_KEY
1. Get a quote
POST /v1/videos/estimate
Content-Type: application/json
{"model":"seedance-2.5","resolution":"480p","duration":5}
Example response (use the current returned price):
{"credits":20,"breakdown":{"output_credits":20,"reference_credits":0,...},
"availability":{"available":true,"reason":"ok"},...}Availability is a snapshot, not a reservation. A task that cannot currently fit an available account is refused before your balance is debited. Retry later or choose a supported specification.
Promotions and final quotes
/v1/models and the price list show base rates. Use credits from /v1/videos/estimate as the final task price. When a promotion applies, breakdown also includes base_total_credits, discount_credits and promotion (name, payment percentage and rule revision). One best eligible promotion applies to the combined output and reference-video cost; round the final total up to an integer, with a minimum of one credit. Expiry restores the base price. Accepted tasks retain their original charge and refund amount. Recharge gifts are separate. Get a fresh quote before submission; after a 409, fetch and confirm the new quote. Keep the original operation ID when recovering an accepted task.
Promotion limits
Promotions may limit total discounted credits, discounted task slots and claims per account. The website and all API keys of the same account share these limits. Estimates do not reserve a slot; admission checks availability atomically with the debit. When a limit is reached, a new quote uses another eligible promotion or the base price. A changed confirmed quote is rejected before debit. Accepted tasks keep their claim after failure or cancellation: the actual payment is refunded, while the promotion slot and discounted-credit budget are not restored. Idempotent retries never claim twice.
2. Submit a task
POST /v1/videos
Content-Type: application/json
Idempotency-Key: order-2026-0001
{
"prompt":"A ginger cat surfing at sunset, cinematic camera movement",
"model":"seedance-2.5",
"resolution":"480p",
"duration":5,
"aspect_ratio":"16:9",
"generation_mode":"t2v",
"audio":true,
"enhance":false,
"expected_credits":20
}
{"task":{"id":123,"status":"queued",...},"balance":980}
Idempotency-Key is required: 1–100 ASCII characters without spaces (a UUID is recommended). The same key, operation ID and task parameters return the original task without a second debit. Changing the prompt, model or references under the same ID returns 409. The quote field is excluded from retry identity. Use the latest quote for expected_credits; a changed price returns 409 for renewed confirmation.
3. Poll and download
GET /v1/videos/123
GET /v1/videos/123/contentPoll every 5 seconds. Active statuses are queued / submitting / submitted / running; terminal statuses are completed / failed. Download the MP4 using an authenticated request. Download URLs do not contain your API key.
If a submission response is lost, Aplovn checks the original task instead of starting another generation. Slow generation or a temporary result-download failure keeps the task active. A confirmed failure refunds the actual debit. An unresolved upstream submission may require an operator to verify it. An audio error is not automatically retried as a new silent generation.
Endpoints
| Method | Path | Purpose |
|---|---|---|
| GET | /v1/models | Current models, capabilities and prices per second |
| GET | /v1/balance | Your credit balance |
| POST | /v1/uploads | Upload a reference; multipart field: file |
| POST | /v1/videos/estimate | Quote; no generation or credit debit |
| POST | /v1/videos | Create a paid generation task |
| GET | /v1/videos | Your website and API tasks; status, q, limit and offset filters |
| GET | /v1/videos/{id} | Your task status |
| GET | /v1/videos/{id}/content | Your completed MP4 |
References and parameters
Upload local files with POST /v1/uploads. The response includes asset_id / kind / duration_sec. The server measures video duration. Include ref_video_asset_ids when quoting reference videos.
Omni reference (at least one reference):
"generation_mode":"omni",
"refs":[
{"asset_id":"IMAGE_ID","kind":"ref_image","position":0},
{"asset_id":"VIDEO_ID","kind":"ref_video","position":0},
{"asset_id":"AUDIO_ID","kind":"ref_audio","position":0}
]
First / last frame (first frame required, last frame optional):
"generation_mode":"frames",
"ref_asset_id":"FIRST_IMAGE_ID",
"refs":[{"asset_id":"LAST_IMAGE_ID","kind":"end_frame","position":0}]
Quote with video references:
{"model":"seedance-2.5","resolution":"480p","duration":5,
"ref_video_asset_ids":["VIDEO_ID"]}
Use @Image1 / @Video1 / @Audio1 in prompts (Chinese aliases are also supported). Numbers match each reference kind's zero-based position + 1; when omitted, positions follow submission order. Repeated positions of the same kind are rejected. Missing references and overlong expanded prompts are rejected before payment. The application ceiling is 10,000 characters; read specs_by_resolution from GET /v1/models for the selected resolution’s prompt_max, durations, ratios and prompt_enhancement. Some channels have a lower limit. Prompts are never silently truncated. First/last-frame roles follow their explicit fields, regardless of mention order. Routing updates affect new tasks; accepted tasks retain their original connection.
Models: seedance-2.5 / seedance-2.0 / seedance-2.0-mini / seedance-2.0-fast / wan-3.0. Resolutions, aspect ratios, audio support, reference counts and duration limits come from /v1/models. Supported resolutions and durations can differ by connection; use specs_by_resolution for the chosen resolution. Send enhance:false unless prompt_enhancement is explicitly true. Modes: t2v / omni / frames. First/last frames and omni references are separate modes. Seedance 2.0 / Mini / Fast audio references need an image or video. Seedance bills combined reference-video duration rounded up, with a 4-second minimum; Wan rounds each clip up separately. Wan output plus reference-video duration cannot exceed 30 seconds. Keep audio explicit when audio matters.
Asset library and projects
The website's Asset library keeps your uploaded images, video and audio in one private workspace. Search, rename and move them between projects, choose existing files in the composer, or reuse the references from an earlier task. Model limits and reference-video charges still apply.
A project organizes both references and generated tasks. Deleting a project moves its contents to Unassigned without deleting files, tasks or videos. Removing an asset from the visible library prevents new selection; its original file is retained for existing tasks and still counts toward storage. The default allowance is 5 GiB and 3,000 retained uploads per account. Contact support to adjust capacity.
Use GET /v1/projects for your projects and GET /v1/assets for your assets. Asset filters: q, kind, project_id, limit and offset. Reuse the returned asset_id in generation references. Download an original with an authenticated GET /v1/assets/{id}/content request. Listings do not expose internal upstream URLs.
Upload to a project with POST /v1/uploads?project_id=p_.... Generation accepts an optional project_id; task listings support the same filter. Omit it for existing client behavior. In listing queries, project_id=unassigned selects only uncategorized content. Manage projects on the website. Old upstream reference URLs are refreshed from your retained originals without creating another generation.
python aplovn.py projects
python aplovn.py assets --project p_PROJECT_ID --kind ref_image
python aplovn.py upload "E:\assets\character.png" --project p_PROJECT_ID
python aplovn.py list --project p_PROJECT_ID
python aplovn.py generate --mode omni --image a_ASSET_ID --project p_PROJECT_ID --prompt "The character in @Image1 walks toward the camera" --waitCLI
Download aplovn.py. Requires Python 3.10+; no extra packages. Windows PowerShell examples:
$env:APLOVN_API_KEY="YOUR_API_KEY"
python aplovn.py models
python aplovn.py balance
python aplovn.py estimate --duration 5
python aplovn.py generate --prompt "A cat at the beach" --wait
python aplovn.py upload "E:\media\reference.mp4"
python aplovn.py generate --mode omni --video "asset_id" --prompt "Follow the camera movement" --wait
python aplovn.py status 123
python aplovn.py download 123 --out "E:\videos\123.mp4"The CLI asks you to confirm the quote. Automated scripts can pass --yes after confirming costs. Preserve the printed request ID; after interruption, use the same --request-id and original parameters to recover that operation.
ZiZi Animation plugin
The separate plugin entry is below API / CLI in the sidebar. Installation and use → · Current plugin: 0.1.2. The plugin uses your own API key and account balance; it needs no website session, CLI or pool credentials.
Execution slots, queues and progress
The default is 12 concurrent executions per account, shared across web, API keys and plugins. Additional jobs are accepted into the queue and dispatched automatically when slots free up. Administrators can change execution limits, queue capacity and progress display. A lower per-key limit also queues extra jobs.
Acceptance debits the quoted credits once; dispatch does not debit again. Confirmed failures and cancelled unstarted jobs refund the original debit. The default waiting queue capacity is 200 per account. A full waiting queue returns429 with Retry-After; normal rate and balance checks still apply.
POST /v1/videos/{task_id}/cancel cancels an unclaimed queued job. Started jobs return409. Repeated cancellation never refunds twice. For compatibility, cancelled jobs retain status=failed with error_code=cancelled_before_submit.
Tasks expose progress_stage and progress_display. Stages include queued, submitting, generating, transferring, checking and completed. An unavailable vendor percentage is represented as progress=0; display the stage instead of inventing a timed percentage. Generation percentages stop at95, transfer uses97, and100 is returned only after a complete verified file is saved. Display mode stages suppresses percentages. Lists also include queued_total, executing_total and concurrency_limit.
Errors
- 401: invalid or revoked key, or unavailable account.
- 402: insufficient account balance or remaining key budget.
- 409: changed quote, conflicting operation ID, or result not ready.
- 400 / 422: invalid parameters or references.
- 429: request rate or full waiting queue; follow Retry-After. Occupied execution slots queue new jobs instead of rejecting them.
- 503: generation capacity temporarily unavailable. No task debit occurs when refused at preflight.
Manage and revoke keys on API / CLI. All your tasks appear in Task history. API keys cannot access admin or payment-management functions. Contact aplovn@163.com.