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, Sora, P-Video) rezoluția face parte din model_id-ul variantei concrete — pasează varianta (ex. seedance-2-fast-480p, p-video-1080p), 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):

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, Sora, Wan, Grok, Kling 2.5 image-to-video, Motion Control).
   • 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.

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