रेफ़रेंसेज़ और एसेट्स

ओवरव्यू

ज़्यादातर Image & Video मॉडल प्रॉम्प्ट के साथ मीडिया स्वीकार करते हैं: वीडियो के लिए पहला फ़्रेम, एडिट की जाने वाली इमेज या लिप-सिंक के लिए ऑडियो। API में हर मीडिया-वैल्यू फ़ील्ड तय आकार के रॉ बाइट्स के बजाय एक रेफरेंस ऑब्जेक्ट लेती है, और हर रेफरेंस में type टैग होता है जो बताता है कि मीडिया कहाँ से आया है।

जहाँ भी रेफरेंस स्वीकार किया जाता है, ये तीनों प्रकार एक-दूसरे की जगह इस्तेमाल किए जा सकते हैं। इसलिए एक ही फ़ील्ड एक रिक्वेस्ट में जनरेशन और अगली में अपलोड किया गया एसेट ले सकती है।

एक जनरेशन को अगली से जोड़ें

generation रेफरेंस को पूरी हो चुकी जनरेशन की ओर इंगित करना ज़रूरी नहीं है। इमेज सबमिट करें, रिस्पॉन्स से ID लें और बिना इंतज़ार किए उसे सीधे वीडियो रिक्वेस्ट में पास करें: API वीडियो को इमेज के पीछे क्यू में रखती है और इमेज पूरी होते ही उसे शुरू कर देती है। दोनों कॉल के बीच कुछ भी अपलोड नहीं होता।

चेन की आखिरी जनरेशन पर webhook सेट करें, फिर इंतज़ार करने के लिए कुछ भी नहीं रहता। दोनों कॉल उनकी जनरेशन क्यू में लगते ही रिटर्न हो जाती हैं, पूरा ग्राफ़ सर्वर-साइड चलता है, और आखिरी जनरेशन टर्मिनल स्टेटस पर पहुँचने के बाद आपके एंडपॉइंट को कॉल किया जाता है।

from elevenlabs import (
    ImageGenerationRequest_Gemini3ProImage,
    ImageReference_Generation,
    VideoGenerationRequest_Veo31FastGenerate001,
    WebhookTarget_All,
)
still = elevenlabs.flows.image.create(
    request=ImageGenerationRequest_Gemini3ProImage(
        prompt="A lighthouse on a cliff at dawn, heavy fog rolling in from the sea",
        aspect_ratio="16:9",
    )
)
# `still` is still pending here. Submitting now queues the video behind it.
clip = elevenlabs.flows.video.create(
    request=VideoGenerationRequest_Veo31FastGenerate001(
        prompt="The fog thickens and the beam sweeps across the water",
        start_frame=ImageReference_Generation(generation_id=still.id),
        duration_secs=8,
        webhook=WebhookTarget_All(),
    )
)
print(clip.id)

सिर्फ आखिरी जनरेशन को webhook की ज़रूरत होती है। इसे इमेज पर भी सेट करने से इंटरमीडिएट रिज़ल्ट के लिए भी इवेंट मिलता है, जो प्रोग्रेस रिपोर्ट करने में उपयोगी है, लेकिन चेन चलाने के लिए इसकी ज़रूरत नहीं है। अन्य जगहों की तरह, इस फ़ील्ड के लिए जनरेशन इवेंट्स को सब्सक्राइब किया हुआ वेबहुक चाहिए; इसे सेट करने के लिए Image & Video वेबहुक्स देखें।

अगर कॉलबैक पाने के लिए कोई एंडपॉइंट नहीं है, तो webhook हटा दें और इसकी बजाय चेन के अंत को पोल करें। इंटरमीडिएट इमेज को फिर भी अलग से पोल करने की ज़रूरत नहीं है — उसकी मॉडैलिटी के इंटरवल पर, सिर्फ आखिरी जनरेशन के लिए एक बार इंतज़ार करें; वीडियो के लिए यह हर 10 सेकंड में एक बार से ज़्यादा नहीं है। पोलिंग गाइडलाइंस देखें।

import time
while True:
    result = elevenlabs.flows.video.get(clip.id)
    if result.status in ("completed", "failed"):
        break
    time.sleep(10)

अधूरे काम को रेफरेंस करने वाली जनरेशन तुरंत बन जाती है और जिन चीज़ों को वह रेफरेंस करती है, उनके पूरे होने तक pending में रहती है। इसे शुरू करने के लिए आपको आगे कोई कार्रवाई नहीं करनी होती। चेन्स किसी भी गहराई और चौड़ाई की हो सकती हैं — एक जनरेशन कई रेफरेंस का इंतज़ार कर सकती है, और उनमें से हर एक खुद भी इंतज़ार कर रहा हो सकता है — इसलिए पूरा ग्राफ़ एक ही बार में सबमिट किया जा सकता है और सिर्फ इसकी लीव्स पर कलेक्ट किया जा सकता है। क्यू में बिताया गया समय जनरेशन के टाइमआउट में नहीं गिना जाता।

अगर रेफरेंस की गई जनरेशन फ़ेल हो जाती है, तो उस पर निर्भर जनरेशन कभी नहीं चलती: वह dependency_failed कारण के साथ फ़ेल हो जाती है और उसके पीछे क्यू में लगी हर चीज़ को भी साथ ले जाती है। कोलैप्स हुई चेन में किसी चीज़ का शुल्क नहीं लगता — जिस जनरेशन का पहले ही भुगतान हो चुका था उसका रिफ़ंड हो जाता है, और जिसकी कीमत किसी ऐसे रेफरेंस आउटपुट पर निर्भर है जो अभी मौजूद नहीं है, जैसे पेंडिंग ऑडियो जनरेशन की अवधि के आधार पर कीमत वाली लिप-सिंक, उसका शुल्क शुरू होने पर ही लिया जाता है। आपके वर्कस्पेस में मौजूद न होने वाली generation_id को क्रिएट कॉल पर ही अस्वीकार कर दिया जाता है, इसलिए टाइपो फ़ेल हुई जनरेशन के रूप में नहीं, बल्कि तुरंत दिख जाता है।

मीडिया को एसेट के रूप में अपलोड करें

जब मीडिया ElevenLabs के बाहर से आता है और आप उसे कई जनरेशन्स में दोबारा इस्तेमाल करना चाहते हैं, तो फ़ाइल को assets API पर अपलोड करें। एसेट्स वर्कस्पेस के होते हैं और आपके डिलीट करने तक बने रहते हैं।

from elevenlabs import ImageReference_Asset, VideoGenerationRequest_Veo31FastGenerate001
with open("lighthouse.png", "rb") as f:
    asset = elevenlabs.assets.create(asset=f, name="lighthouse.png")
print(asset.asset_id)
clip = elevenlabs.flows.video.create(
    request=VideoGenerationRequest_Veo31FastGenerate001(
        prompt="The beam sweeps across the water as the fog thickens",
        start_frame=ImageReference_Asset(asset_id=asset.asset_id),
    )
)

अपलोड रिस्पॉन्स स्टोर किए गए एसेट की जानकारी देता है:

{
  "asset_id": "5xM2KqOnZyce22SPZ9d4",
  "name": "lighthouse.png",
  "mime_type": "image/png",
  "created_at_unix": 1721520000,
  "content_url": "https://storage.googleapis.com/assets/5xM2KqOnZyce22SPZ9d4"
}

content_url लगभग एक घंटे तक मान्य रहने वाला साइन किया हुआ URL है, और अपलोड प्रोसेस होने के दौरान null रहता है। नया URL पाने के लिए एसेट को फिर से फ़ेच करें।

स्टोरेज सीमाएं

अपलोड किए गए एसेट्स वर्कस्पेस की कुल स्टोरेज सीमा में गिने जाते हैं, जो आपके प्लान पर निर्भर करती है:

सिर्फ आपके अपलोड किए गए फ़ाइलें सीमा में गिनी जाती हैं; जनरेट किए गए आउटपुट नहीं। वर्कस्पेस को उसकी सीमा से ऊपर ले जाने वाले अपलोड को फ़ाइल पढ़ने से पहले asset_storage_limit_exceeded एरर के साथ अस्वीकार कर दिया जाता है। जगह खाली करने के लिए उन एसेट्स को डिलीट करें जिनकी अब ज़रूरत नहीं है, या सीमा बढ़वाने के लिए सपोर्ट से संपर्क करें।

एसेट्स मैनेज करें

एसेट्स को नए से पुराने क्रम में लिस्ट करें, वैकल्पिक रूप से नाम के आधार पर फ़िल्टर करें, और पिछले रिस्पॉन्स के कर्सर से रिज़ल्ट्स के पेज देखें। page_size 1 से 100 तक स्वीकार करता है और डिफ़ॉल्ट रूप से 30 है।

page = elevenlabs.assets.list(page_size=20, search="lighthouse")
for asset in page.assets:
    print(asset.asset_id, asset.name, asset.mime_type)
if page.has_more:
    page = elevenlabs.assets.list(page_size=20, search="lighthouse", cursor=page.next_cursor)

ID से एक एसेट को प्राप्त या डिलीट करें। एसेट डिलीट करने से उन जनरेशन्स पर कोई असर नहीं पड़ता जिन्होंने उसे पहले से इस्तेमाल किया है।

asset = elevenlabs.assets.get("5xM2KqOnZyce22SPZ9d4")
elevenlabs.assets.delete("5xM2KqOnZyce22SPZ9d4")

मीडिया को इनलाइन पास करें

inline_base64 रेफरेंस मीडिया को रिक्वेस्ट बॉडी में रखता है, जिससे एक बार इस्तेमाल होने वाले इनपुट के लिए अलग से अपलोड करने की ज़रूरत नहीं पड़ती। फ़ाइल को स्टैंडर्ड base64 अल्फ़ाबेट से एन्कोड करें और उसका MIME टाइप घोषित करें।

import base64
from elevenlabs import ImageGenerationRequest_GptImage2, ImageReference_InlineBase64
with open("headshot.jpg", "rb") as f:
    encoded = base64.b64encode(f.read()).decode()
generation = elevenlabs.flows.image.create(
    request=ImageGenerationRequest_GptImage2(
        prompt="Replace the background with a softly lit studio backdrop",
        images=[
            ImageReference_InlineBase64(
                content_base64=encoded,
                mime_type="image/jpeg",
            )
        ],
    )
)

डिकोड करने के बाद इनलाइन कंटेंट की सीमा प्रति रेफरेंस 25MB है। बड़ी फ़ाइलों को assets API पर रखें, जो बहुत बड़े अपलोड स्वीकार करती है और जिसमें base64 साइज़ पेनल्टी नहीं होती। हर मॉडैलिटी MIME टाइप्स का एक तय सेट स्वीकार करती है:

मॉडल के अनुसार रेफरेंस फ़ील्ड्स

रेफरेंस फ़ील्ड्स के नाम उस भूमिका के आधार पर रखे जाते हैं जो मीडिया निभाता है। start_frame और end_frame वीडियो की सीमा तय करने वाली एकल इमेज हैं, image और audio लिप-सिंक मॉडल के ज़रूरी इनपुट हैं, और बिना विशेषण वाले बहुवचन images, videos, और audios ऐसे फ्री-फ़ॉर्म रेफरेंस मटीरियल हैं जिनसे मॉडल जानकारी लेता है।

किस मॉडल में कौन से फ़ील्ड स्वीकार होते हैं और कौन से कॉम्बिनेशन मान्य हैं, यह हर मॉडल के लिए अलग होता है। end_frame के लिए हमेशा start_frame चाहिए। किसी कंस्ट्रेंट का उल्लंघन होने पर संबंधित फ़ील्ड का नाम बताने वाली वैलिडेशन एरर मिलती है, इसलिए जनरेशन कभी शुरू नहीं होती और उसका कभी शुल्क नहीं लिया जाता।

Veo 3.1

दोनों Veo मॉडल start_frame, end_frame, और images में अधिकतम तीन एंट्री स्वीकार करते हैं। अन्य मॉडलों के विपरीत, images में हर एंट्री रेफरेंस को उसकी भूमिका के साथ रैप करती है:

{
  "images": [
    {
      "image": { "type": "asset", "asset_id": "5xM2KqOnZyce22SPZ9d4" },
      "role": "subject"
    },
    {
      "image": { "type": "asset", "asset_id": "7pQ4LnBvXkR2mT9wYcHd" },
      "role": "style"
    }
  ]
}

subject रेफरेंस इमेज के सब्जेक्ट या सीन एलिमेंट्स को वीडियो में रखता है; style रेफरेंस उसकी विज़ुअल स्टाइल ट्रांसफ़र करता है। रेफरेंस इमेज को start_frame या end_frame के साथ मिलाया नहीं जा सकता और इनके लिए आठ सेकंड की अवधि ज़रूरी है।

Seedance

तीन Seedance 2.0 टियर start_frame, end_frame, अधिकतम 9 images, अधिकतम 3 videos, और अधिकतम 3 audios स्वीकार करते हैं, जिन पर ये कंस्ट्रेंट लागू होते हैं:

• रेफरेंसेज़ को start_frame या end_frame के साथ नहीं मिलाया जा सकता।
• रेफरेंस ऑडियो के लिए कम से कम एक रेफरेंस इमेज या वीडियो चाहिए, उदाहरण के लिए लिप-सिंक चलाने के लिए।
• रेफरेंस फ़ाइलों की कुल संख्या 12 से ज़्यादा नहीं होनी चाहिए।

Seedance 2.5 सीमाओं को बढ़ाकर 30 images, 10 videos, और 10 audios करता है, कुल संख्या की कोई सीमा नहीं रखता, और रेफरेंस ऑडियो के लिए साथ में इमेज या वीडियो की ज़रूरत वाला नियम हटा देता है, इसलिए सिर्फ ऑडियो इनपुट स्वीकार होता है। रेफरेंसेज़ को फिर भी start_frame या end_frame के साथ नहीं मिलाया जा सकता।

GPT Image

GPT Image मॉडल images के साथ mask स्वीकार करते हैं। मास्क के पूरी तरह पारदर्शी क्षेत्र बताते हैं कि पहली रेफरेंस इमेज को कहाँ एडिट किया जा सकता है। रेफरेंस इमेज के बिना मास्क अस्वीकार कर दिया जाता है।

अगले चरण