Recipes
Three short end-to-end flows — generate an image and fetch it, build a reel draft, and watch your spend.
Three flows that put the tools together. Each one is complete: nothing is left out between the calls.
Generate an image and fetch it
generate_image returns as soon as the job is accepted, not when the image exists. The
address comes from get_asset.
Pick the brand. list_brands gives you the ids. One key belongs to one workspace,
so you only ever see your own.
Start the job. generate_image with brand_id, prompt and modelKey. The
answer carries asset_id, status: "generating" and what it cost.
Poll get_asset with that id until status is no longer generating. There is no
webhook for this yet — a few seconds between calls is enough.
Before you publish it
What you get back is the master: signed with C2PA, but without a visible label. If you distribute it yourself, the visible disclosure is yours to make — see AI labelling.
Build a reel draft
create_composition plans and assembles a draft inside your workspace. It does not
publish anything, and the draft itself is not charged.
Call create_composition with brand_id, idea, duration_target_sec and mode.
Use fit_to_time when the length matters more than completeness, fit_to_idea when it
is the other way round.
Open it in Ikrames. The answer carries a composition_id. Turning a draft into a
post happens in the app, not over this API — that is where approval, the visible AI
label and scheduling live.
Reels are portrait only (9:16). A composition is draft material until it has been
through Ikrames' publishing path.
Watch what you spend
get_costs reads the same events the billing screen reads. Useful before and after a
batch, so you can see what a run actually cost rather than estimating it.
Read the balance before — get_costs with the window you care about.
Do the work. Every call that spends credits reports cost_credits and
new_balance in its own answer, so you can also stop mid-run.
Read it again. The difference is what the run cost, broken down by what produced it.
A failed generation is not charged
If a job cannot be submitted, the credits are returned automatically and the call reports the failure. You pay for work that happened, not for work that was attempted.