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_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.

Flare vs Sunburst (GPT Image 2.5):

• gpt-image-2-5-flare este banda rapida. Alegerea implicita pentru explorare, iterare pe prompt si generare in volum.
• gpt-image-2-5-sunburst este banda de calitate. Mai lenta, detaliu mai curat si tipografie mai stabila. Foloseste-o pentru randari finale si tipar 4K.
• Ambele benzi accepta aceiasi parametri, aceleasi 16 imagini de referinta, acelasi prompt de 20.000 de caractere si aceleasi 13 rapoarte de aspect, si costa la fel la fiecare nivel de rezolutie.
• Niciuna dintre benzi nu accepta 4:5. Foloseste nano-banana-2 cand o plasare il cere.

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 trei familii de modele separate — seedance-2-fast (ieftin, rapid), seedance-2 (standard, calitate mai mare) și seedance-2-mini (cel mai ieftin, ~50% sub Fast, doar 480p/720p). 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-mini-720p, 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, 720p și 1080p (ids de variantă seedance-2-480p / -720p / -1080p, fiecare și cu forma -video-ref), 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 4.000 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):

#Gemini Omni 1.1 Flash

gemini-omni-flash-* este versiunea 1.1 a aceleiași familii, cu funcția ei edge și cu propriile rânduri de preț. Citește aceleași referințe de imagine, video și personaj și folosește același catalog de 29 de voci. Ce adaugă:

• un nivel 360p. Spre deosebire de 1.0, fiecare rezoluție are aici rândul ei, deci 360p este și cea mai rapidă randare și cea mai ieftină, iar 1080p costă mai mult decât 720p
• un mod primul și ultimul cadru: trimite cadrul de start în source_media_urls și cadrul de final în last_frame_url. Modul este exclusiv — nu poate fi combinat cu imagini de referință suplimentare, cu un video de referință sau cu character_ids, iar trimiterea lor împreună întoarce variant_mismatch.

Id-uri de variantă (se pasează la generate_media ca model):

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.

#remove_background

Decupează subiectul dintr-o imagine. Output-ul e un PNG cu fundal transparent real (alpha), motiv pentru care nu ceri niciodată unui model de imagine „fundal transparent”: modelele de imagine coc un fill alb sau de tip tablă de șah în pixeli. Nu primește niciun prompt: e o operație pe o imagine existentă, nu un model generate_media.

Se taxează fix per imagine. Apelează estimate cu model: "remove-background" pentru prețul exact și confirmă cu utilizatorul înainte.

Parametri:

Răspuns: { generation_id, status: "pending" }. Consultă get_status până la completed; URL-ul de output e PNG-ul decupat.

#regenerate

Re-rulează o generare media anterioară cu suprascrieri opționale. Promptul, modelul, aspect ratio, source_media_urls și durata rândului original sunt reutilizate dacă nu le suprascrii. Doar media — muzica, separarea și dialogul trebuie apelate din nou din instrumentul original.

Costul e identic cu o generare nouă, deci confirmă cu utilizatorul înainte, mai ales pentru modelele video taxate pe durată.

Parametri:

#get_status

Consultă orice job după id — generare media, generare muzică sau separare audio. Serverul dispecerizează automat după id, deci un singur instrument acoperă toate trei.

Parametri:

Răspuns: kind (ce a rezolvat id-ul), status (pending, queued, processing, completed, failed), progress și, în funcție de kind, un array outputs (url, thumbnail_url, optimized_url, media_type, dimensiuni), un array songs, sau vocals_url + instrumental_url. error_message la eșec.

#estimate

Previzualizează și costul în credite și timpul de procesare al unei generări, fără să deducă nimic. Nu pornește niciun job. Obligatoriu pentru orice model taxat pe durată: citează numărul utilizatorului și așteaptă confirmarea, pentru că o generare finalizată nu poate fi rambursată.

Parametri:

Răspuns: credits (estimated_credits, mode, rate_per_second, explanation, pessimistic) și time (estimated_seconds, source). Când credits.pessimistic e true suma reală taxată poate fi mai mică — pune utilizatorul să re-încarce prin get_upload_url ca durata să fie măsurată, apoi estimează din nou.

#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.