Instrumente media

Generează imagini și videoclipuri cu peste 40 de modele AI. Apelează întotdeauna get_models mai întâi pentru a vedea modelele disponibile, costurile și dacă un model necesită o imagine de intrare.

Clienți REST HTTP: aceleași limite sunt centralizate în Cerințe modele API (în engleză) și în răspunsul GET /v1/models per model.

#generate_media

Pornește o generare de imagine sau video.

Parametri:

Exemplu (text-to-image):

{
  "prompt": "Un oraș futurist la apus cu mașini zburătoare",
  "model": "nano-banana",
  "generation_type": "text-to-image",
  "aspect_ratio": "16:9",
  "quality": "pro"
}

Exemplu (image-to-video, o imagine de intrare):

{
  "prompt": "Mișcare blândă și subtilă",
  "model": "kling-2-6-image-to-video",
  "generation_type": "image-to-video",
  "source_media_urls": ["https://example.com/your-image.jpg"],
  "aspect_ratio": "16:9",
  "duration": "5s"
}

Răspuns: Include generation_id, status (ex. pending) și adesea estimated_time_seconds și estimated_cost_credits. Interoghează cu get_generation_status până când status este completed sau failed.

Modele care suportă duration:

Pentru modele doar imagine, duration este ignorat.

Modele care suportă negative_prompt:

Celelalte modele ignoră negative_prompt.

Modele care suportă quality (sau echivalent):

Pentru celelalte modele, quality este ignorat.

<a id="tiere-rezolutie"></a>

Tiere de rezoluție (parametrul resolution):

Când să alegi fiecare tier (GPT Image 2):

• 1K — implicit. Folosește pentru postări social, thumbnail-uri, prototipare, preview-uri in-app, orice ≤ 1024 × 1024. Cel mai ieftin; fără probleme de aspect ratio.
• 2K — folosește când clientul are nevoie de un hero web clar, copertă de newsletter, ilustrație in-product la densitate retină. Trebuie să alegi un aspect direcțional (landscape sau portrait).
• 4K — folosește pentru print, out-of-home, bannere, sau orice caz în care utilizatorul cere explicit dimensiunea maximă. Confirmă aspectul cu utilizatorul întâi; 1:1 / auto nu vor funcționa.

Modelele care nu sunt listate ignoră resolution. Pentru familiile video (Seedance, Kling, P-Video, Gemini Omni) rezoluția face parte din model_id-ul variantei concrete — pasează varianta (ex. seedance-2-fast-480p, p-video-1080p, gemini-omni-video-1080p-6s), nu acest parametru.

Limite caractere prompt:

Unele modele impun o lungime maximă a promptului. Depășirea poate returna eroare sau truncare.

Altele pot să nu aibă limită documentată sau să folosească valorile implicite ale serverului.

Limite fișiere de intrare (imagini și video):

Pentru image-to-video și image-to-image, source_media_urls este o listă de URL-uri. Majoritatea modelelor acceptă doar imagini (JPEG, PNG, WebP, de obicei 10 MB max per fișier). Unele modele acceptă și intrări video; când acceptă, se aplică limite de format și mărime (ex. MP4, durată max).

Folosește get_models pentru a confirma input_media_types și capabilitățile pentru un model dat. Vezi Instrumente cont pentru listă modele și prețuri.

Kling 3.0 – elemente (opțional):

Elementele permit referențierea imaginilor sau videoclipurilor în prompt cu @element_name. Trimite kling_elements ca array de obiecte cu name, description și fie element_input_urls (2–4 URL-uri imagine) fie element_input_video_urls (1 URL video). Imaginile de referință pentru fiecare element vin din element_input_urls propriu; image_urls principal poate rămâne gol pentru text-to-video, sau să țină cadre opționale de start/end pentru image-to-video. Fiecare element necesită titlu (name) și descriere. Imagini element: JPG/PNG, min 300×300px, max 10MB fiecare. Video element: MP4/MOV, max 50MB.

Seedance 1.5 Pro – două moduri (verifică generation_type înainte de a folosi imagini):

Seedance 2 (ByteDance) – două familii de modele, două moduri, referințe multimodale:

Seedance 2 este livrat pe Kubeez ca două familii de modele separate — seedance-2-fast (ieftin, rapid) și seedance-2 (standard, calitate mai mare). Fiecare familie expune model_ids concrete per rezoluție și combinație cu video de referință; pasează varianta completă (ex. seedance-2-fast-480p, seedance-2-720p-video-ref) — pasarea doar a etichetei de familie întoarce o eroare variant_required cu opțiunile disponibile. Ambele tiere suportă rezoluțiile 480p și 720p (nu există 1080p), durată întreg între 4 și 15 secunde, și aspect ratios 1:1, 4:3, 3:4, 16:9, 9:16, 21:9 și adaptive. Prompt-ul maxim este 2.500 de caractere. Audio-ul se comută prin generate_audio (implicit true) și este gratuit — spre deosebire de Kling 3.0, care aplică un surcharge pentru audio.

Două moduri:

Limite stricte (aplicate ca erori 400):

• 3 videouri de referință → too_many_videos

• 3 clipuri audio de referință → too_many_audios

• 9 imagini de referință → too_many_images

• Durata combinată a videourilor de referință > 15s → respinsă
• Durata combinată a clipurilor audio de referință > 15s → respinsă
• Un singur fișier video sau audio de referință mai lung de 15s → respins

Două căi de facturare (important):

Seedance 2 are două formule de cost, alese în funcție de prezența sau absența unui video de referință:

• Fără video de referință:

  credits = output_s × rate/s
  

• Cu video de referință (ruta providerului upstream):

  credits = (ref_s + output_s) × rate/s
  

  unde ref_s este suma duratelor tuturor videourilor de referință, limitată la 15 secunde per cerere.

Notă importantă pentru utilizatorii MCP și REST API: Backend-ul nu poate interoga durata unui video de la distanță dintr-un URL, așa că, pentru cererile cu video de referință primite prin MCP sau REST API, facturează cel mai pesimist caz (15 secunde) pentru ref_s. Web UI-ul Kubeez măsoară durata local și facturează valorile exacte. Pentru workflow-uri sensibile la cost cu clipuri de referință scurte, recomandăm să folosești web UI-ul.

Tarife per secundă, în timp real (extrase din catalogul ai_models_config — mereu la zi):

Gemini Omni Video — modelul multi-modal Google:

Gemini Omni Video produce ieșire video cu audio built-in (29 de voci) și acceptă intrări multi-modale (text, referințe de imagine, un singur video de referință opțional). Modelul vine ca 15 variante concrete — alege-o pe cea care se potrivește rezoluției și duratei dorite. 720p și 1080p au același preț; 4K este un tier de preț separat.

Id-uri variantă (pasate la generate_media ca model):

Variantele video-ref preiau durata din clipul sursă tăiat (se folosesc primele 10s; fără parametri de trim expuși). Variantele bazate pe durată acceptă 1–7 referințe de imagine; variantele video-ref acceptă 1 clip sursă (consumă 2 sloturi) + până la 5 referințe de imagine.

Tarifare flat per task. Tarife în timp real (720p și 1080p împart fiecare rând — Google le facturează identic):

Parametri specifici Gemini Omni:

Media sursă (source_media_urls): 7 sloturi de referință în total. Un singur video de referință consumă 2 sloturi; fiecare character_id consumă 1 slot; imaginile umplu restul. Maxim 1 video pe cerere; pasarea unui URL video necesită o variantă -video-ref (variantă de durată + video → variant_mismatch). Fereastra clipului-driver este implicit primele 10 secunde; suprascrie cu video_trim_start_s / video_trim_end_s. URL-urile de fișiere audio nu sunt acceptate (returnează unsupported_audio_url); folosește voice_id în schimb.

Tool-uri companion (folosește-le alături de generările Gemini Omni):

Exemplu de cerere (1080p, 6s, vertical, refolosind un personaj salvat + voce aleasă):

{
  "model": "gemini-omni-video-1080p-6s",
  "prompt": "Un barista face un espresso perfect, povestește procesul",
  "aspect_ratio": "9:16",
  "voice_id": "kore",
  "character_ids": ["char_4f2a9b7c"],
  "source_media_urls": ["https://media.kubeez.com/cafe-shot.jpg"]
}

Audio la video (două concepte):

1. capabilities.video_audio în get_models — dacă ieșirea are sunet:
   • included — ieșirea include de obicei pistă audio fără parametrul sound (ex. Veo, Wan, Grok, Kling 2.5 image-to-video, Motion Control, Gemini Omni Video — acesta expune parametrul voice_id pentru alegerea uneia dintre cele 29 de voci built-in).
   • toggle_via_sound_param — audio generat se pornește/oprește cu sound: true / false (Kling 2.6, Kling 3.0, Seedance 1.5 Pro, Seedance 2). Pentru Seedance 2 comutatorul este gratuit (implicit true); pentru celelalte modele prețul poate diferi. Kling 3.0 rutează sound: true către rânduri dedicate -audio în catalog — continui să folosești kling-3-0-std / kling-3-0-pro ca model id și doar comuți sound; serverul alege rândul cu tariful corect. Tarife în timp real:

Tarife per secundă de Motion Control (Kling 3.0 și Kling 2.6):

• silent — fără audio generat (doar Seedance 1.0 / v1-pro-fast-i2v).

2. supports_sound — înseamnă doar că API-ul acceptă comutatorul sound pentru acel model; nu înseamnă că celelalte modele video sunt fără sunet; majoritatea au video_audio: included.

Modelele doar imagine ignoră sound.

#API REST: URL-uri pentru fișiere locale sau din browser

Dacă folosești API-ul HTTP (POST /v1/generate/media) și intrările sunt fișiere pe disc sau selectate în browser—nu URL-uri publice deja—încarcă mai întâi fiecare fișier cu POST /v1/upload/media. Folosește valorile din urls ca source_media_urls.

<a id="trim_video"></a>

#trim_video

Taie o fereastră din orice URL video accesibil public și găzduiește clipul tăiat. Kubeez gestionează trim-ul server-side și returnează un url public pe care îl pasezi direct la generate_media ca valoare în source_media_urls.

Când să folosești acest tool:

• Video-ul sursă al utilizatorului este mai lung decât limita modelului pentru clipul de referință și vrei rezultate deterministe în loc să te bazezi pe trim-ul providerului.
• Vrei să folosești o fereastră specifică dintr-un asset mai lung (ex. „folosește secundele 5–12, nu primele 10").
• Înlănțuiești mai multe generări și vrei un singur URL canonic tăiat reutilizabil în mai multe apeluri.

Limite per model (sari peste trim când sursa deja se încadrează):

Parametri:

Returnează: { url, size_bytes, duration_s, start_s, end_s, elapsed_s }. url este un link public găzduit Kubeez care indică spre bucket-ul media-inputs din Supabase storage, safe de folosit ca valoare source_media_urls. Clipurile tăiate stau în același bucket cu inputurile încărcate de utilizator și împart aceeași curățare automată săptămânală — tratează-le ca efemere, nu ca asset permanent.

Flux tipic (Gemini Omni Video cu sursă lungă de la utilizator):

1. get_upload_url(model_id="gemini-omni-video-1080p-video-ref")
       → pagină upload presemnată
2. (utilizatorul încarcă clipul de 25s prin link)
3. get_upload_session(token) → { media_urls: ["https://.../source.mp4"] }
4. trim_video(source_url=media_urls[0], start_s=5, end_s=15)
       → { url: "https://.../trims/<uuid>.mp4", duration_s: 10 }
5. generate_media(
       model="gemini-omni-video-1080p-video-ref",
       prompt="...",
       source_media_urls=[<url-ul tăiat>]
   )

Trim standalone (URL-ul sursă e deja public — fără pas de upload):

trim_video(source_url="https://media.kubeez.com/<asset>.mp4", start_s=0, end_s=8)
       → { url, duration_s: 8 }
generate_media(model="kling-3-0-motion-control-1080p", source_media_urls=[<imagine>, <url-ul tăiat>], ...)

Erori:

Exemplu de cerere:

{
  "source_url": "https://media.kubeez.com/u123/uploads/long-take.mp4",
  "start_s": 5.2,
  "end_s": 14.7
}

Exemplu de răspuns:

{
  "url": "https://<project>.supabase.co/storage/v1/object/public/media-inputs/u123/trims/abc.mp4",
  "size_bytes": 1245678,
  "duration_s": 9.5,
  "start_s": 5.2,
  "end_s": 14.7,
  "elapsed_s": 1.83
}

Precizie pe frame: -c copy aliniază startul efectiv la cel mai apropiat keyframe precedent (deplasare ≤ 1 GOP, de obicei ≤ 1s). Comportament identic cu stream-copy-ul nativ MP4 din web UI. Pentru tăieri precise pe frame, re-encodează sursa în prealabil — compromisul fiind o operațiune mai lentă și cu pierderi, pe care o evităm deliberat aici.

Nu păstra output-ul: URL-ul indică spre bucket-ul media-inputs care e curățat săptămânal. Dacă ai nevoie ca clipul tăiat să supraviețuiască următoarei generări, folosește manage_library(kind="asset", action="add", ...) pentru a-l copia în Biblioteca de Assets permanentă a utilizatorului.

#get_generation_status

Verifică statusul unei generări media și obține URL-urile de output când e gata.

Parametri:

Răspuns: Include status (pending, queued, processing, completed, failed), progress și când e finalizat un array outputs cu url, thumbnail_url, optimized_url, media_type, dimensiuni etc.

#get_generation_estimate

Obține un timp estimat de procesare în funcție de parametri pentru un model și opțiuni dat (nu se pornește niciun job). Pentru o durată estimată per model într-un singur apel, folosește get_models; fiecare model include estimated_time_seconds. Folosește get_generation_estimate când ai nevoie de o estimare care depinde de lungimea promptului, durată sau alți parametri.

Parametri:

Răspuns: Timp estimat (și opțional încredere/dimensiune eșantion) pentru a seta așteptările utilizatorului înainte de generate_media.

#Reguli modele

• Text-to-image și text-to-video: Nu trimite source_media_urls (decât dacă modelul suportă o imagine de referință opțională). Excepție: seedance-1-5-pro în mod text-to-video acceptă 0–1 imagini opționale.
• Image-to-video și image-to-image: Trimite URL-uri imagine (și când e suportat, video) în source_media_urls. Majoritatea modelelor au nevoie doar de imagini; unele (ex. Kling 2.6 Motion Control) necesită 1 imagine + 1 video. seedance-1-5-pro în mod image-to-video necesită exact 2 imagini (cadru start + final). Respectă limitele de intrare ale fiecărui model de mai sus.
• Audio video: Folosește capabilities.video_audio din get_models. included — audio fără parametrul sound. toggle_via_sound_param — folosește sound doar când supports_sound e true. silent — fără audio generat (doar Seedance 1.0). Nu deduce „fără audio” doar din supports_sound: false.
• Folosește get_models pentru a vedea ce modele suportă ce tipuri de generare, input_media_types (ex. image, video) și numărul necesar de intrări.

Vezi Limitări pentru limite de rată și credite. Pentru un singur tabel cu valorile implicite API (prompt, intrări, durată, flag-uri), vezi Cerințe modele API.