How it works

#Typical workflows

#Media (image or video)

1. Optionally call get_models to pick a model and see cost; call get_balance to confirm you have enough credits.
2. Call generate_media with prompt, model, and options. You receive a generation_id.
3. Poll get_generation_status with that ID every few seconds (e.g. 2-5 seconds) until status is completed or failed.
4. When completed, use the outputs array: each item has url (full quality), thumbnail_url, and optionally optimized_url. Use the one that fits your use case (preview vs download).

#Music

1. Optionally call get_balance and get_models (music) to check credits and cost.
2. Call generate_music with prompt, style, and options. You receive a generation_id.
3. Poll get_music_status with that ID until status is completed or failed.
4. When completed, use the songs array: each song has audio_url, title, lyrics, and often image_url.

#Ads

1. Call create_ad_copy with reference ad image URL, and your product (user-uploaded product image URL or text), and options. You receive generation_ids (one per variant).
2. For each ID, poll get_generation_status (same as media) until completed.
3. Use the returned image URLs for each variant.

#Best practices

• Check balance and cost first - Call get_balance and get_models before expensive generations so users are not surprised by failures or costs.
• Respect model requirements - For media, only send source_media_urls when the model supports image-to-video or image-to-image. Use get_models to see which models need input media.
• Poll sensibly - Use a 2-5 second interval when polling status. Set a maximum wait time (e.g. 5-10 minutes for media, longer for music/ads) and show a timeout message if the job does not complete.
• Handle errors - On rate limit (e.g. 429), wait and retry. On insufficient credits or invalid parameters, show a clear message and do not retry the same request without user action.
• Use the right URL - For previews use thumbnail_url or optimized_url; for full quality use url.

See Limitations for rate limits and credit behavior.