Generate videos
Submission returns HTTP 202 with a ShareAI job ID and polling URL.
On this page
https://api.shareai.now/api/v1/videosGenerate videos
- Base URL
https://api.shareai.now- Authentication
- Bearer API key or approved OAuth access token
- Required scope
inferenceormonetization_gateway
Submission returns HTTP 202 with a ShareAI job ID and polling URL. Send a stable Idempotency-Key header for retries of the same request. Reusing that key with different input is rejected. Poll GET /api/v1/videos/{id} with the same originating credential. States include queued, pending, in_progress, finalizing, completed, failed and requires_review. A requires_review result needs team reconciliation; polling never starts another generation.
Before you start#
Set SHAREAI_API_KEY on your server and replace the model placeholder with a currently enabled model. Never expose the API key in browser code. The model, account, credential and provider must all permit this operation. Optional settings below require model support; the API safety bounds are not a promise that every model supports every value.
Send a request#
cURL
curl --fail-with-body --request POST "https://api.shareai.now/api/v1/videos" \
-H "Authorization: Bearer $SHAREAI_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: YOUR_UNIQUE_REQUEST_ID" \
--data '{
"model": "YOUR_ENABLED_VIDEOS_MODEL",
"prompt": "A slow camera move through a quiet forest.",
"duration": 8
}'Python
import json
import os
import urllib.request
payload = {'model': 'YOUR_ENABLED_VIDEOS_MODEL',
'prompt': 'A slow camera move through a quiet forest.',
'duration': 8}
headers = {'Content-Type': 'application/json', 'Idempotency-Key': 'YOUR_UNIQUE_REQUEST_ID'}
headers["Authorization"] = "Bearer " + os.environ["SHAREAI_API_KEY"]
request = urllib.request.Request('https://api.shareai.now/api/v1/videos', data=json.dumps(payload).encode(), headers=headers, method="POST")
with urllib.request.urlopen(request, timeout=180) as response:
result = json.load(response)
print(result)TypeScript
const response = await fetch("https://api.shareai.now/api/v1/videos", {
method: "POST",
headers: { Authorization: `Bearer ${process.env.SHAREAI_API_KEY}`, ...{"Content-Type": "application/json", "Idempotency-Key": "YOUR_UNIQUE_REQUEST_ID"} },
body: JSON.stringify({
"model": "YOUR_ENABLED_VIDEOS_MODEL",
"prompt": "A slow camera move through a quiet forest.",
"duration": 8
}),
});
if (!response.ok) throw new Error(await response.text());
const result = await response.json();
console.log(result);Request fields#
| Field | Type | Meaning and limits |
|---|---|---|
model required | string | Exact enabled public model identifier. Must declare this operation and be allowed by your credential. |
prompt required | string | Nonempty generation prompt, at most 256 KiB of UTF-8 text. |
duration | integer | Optional requested video duration in seconds, 1–600, further restricted by the selected model. Actual returned durations determine duration billing. |
resolution | string | Model-supported resolution selector, at most 100 characters; must match the published tariff variant. |
aspect_ratio | string | Model-supported aspect ratio selector, at most 100 characters. |
size | string | Model-supported output size, at most 100 characters, for example 1024×1024. Not every model supports this option. |
generate_audio | boolean | Optional video soundtrack selector. Model support and the matching tariff variant are required. |
seed | integer | Optional model-supported seed. Video requires a nonnegative integer; reproducibility depends on the executor. |
frame_images | array | At most two image_url parts, each with frame_type first_frame or last_frame, without duplicates. Do not combine frame_images and input_references. |
input_references | array | At most 16 typed image_url parts with image_url.url set to an HTTPS URL or supported image data URL. Model support is required. |
provider | object | Optional provider routing preferences. Use provider.only for accepted provider tags, not a prefix in the model ID. Account and credential restrictions still apply. |
allow_temporary_retention | boolean | Video only. Explicit true permits temporary upstream result retention on routes that require it. Omitted/false keeps those routes unavailable. Conflicts with provider.zdr:true; other operations retain mandatory ZDR. |
Read the result#
Success returns HTTP 202 with JSON. Submission returns HTTP 202 with a ShareAI job ID and polling URL. Send a stable Idempotency-Key header for retries of the same request. Reusing that key with different input is rejected. Poll GET /api/v1/videos/{id} with the same originating credential. States include queued, pending, in_progress, finalizing, completed, failed and requires_review. A requires_review result needs team reconciliation; polling never starts another generation.
Billing units#
Video routes declare their billed units. A per-second route settles using the measured duration of each returned file, never the requested duration or an upstream USD cost. Requested duration must be between 1 and 600 seconds and supported by the model. A conservative credit hold can cover up to four outputs.
Choose the exact enabled model identifier from Console. Its declared operation and input/output capabilities must match this endpoint; a text chat model cannot be substituted for another operation. Your credential, provider and account restrictions still apply.
Pricing and usage#
Rates are published in EUR AI credits for the selected model, provider, units and variants. Only the dimensions in its active tariff are charged. An estimate reserves credits before execution; final charges use measured usage. Prices can depend on resolution, output format or a usage band. Check Console Usage for the final ShareAI debit. Upstream cost fields and media bytes are not converted into invented token counts.
Access and errors#
Use inference for approved network-cost inference or monetization_gateway for an approved Builder markup and accepted billing terms. Identity-only access does not authorize spending. Validation, model authorization, insufficient credits, rate limits and execution failures return a structured error. After a timeout or uncertain submission, inspect Usage or the video job before creating another potentially paid request.
Temporary video retention#
Some video routes need temporary upstream retention so the generated result can be retrieved. They require your explicit allow_temporary_retention:true acceptance on that video request. Omitting it keeps those routes unavailable. This exception applies to video only and never permits model training or retention for other operations. An explicit ZDR policy cannot be silently weakened.
JSON
{"allow_temporary_retention": true}Check job status#
https://api.shareai.now/api/v1/videos/{id}Read a video generation with its originating credential
- Base URL
https://api.shareai.now- Authentication
- Bearer API key or approved OAuth access token
- Required scope
inferenceormonetization_gateway
JSON
{
"id": "YOUR_JOB_ID",
"object": "video",
"status": "pending",
"created_at": 1793664000,
"polling_url": "/api/v1/videos/YOUR_JOB_ID"
}The JSON above illustrates the stable job fields, not a real generation. Poll the ShareAI path with the same key, waiting between checks. queued, pending, in_progress and finalizing mean wait; completed exposes data with ShareAI content URLs; failed and requires_review mean stop and inspect. Retry status reads after transient errors, but do not resubmit generation automatically. A different or revoked credential cannot retrieve the job.
cURL
curl --fail-with-body "https://api.shareai.now/api/v1/videos/YOUR_JOB_ID" \
-H "Authorization: Bearer $SHAREAI_API_KEY"Download the result#
When completed, each data entry contains a ShareAI content URL. Fetch GET /api/v1/videos/{id}/content?index=0 using the same originating credential. The endpoint supports a single HTTP byte range. Provider URLs, private tickets and provider credentials are never returned. Polling and downloading do not create a second inference request or Monetization Gateway ingestion charge. A completed job means settlement is confirmed before the file becomes downloadable.
cURL
curl --fail-with-body "https://api.shareai.now/api/v1/videos/YOUR_JOB_ID/content?index=0" \
-H "Authorization: Bearer $SHAREAI_API_KEY" --output result.mp4Optional frame_images must contain image_url parts with first_frame or last_frame. Use frame images or reference images in one request, not both. Model durations, resolutions and aspect ratios can be more restrictive than the API’s safety bounds. Webhooks and arbitrary callback URLs are not supported.
Last updated November 3, 2026