इमेज और वीडियो क्विकस्टार्ट

इमेज और वीडियो API एसिंक्रोनस है। आप जनरेशन सबमिट करते हैं और उसके पूरा होने पर साइन किए गए URL से नतीजा डाउनलोड करते हैं। इमेज और वीडियो के लिए अलग एंडपॉइंट हैं, लेकिन दोनों के लिए रिक्वेस्ट और रिस्पॉन्स का ढाँचा एक जैसा है।

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

इमेज जनरेट करें

ELEVENLABS_API_KEY=<your_api_key_here>

pip install elevenlabs
pip install python-dotenv

# example.py
import os
from dotenv import load_dotenv
from elevenlabs import ImageGenerationRequest_Gemini3ProImage, WebhookTarget_All
from elevenlabs.client import ElevenLabs
load_dotenv()
elevenlabs = ElevenLabs(api_key=os.getenv("ELEVENLABS_API_KEY"))
generation = elevenlabs.flows.image.create(
    request=ImageGenerationRequest_Gemini3ProImage(
        prompt="A corgi in a tiny lifeguard chair on a sunlit beach at golden hour, photorealistic",
        aspect_ratio="16:9",
        resolution="2K",
        webhook=WebhookTarget_All(),
    )
)
print(generation.id, generation.status)

{
  "id": "JWr5N6X9ZTqf8jD2LmQb",
  "status": "pending"
}

import time
import requests
while True:
    result = elevenlabs.flows.image.get(generation.id)
    if result.status in ("completed", "failed"):
        break
    time.sleep(2)
if result.status == "failed":
    raise RuntimeError(f"{result.failure_reason}: {result.error_message}")
with open("corgi.png", "wb") as f:
    f.write(requests.get(result.content_url).content)

{
  "id": "JWr5N6X9ZTqf8jD2LmQb",
  "status": "completed",
  "content_url": "https://storage.googleapis.com/generations/JWr5N6X9ZTqf8jD2LmQb",
  "content_mime_type": "image/png"
}

python example.py

वीडियो जनरेट करें

वीडियो जनरेशन में flows.video इस्तेमाल होता है और यह उसी सबमिट-और-कलेक्ट पैटर्न का पालन करता है। वीडियो में कई मिनट लग सकते हैं, इसलिए यह उदाहरण नतीजे का इंतज़ार करने के बजाय webhook के साथ वेबहुक डिलीवरी चुनता है।

from elevenlabs import VideoGenerationRequest_Veo31FastGenerate001, WebhookTarget_All
generation = elevenlabs.flows.video.create(
    request=VideoGenerationRequest_Veo31FastGenerate001(
        prompt="A corgi rides a tiny surfboard across a sunlit wave at golden hour, cinematic",
        duration_secs=8,
        aspect_ratio="16:9",
        resolution="1080p",
        generate_audio=True,
        webhook=WebhookTarget_All(),
    )
)
print(generation.id)

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

नतीजे पाना

वेबहुक और पोलिंग एक ही payload लौटाते हैं, इसलिए चुनाव इस बात का है कि आप उसके लिए कैसे इंतज़ार करते हैं, न कि आपको क्या मिलता है।

जहाँ भी संभव हो, वेबहुक का इस्तेमाल करें। जब callback पाने के लिए आपके पास कोई जगह न हो, तब पोलिंग चुनें और ऐसा करने पर नीचे दिए गए intervals का पालन करें।

वेबहुक टारगेट चुनना

webhook दो forms स्वीकार करता है। WebhookTarget_All generation events को subscribed हर वेबहुक तक पहुँचता है, और यह सही डिफ़ॉल्ट है क्योंकि वेबहुक rotate या replace होने पर भी काम करता है। WebhookTarget_Ids डिलीवरी को खास वेबहुक तक सीमित करता है, जब एक workspace कई consumers को भेजता हो और किसी job को उनमें से सिर्फ़ एक तक पहुँचना हो:

from elevenlabs import WebhookTarget_Ids
webhook = WebhookTarget_Ids(ids=["Q8mVr2LpXcT4nB6yJdKw"])

हर ID पहले से generation events को subscribed होनी चाहिए; unsubscribed वेबहुक का नाम देने पर उसे चुपचाप अनदेखा करने के बजाय request reject हो जाती है। डिलीवर किया गया payload GET endpoint के लौटाए गए payload जैसा ही होता है, इसलिए एक के लिए लिखा handler दूसरे के लिए भी काम करता है। वेबहुक गाइड में वेबहुक configure करना, signature verify करना और event handle करना बताया गया है।

पोलिंग दिशानिर्देश

किसी generation का runtime model, resolution और वीडियो के लिए duration पर निर्भर करता है, इसलिए fixed loop के बजाय अपने अनुरोध के अनुसार interval पर poll करें:

• इमेज: हर 2 सेकंड में एक बार से ज़्यादा poll न करें। ज़्यादातर कुछ सेकंड में पूरे हो जाते हैं।
• वीडियो: हर 10 सेकंड में एक बार से ज़्यादा poll न करें। सेकंड नहीं, मिनटों की अपेक्षा रखें और interval को duration_secs और resolution के हिसाब से बढ़ाएं।

दोनों पर दो नियम लागू होते हैं। generation में ज़्यादा समय लगने पर back off करें — interval को दोगुना करके करीब एक मिनट तक ले जाने से धीमा generation सैकड़ों requests में नहीं बदलेगा। और loop की एक सीमा रखें, ताकि अटका हुआ generation अनंत loop के बजाय आपके अपने code में timeout के रूप में खत्म हो।

इससे तेज़ पोलिंग से आपको कुछ नहीं मिलता: सिर्फ़ दो बार पूछने से generation का status जल्दी नहीं बदलता। लगातार बहुत तेज़ पोलिंग पर 429 responses मिल सकते हैं, जिन्हें आपको exponential backoff के साथ handle करना चाहिए।

Generation लाइफ़साइकल

एक generation चार statuses से गुजरता है। दो terminal statuses में अलग-अलग fields होते हैं, इसलिए बाकी response पढ़ने से पहले status के आधार पर branch करें।

Failures हैंडल करना

एक failed generation, पढ़ने योग्य error_message के साथ failure_reason category रिपोर्ट करता है:

{
  "id": "JWr5N6X9ZTqf8jD2LmQb",
  "status": "failed",
  "failure_reason": "moderated",
  "error_message": "The prompt was rejected by content moderation. You were not charged for this generation."
}

Failed generations के लिए शुल्क नहीं लिया जाता। जिन parameter समस्याओं का पहले ही पता लगाया जा सकता है — जैसे unsupported field, model की allowed range से बाहर का value या reference inputs का अमान्य combination — उन्हें generation शुरू होने से पहले create request ही reject कर देती है।

कीमत

Generations के लिए credits में शुल्क लिया जाता है। लागत model, आपके चुने हुए parameters जैसे resolution और duration, और दिए गए inputs पर निर्भर करती है। API के ज़रिए generation की लागत उतनी ही होती है जितनी ElevenLabs ऐप में होती है, जहाँ submit करने से पहले लागत दिखाई जाती है। किसी खास model और setting combination की लागत कैसे दिखाई जाती है, इसके लिए playground में Image & Video देखें।

अपनी generations की सूची देखें

हर endpoint उससे बनाई गई generations की सूची देता है, सबसे नई पहले। नतीजे आपके workspace और इस API तक सीमित होते हैं, इसलिए ElevenLabs ऐप में बनाई गई generations दिखाई नहीं देतीं।

page = elevenlabs.flows.image.list(page_size=20, status="completed")
for item in page.generations:
    print(item.id, item.content_url)
while page.has_more:
    page = elevenlabs.flows.image.list(page_size=20, status="completed", cursor=page.next_cursor)
    for item in page.generations:
        print(item.id, item.content_url)

page_size 1 से 100 तक स्वीकार करता है और डिफ़ॉल्ट रूप से 30 होता है। सिर्फ़ किसी एक lifecycle state की generations लौटाने के लिए status और सिर्फ़ एक model की generations लौटाने के लिए model_id दें। next_cursor को opaque मानें: उसका सटीक value वापस दें और has_more के false होने पर रुक जाएं।

उपलब्ध मॉडल

API, ElevenLabs ऐप में उपलब्ध models के एक subset को उपलब्ध कराता है। हर model सिर्फ़ उसके लिए सूचीबद्ध parameters स्वीकार करता है — किसी दूसरे model द्वारा supported field भेजने पर validation error मिलता है।

इमेज मॉडल

GPT Image 2.5 models quality के लिए low, medium, high, xhigh और max values स्वीकार करते हैं, और diff़ॉल्ट रूप से high होता है। GPT Image 2 की अधिकतम value high है और डिफ़ॉल्ट रूप से medium होता है।

वीडियो मॉडल

model capabilities, availability और pricing के लिए Image & Video overview देखें।

अगले चरण