وضع توليد الفيديو في قائمة الانتظار

Queue a new video generation request.

Authentication: This endpoint accepts either a Bearer API key or a SIGN-IN-WITH-X header for x402 wallet-based authentication. The legacy X-Sign-In-With-X header is also accepted during migration. When using x402, a 402 Payment Required response indicates insufficient balance and includes top-up instructions.

POST /video/queue

/api/v1/video/queue

cURL

curl --request POST \
  --url https://api.venice.ai/api/v1/video/queue \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "model": "seedance-2-0-text-to-video-basic",
  "prompt": "Commerce being conducted in the city of Venice, Italy.",
  "duration": "10s",
  "consents": {},
  "negative_prompt": "low resolution, error, worst quality, low quality, defects",
  "aspect_ratio": "16:9",
  "omni_reference_task_type": "edit",
  "resolution": "720p",
  "upscale_factor": 2,
  "enhancement_model": "Proteus",
  "target_fps": 60,
  "softness": 3,
  "creativity": 0.5,
  "realism": 0.5,
  "sharp": 0.5,
  "compression": 0.5,
  "noise": 0.5,
  "halo": 0.5,
  "grain": 0,
  "recover_detail": 0.5,
  "h264_output": false,
  "output_format": "mp4",
  "slowdown_factor": 1,
  "audio": true,
  "image_url": "data:image/png;base64,iVBORw0K...",
  "end_image_url": "data:image/png;base64,iVBORw0K...",
  "audio_url": "data:audio/mpeg;base64,SUQzBAA...",
  "video_url": "data:video/mp4;base64,AAAAFGZ0eXA...",
  "reference_image_urls": [
    "data:image/png;base64,iVBORw0K..."
  ],
  "reference_video_urls": [
    "https://example.com/reference-clip.mp4"
  ],
  "reference_audio_urls": [
    "data:audio/mpeg;base64,SUQzBAAAAAA..."
  ],
  "reference_document_urls": [
    "https://example.com/brief.pdf"
  ],
  "elements": [
    {
      "frontal_image_url": "data:image/png;base64,iVBORw0K...",
      "reference_image_urls": [
        "data:image/png;base64,iVBORw0K..."
      ]
    }
  ],
  "scene_image_urls": [
    "data:image/png;base64,iVBORw0K..."
  ],
  "keyframes": [
    {
      "image_url": "data:image/png;base64,iVBORw0K...",
      "frame_index": 0
    },
    {
      "image_url": "data:image/png;base64,iVBORw0K...",
      "frame_index": 120
    }
  ]
}
'

200

{
  "model": "video-model-123",
  "queue_id": "123e4567-e89b-12d3-a456-426614174000",
  "download_url": "<string>"
}

استدعِ /video/quote للحصول على تقدير للسعر، ثم استعلِم /video/retrieve باستخدام الـ queue_id المُعاد حتى يكتمل.

تُعيد النماذج الخاصة أيضًا download_url للفيديو النهائي. وهو عنوان URL للتسليم قصير الأمد (لا بأس بإعادة المحاولة بضع مرات في حال انقطع التنزيل)؛ راجع دليل توليد الفيديو للتفاصيل وDELETE الاختيارية للخصوصية.

​

Seedance 2.0 و 2.5

بالنسبة لنماذج seedance-2-0-*-basic و seedance-2-5-*-basic (text-to-video، image-to-video، reference-to-video، بالإضافة إلى متغيرات -fast-* لـ Seedance 2.0)، راجع دليل Seedance 2.0 و 2.5 لنموذج التدفقات الأربعة (Reference / Edit / Extend / Stitch)، وقيم aspect_ratio / duration المتطابقة مع المصدر، وحدود الإدخال متعدد الوسائط الخاصة بكل عائلة، وسياسة وسائط واجهة برمجة التطبيقات العامة، وتفاصيل التسعير.

​

سياسة وسائط Seedance العامة

لا تستخدم نماذج Seedance العامة إثباتات الموافقة. قد يتم رفض الوسائط التي تحتوي على أشخاص يمكن اكتشافهم من قِبل الطبقات الأعلى. استخدم تطبيق Venice أو Studio للحصول على مجموعة ميزات Seedance الكاملة. راجع دليل Seedance للتفاصيل.

​

تكبير الفيديو

لنموذج topaz-video-upscale، استخدم upscale_factor (1 أو 2 أو 4) بدلًا من resolution، وقدّم video_url. يتم اكتشاف المدة و FPS تلقائيًا من ملف الفيديو. راجع دليل تكبير الفيديو للحصول على التفاصيل والأمثلة الكاملة.

---

التفويضات

BearerAuthsiwx

Authorization · string · header · مطلوب

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

الجسم

application/json

Request body for video generation. Available fields and valid values vary by model.

model · string · مطلوب

The model to use for video generation.

مثال:

"seedance-2-0-text-to-video-basic"

prompt · string · مطلوب

The prompt to use for video generation. Required for most models. The maximum length varies by model (default 2500 characters, up to 20000 for some models).

Required string length: 1 - 20000

مثال:

"Commerce being conducted in the city of Venice, Italy."

duration · enum<string> · مطلوب

The duration of the video to generate. Available options vary by model. For Seedance 2.5 reference-to-video edit jobs, -1 or auto matches output length to the source clip (requires reference_video_urls on queue, or reference_video_total_duration on quote; source must be 4–30s).

الخيارات المتاحة: 1s, 2s, 3s, 4s, 5s, 6s, 7s, 8s, 9s, 10s, 11s, 12s, 13s, 14s, 15s, 16s, 17s, 18s, 19s, 20s, 21s, 22s, 23s, 24s, 25s, 26s, 27s, 28s, 29s, 30s, -1, 1 gen, auto, Auto

مثال:

"10s"

consents · object

Optional provider-specific consent attestations. Required only for models that return a needs_consent response.

Show child attributes

negative_prompt · string

Optional negative prompt. The maximum length varies by model (default 2500 characters, up to 20000 for some models).

Maximum string length: 20000

مثال:

"low resolution, error, worst quality, low quality, defects"

aspect_ratio · enum<string>

The aspect ratio of the video. Available options vary by model. Some models do not support aspect_ratio. For Seedance 2.x reference-to-video edit/extend, adaptive or auto matches output aspect ratio to the source clip (requires reference_video_urls on queue, or reference_video_total_duration on quote).

الخيارات المتاحة: 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 9:21, 16:9, 21:9, adaptive, auto

مثال:

"16:9"

omni_reference_task_type · enum<string>

Optional Seedance 2.5 reference-to-video task-type hint forwarded to BytePlus (auto | reference | edit | extend). Aliases editing→edit and extension→extend are accepted on the queue API. Pre-guides classification to reduce async TaskTypeConstraint errors. The prompt must still match the chosen type. When omitted, Venice infers from the prompt if reference_video_urls are present. Not supported on other models.

الخيارات المتاحة: auto, reference, edit, extend

مثال:

"edit"

resolution · enum<string>

The resolution of the video. Available options vary by model. Some models do not support resolution. Use upscale_factor for upscale models.

الخيارات المتاحة: 256p, 360p, 480p, 540p, 580p, 720p, 1080p, 1440p, 2160p, 4k, 1x, 2x, 4x, 2K, 768P, true_1080p

مثال:

"720p"

upscale_factor · enum<integer> · افتراضي: 2

For upscale models only. 1 = quality enhancement, 2 = double resolution (default), 4 = quadruple.

الخيارات المتاحة: 1, 2, 4

مثال:

2

enhancement_model · string

For enhancement models only. The provider-side enhancement model. Available values are listed per model in GET /models constraints.topaz.models.

مثال:

"Proteus"

target_fps · integer

For enhancement models only. Target FPS for frame interpolation (16-120). Doubles the price on upscaling endpoints when ≥48; scales linearly on interpolation. Omit to keep the source frame rate.

مثال:

60

softness · number

For enhancement models only. Softness level (1-5, sharpest to softest).

النطاق المطلوب: 1 <= x <= 5

مثال:

3

creativity · number

For enhancement models only. How much new detail the model invents (0.0-1.0).

النطاق المطلوب: 0 <= x <= 1

مثال:

0.5

realism · number

For enhancement models only. Bias generated detail toward photorealism (0.0-1.0).

النطاق المطلوب: 0 <= x <= 1

مثال:

0.5

sharp · number

For enhancement models only. Output sharpness (0.0 softens, 0.5 neutral, 1.0 strong).

النطاق المطلوب: 0 <= x <= 1

مثال:

0.5

compression · number

For enhancement models only. Compression artifact removal level (0.0-1.0).

النطاق المطلوب: 0 <= x <= 1

مثال:

0.5

noise · number

For enhancement models only. Noise reduction level (0.0-1.0).

النطاق المطلوب: 0 <= x <= 1

مثال:

0.5

halo · number

For enhancement models only. Halo reduction level (0.0-1.0).

النطاق المطلوب: 0 <= x <= 1

مثال:

0.5

grain · number

For enhancement models only. Film grain amount (0.0-0.1).

النطاق المطلوب: 0 <= x <= 0.1

مثال:

0

recover_detail · number

For enhancement models only. Recover original detail level (0.0-1.0).

النطاق المطلوب: 0 <= x <= 1

مثال:

0.5

h264_output · boolean

For enhancement models only. Output H.264 instead of the default H.265.

مثال:

false

output_format · enum<string>

For enhancement models only (SDR-to-HDR). Output container: mp4 (10-bit H265 HDR10) or prores (10-bit ProRes).

الخيارات المتاحة: mp4, prores

مثال:

"mp4"

slowdown_factor · enum<integer>

For enhancement models only (frame interpolation). Slow-motion factor: 2 makes the output twice as long at the target FPS, up to 8x. Multiplies the billed duration.

الخيارات المتاحة: 1, 2, 4, 8

مثال:

1

audio · boolean · افتراضي: true

For models which support audio generation and configuration. Defaults to true.

مثال:

true

image_url · string

For image-to-video models, the reference image. Must be a URL (http/https) or a data URL (data:image/...).

مثال:

"data:image/png;base64,iVBORw0K..."

end_image_url · string

For models that support end images or transitions, the end frame image. Must be a URL or data URL.

مثال:

"data:image/png;base64,iVBORw0K..."

audio_url · string

For models that support audio input, background music. Must be a URL or data URL. Supported: WAV, MP3. Max: 30s, 15MB.

مثال:

"data:audio/mpeg;base64,SUQzBAA..."

video_url · string

For models that support video input (video-to-video, upscale). Must be a URL or data URL. Supported: MP4, MOV, WebM.

مثال:

"data:video/mp4;base64,AAAAFGZ0eXA..."

reference_image_urls · string[]

For models with reference image support, up to 30 images for character/style consistency. Each must be a URL or data URL.

Maximum array length: 30

مثال:

["data:image/png;base64,iVBORw0K..."]

reference_video_urls · string[]

For models with reference video support (e.g. Seedance 2.0 R2V), up to 10 reference video URLs (role: "reference_video") used to inherit subject motion, camera movement, and overall style. Per-clip 2–15 s, .mp4 or .mov, ≤50 MB; aggregate duration ≤15 s. Each must be a URL or data URL.

Maximum array length: 10

مثال:

["https://example.com/reference-clip.mp4"]

reference_audio_urls · string[]

For models with reference audio support (e.g. Seedance 2.0 R2V), up to 10 reference audio URLs (role: "reference_audio") used as donors for vocal timbre, narration, or sound effects. Per-clip 2–15 s, .wav or .mp3; aggregate duration ≤15 s. Must be paired with at least one reference image or reference video — audio-only Reference workflows are rejected at validation. Each must be a URL or data URL.

Maximum array length: 10

مثال:

["data:audio/mpeg;base64,SUQzBAAAAAA..."]

reference_document_urls · string[]

For models with document / webpage Omni-Reference (Wan 3.0), up to 1 URL. Document files and public webpage URLs are fetched by Venice and forwarded as type: "file" (≤100 MB). Each must be a URL or data URL.

Maximum array length: 1

مثال:

["https://example.com/brief.pdf"]

elements · object[]

For models with advanced element support (e.g., Kling O3 R2V). Up to 4 elements defining characters/objects. Reference in prompt as @Element1, @Element2, etc.

Maximum array length: 4

Show child attributes

مثال:

[
  {
    "frontal_image_url": "data:image/png;base64,iVBORw0K...",
    "reference_image_urls": ["data:image/png;base64,iVBORw0K..."]
  }
]

scene_image_urls · string[]

For models with advanced element support. Up to 4 scene reference images. Reference in prompt as @Image1, @Image2, etc.

Maximum array length: 4

مثال:

["data:image/png;base64,iVBORw0K..."]

keyframes · object[]

For keyframe-driven models. Up to 10 keyframe images pinned to frame positions in the generated 24 fps video. Each frame_index must be unique and no greater than duration × 24.

Maximum array length: 10

Show child attributes

مثال:

[
  {
    "image_url": "data:image/png;base64,iVBORw0K...",
    "frame_index": 0
  },
  {
    "image_url": "data:image/png;base64,iVBORw0K...",
    "frame_index": 120
  }
]

الاستجابة

200

application/json

Video generation request queued successfully

model · string · مطلوب

The ID of the model used for video generation.

مثال:

"video-model-123"

queue_id · string · مطلوب

The ID of the video generation request.

مثال:

"123e4567-e89b-12d3-a456-426614174000"

download_url · string

Pre-signed URL to download the completed video. Only present for VPS-backed models. When provided, the retrieve endpoint returns JSON status only (no video stream). Fetch this URL after status is COMPLETED to get the video/mp4 file. Valid for 24 hours.