Vai al contenuto

Documenti per sviluppatori UlazAI

Google Veo 3.1 Generazione video API

Google Veo 3.1 Generazione video API

Genera video con Veo 3.1 utilizzando i controlli del fotogramma supportati e il flusso di lavoro relativo allo stato del lavoro.

✨ NOVITÀ: Veo 3.1 Lite, Fast e Quality sono disponibili con il controllo del primo e dell'ultimo fotogramma.

✨ Caratteristiche Veo 3.1

✅ Tre opzioni di modello - Leggero, veloce e di qualità

✅ Controllo del fotogramma - Imposta le immagini del primo e dell'ultimo fotogramma

✅ Da testo a video e immagine in video

✅ Video di 8 secondi con audio nativo

✅ Supporto filigrana - Aggiungi testo del marchio

✅ Modalità fallback opzionale per un secondo tentativo di modello

✅ Traduzione automatica all'inglese

✅ Rapporti d'aspetto multipli (16:9, 9:16, Automatico)

💰 Prezzi

💸Veo 3.1 Lite

40 crediti

Modalità dal miglior rapporto qualità-prezzo

Testo in video + immagine in video

⚡Veo 3.1 Fast

100 crediti

~ $ 0,92 per video

Il tempo varia in base alla coda

💎 Qualità Veo 3.1

220 crediti

~ $ 2,31 per video

Il tempo varia in base alla coda

🛡️ Modalità di riserva

+200 crediti

Componente aggiuntivo facoltativo

Il fallback non garantisce il successo

POST /veo31/api/generate/

Genera video Veo 3.1

Crea un video di 8 secondi con Google Veo 3.1 utilizzando testo prompt e cornici di immagine opzionali.

Richiedi corpo

{
  "prompt": "A golden retriever running through a field of flowers at sunset",
  "model": "veo3_lite",           // Options: "veo3_lite", "veo3_fast", "veo3"
  "aspectRatio": "16:9",          // Options: "16:9", "9:16", "Auto"
  "imageUrls": [],                // Optional: Array of 1-2 image URLs
  "seeds": 42069,                 // Optional: 10000-99999 for reproducible results
  "watermark": "UlazAI",          // Optional: Max 50 characters
  "enableFallback": false,        // Optional fallback attempt; check current extra credits
  "enableTranslation": true       // Optional: Auto-translate to English
}

Parametri

prompt * (stringa)

Descrizione testuale del video da generare. Massimo 5000 caratteri. Sii descrittivo riguardo alle azioni, ai movimenti della telecamera e all'atmosfera.

modello * (stringa)

Modello da utilizzare: veo3_lite (40 crediti), veo3_fast (100 crediti), o veo3 (220 crediti)

rapporto d'aspetto (stringa)

Proporzioni video: 16:9 (paesaggio), 9:16 (ritratto), Auto (automatico). Predefinito: 16:9

URL immagine (matrice)

Array opzionale di 1-2 URL di immagini per il controllo del frame:
• 1 immagine: il video è incentrato su questa immagine
• 2 immagini: transizioni video dal primo all'ultimo fotogramma
Massimo 10 MB per immagine, solo JPG/PNG

semi (intero)

Seme opzionale per risultati riproducibili. Intervallo: 10000-99999

filigrana (stringa)

Testo della filigrana opzionale da sovrapporre al video. Massimo 50 caratteri. Ottimo per il marchio.

abilitare Fallback (booleano)

Abilita un tentativo facoltativo del modello di backup. Controlla il costo attuale del credito extra; il fallback non garantisce il completamento. Predefinito: false

abilitaTraduzione (booleano)

Traduci automaticamente prompt in inglese per ottenere i migliori risultati. Supporta tutte le lingue. Predefinito: true

Risposta positiva (201)

{
  "success": true,
  "data": {
    "task_id": "veo31_abc123def456",
    "status": "processing",
    "model": "veo3_fast",
    "credits_charged": 100,
    "credits_remaining": 900,
    "estimated_time": "varies by queue",
    "message": "Veo 3.1 video generation started successfully"
  }
}

Risposta all'errore (400)

{
  "success": false,
  "error": "Insufficient credits. Required: 100, Available: 50"
}

Esempio cURL: testo in video

curl -X POST https://ulazai.com/veo31/api/generate/ \
  -H "Authorization: Token YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A golden retriever running through a field of flowers at sunset, slow motion, cinematic lighting",
    "model": "veo3_fast",
    "aspectRatio": "16:9",
    "watermark": "MyBrand",
    "enableTranslation": true
  }'

Esempio cURL: conversione da immagine a video con controllo frame

curl -X POST https://ulazai.com/veo31/api/generate/ \
  -H "Authorization: Token YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "The character slowly turns their head and smiles at the camera",
    "model": "veo3",
    "aspectRatio": "16:9",
    "imageUrls": ["https://your-domain.com/start-frame.jpg"],
    "seeds": 42069,
    "enableFallback": true
  }'

Esempio di Python

import requests
import time

API_KEY = "your_api_key_here"
BASE_URL = "https://ulazai.com"

# Generate video
response = requests.post(
    f"{BASE_URL}/veo31/api/generate/",
    headers={
        "Authorization": f"Token {API_KEY}",
        "Content-Type": "application/json"
    },
    json={
        "prompt": "A serene mountain lake at sunrise with mist rising from the water",
        "model": "veo3_fast",
        "aspectRatio": "16:9",
        "watermark": "MyBrand"
    }
)

data = response.json()
if data["success"]:
    task_id = data["data"]["task_id"]
    print(f"Task created: {task_id}")

    # Poll for completion
    while True:
        status_response = requests.get(
            f"{BASE_URL}/veo31/api/status/{task_id}/",
            headers={"Authorization": f"Token {API_KEY}"}
        )

        status_data = status_response.json()
        if status_data["data"]["status"] == "completed":
            video_url = status_data["data"]["video_url"]
            print(f"Video ready: {video_url}")
            break
        elif status_data["data"]["status"] == "failed":
            print(f"Generation failed: {status_data['data']['error_message']}")
            break

        time.sleep(5)  # Poll every 5 seconds
else:
    print(f"Error: {data['error']}")
OTTIENI /veo31/api/status/<task_id>/

Controlla lo stato della generazione

Controlla lo stato di un'attività di generazione video Veo 3.1.

Risposta - Elaborazione

{
  "success": true,
  "data": {
    "task_id": "veo31_abc123def456",
    "status": "processing",
    "model": "veo3_fast",
    "prompt": "A golden retriever running through flowers",
    "credits_charged": 100
  }
}

Risposta: completata

{
  "success": true,
  "data": {
    "task_id": "veo31_abc123def456",
    "status": "completed",
    "video_url": "https://cdn.ulazai.com/videos/veo31_abc123.mp4",
    "thumbnail_url": "https://cdn.ulazai.com/videos/veo31_abc123_thumb.jpg",
    "resolution": "1080p",
    "duration": 8,
    "aspect_ratio": "16:9",
    "fallback_used": false,
    "credits_charged": 100
  }
}

Risposta: non riuscita

{
  "success": true,
  "data": {
    "task_id": "veo31_abc123def456",
    "status": "failed",
    "error_message": "Content policy violation. Enable fallback mode to retry.",
    "credits_refunded": 100
  }
}

Esempio di arricciatura

curl -X GET https://ulazai.com/veo31/api/status/veo31_abc123def456/ \
  -H "Authorization: Token YOUR_API_KEY"
POST /veo31/api/upload-frame/

Carica l'immagine del fotogramma

Carica un'immagine per il controllo del fotogramma (primo o ultimo fotogramma). Restituisce un URL da utilizzare nell'endpoint di generazione.

Richiesta (multipart/form-data)

Content-Type: multipart/form-data

image: (binary file data)

Parametri

immagine * (file)

File immagine da caricare. Massimo 10 MB. Formati supportati: JPG, PNG. Risoluzione consigliata: 1920x1080 o superiore.

Risposta positiva (200)

{
  "success": true,
  "url": "https://cdn.ulazai.com/uploads/frame_abc123.jpg",
  "message": "Image uploaded successfully"
}

Esempio di arricciatura

curl -X POST https://ulazai.com/veo31/api/upload-frame/ \
  -H "Authorization: Token YOUR_API_KEY" \
  -F "image=@/path/to/your/image.jpg"

Codici di stato

200 ok - Richiesta riuscita

201 Creato - Attività di generazione creata correttamente

400 Richiesta errata - Parametri non validi o crediti insufficienti

401 Non autorizzato - Chiave API mancante o non valida

404 Non trovato - ID attività non trovato

413 Carico utile troppo grande - L'immagine supera il limite di 10 MB

429 Troppe richieste - Limite di velocità superato

500 Errore interno del server - Errore del server, contattare l'assistenza

Valori dello stato dell'attività

in sospeso - Attività creata, in attesa di iniziare

elaborazione - Il video è in fase di generazione

completato - Generazione video riuscita, video_url disponibile

fallito - Generazione fallita, crediti rimborsati automaticamente

💡 Migliori pratiche

Utilizzare prompt descrittivi

Includi dettagli su azioni, movimenti della telecamera, illuminazione e atmosfera. Esempio: "primo piano al rallentatore di gocce d'acqua che cadono, retroilluminato da un tramonto dorato, profondità di campo ridotta"

Abilita il fallback per i contenuti importanti

Per lavori importanti, considera il tentativo di fallback opzionale e gestisci comunque le generazioni non riuscite o rifiutate nel tuo flusso di lavoro.

Usa i semi per dare consistenza

Se devi rigenerare video simili, utilizza lo stesso valore seed (10000-99999) per risultati più coerenti.

Controllo del frame per il branding

Carica 1 immagine per centrare il video attorno ad essa o 2 immagini per creare una transizione fluida. Perfetto per video di personaggi o prodotti coerenti.

Sondaggio dello stato in modo efficiente

Sondaggio ogni 5 secondi per la modalità Veloce, 10 secondi per la modalità Qualità. Non effettuare sondaggi più frequentemente per evitare limiti di frequenza.

📝 Esempio Prompts

✅ Buono Prompt

"Un'aquila maestosa vola sopra le montagne innevate all'alba, la luce dorata che ne illumina le ali, una ripresa al rallentatore dal basso, composizione cinematografica"

✅ Buono Prompt

"Primo piano di un barista che versa latte art, vapore che sale dalla tazza, illuminazione calda del bar, profondità di campo ridotta, prospettiva con obiettivo macro"

❌ Povero Prompt

"aquila in volo"

Troppo vago: mancano dettagli su ambientazione, movimento, angolazione della telecamera

Hai bisogno di aiuto?

Hai problemi con Veo 3.1 API? Siamo qui per aiutarti!