Cum funcționează

Serverul MCP rulează fiecare generare ca un job asincron: o pornești, apoi consulți statusul până se termină. Clientul gestionează polling-ul automat — pagina asta e pentru cine construiește unul propriu sau debughează fluxul.

#Fluxul canonic media

Pentru orice instrument care primește un fișier de la utilizator (editare imagine, motion control, lip-sync, subtitrări, separare, reclame):

1. get_upload_url(model_id=X) — întoarce un link temporar de browser. Trimite-l utilizatorului ca atare.
2. Utilizatorul încarcă din browser. Kubeez detectează durata / dimensiunile pe partea de client și le scrie în tabelul de metadata.
3. get_upload_session(token) — întoarce URL-urile publice plus duration_seconds per fișier și un flag billing_readiness (exact / pessimistic_fallback).
4. estimate_generation_cost(model, reference_*_seconds=…) — previzualizare exactă a prețului, fără credite deduse. Spune-i utilizatorului.
5. generate_*(...) — doar după ce utilizatorul confirmă.

Modelele cu tarif fix (Nano Banana, Flux, Imagen, Z-Image, Seedream, Logo Maker, reclame, muzică, voce) sar peste pasul 4 — citează cost_per_generation din get_models direct.

#Fluxuri pe instrument

#Imagini și video

1. Opțional: get_models → alege un model_id și citește capabilitățile.
2. Opțional: get_balance ca să verifici creditele.
3. generate_media(prompt, model, …) → întoarce generation_id.
4. Consultă get_generation_status(id) la fiecare 5s după o așteptare inițială scurtă (~10s pentru imagine, ~30s pentru video scurt).
5. Când status e completed, citește outputs[] — fiecare element are url, thumbnail_url, opțional optimized_url.

#Muzică

1. generate_music(prompt, …) → generation_id.
2. Consultă get_music_status(id) după ~30s, apoi la fiecare 5s.
3. Când e gata, citește songs[] — fiecare cu audio_url, stream_url, cover_image_url.

#Subtitrări

1. generate_captions(media_url, …) e sincron — întoarce subtitrări la nivel de cuvânt în răspuns (așteptare 1–5 minute).

#Separare audio

1. generate_separation(media_url) → separation_id.
2. Consultă get_separation_status(id) după ~20s, apoi la fiecare 5s.
3. Când e gata, citește vocals_url + instrumental_url.

#Reclame

1. create_ad_copy(reference_ad_url, …, variant_count) → generation_ids: [...] (unul per variantă).
2. Consultă fiecare id cu get_generation_status până la finalizare.

#Ritmul polling-ului

Fiecare rând din get_models aduce un estimated_time_seconds bazat pe timpi reali istorici. Folosește-l ca prima așteptare, apoi consultă la fiecare 5s. Nu interoga la fiecare secundă — îți consumi cota de rate-limit pentru același rezultat.

#Bune practici

• Citează costul înainte de generare pentru orice model per-durată — estimate_generation_cost e read-only.
• Începe întotdeauna cu get_models — nu fixa model_ids; capabilitățile dictează forma cererii.
• Respectă cerințele de input — get_models îți spune requires_input_media, max_input_images etc.
• Tratează 429 (rate limit) — așteaptă și reîncearcă. Nu intra în bucle strânse pe erori.
• Arată erori clare utilizatorului la credite insuficiente sau input invalid — nu reîncerca fără acțiunea lui.

Vezi Limitări pentru rate limits și comportamentul rambursării de credite.