Generate an image
POST
https://api.vidmoat.com/v1/ai/imagesGenerate a still with optional referenceUrls (up to 5 images: your uploads or public HTTPS images). provider accepts grok, openai or auto (default). Google models are not offered through the API: provider vertex is refused with a 400. quoteOnly:true returns the initial and maximum credits without spending. Retain provider:auto with the quoted maxCredits to allow safe quota fallback; explicit providers never switch. OpenAI GPT Image 2.5 Flare costs 128 at 1k or 256 at 2k plus 8 per reference. Only the successful asset is charged. Image generation is on Creator and above; live keys need Studio or above.
Body#
promptstringrequiredUp to 800 characters; anything longer is cut to 800.providerenumdefaultautoWho generates it. Auto picks the lowest compatible quote between Grok and OpenAI.One ofauto,grok,openairesolutionenumdefault2kAffects OpenAI prices.One of1k,2kaspectRatiostringFor example16:9,9:16,1:1,4:5,21:9.referenceUrlsarray of stringsUp to 5 reference images: your upload URLs (png, jpg, webp, avif) or public HTTPS URLs.castIdsarray of stringsUp to 6 saved Cast members (cm_...from GET /v1/cast). Each adds its best reference view and its description; counted withreferenceUrls. Over the limit is refused with the count.sceneobject{ projectId, sceneId }: make this still for a storyboard scene. The scene's cast and place are added tocastIds(you can add members, never remove one) and the board's style lock fills the lens (a different one is refused). The response lists them inscene.applied.shotobjectOptional shot preset,{ framing?, lens? }. framing:extreme_close_up,close_up,medium,wide,overhead,low_angle; lens:wide_24mm,normal_50mm,portrait_85mm,macro,anamorphic. Added to the prompt for you. Amoveorpaceis refused for a still with the nearest framing, and an unknown id is refused with the list, before any charge.framingenumWhich Cast views to send withcastIds. Default medium.One ofclose,medium,wideconsistencyobject{ check?: boolean }. WithcastIdsthe finished image is face-checked against each member (free) and the reply carriesconsistencyverdicts.maxCreditsnumberNever spend more than this.quoteOnlybooleantruereturns the route and price without generating or charging.
Response#
Returns 200.
Response fields#
urlstringThe image. Use as a clipsrc.routeobjectThe provider route chosen:provider,model,credits,maxCredits,reasonandpolicy(andvoiceIdfor speech).shotobjectWhen you sentshot: the preset applied, withshotDescriptionin words.sceneobjectWhen you sentscene: what the scene added, inscene.applied.castIdsarray of stringsWhen Cast members were used: the members, after the scene's were added.referencesUsedarrayWhen Cast members were used:{ memberId, name, view, url }per reference image sent.consistencyarrayWithconsistency.check: one verdict per member, as Check consistency returns them;consistencySummarysays it in one line.creditsobject{ charged, remaining }: what this call cost and the balance after it.hintstringWhat to do with it.quoteOnlybooleanWithquoteOnly: truethe reply is{ route, quoteOnly: true }plus the shot, scene and Cast fields above.
Errors#
Besides the errors any request can get (authentication, rate limits):
| Status | Code | When |
|---|---|---|
| 400 | invalid_request | No prompt, a refused reference, provider vertex (Google models are not offered through the API), or no provider matches the options and maxCredits. |
| 402 | plan_required | The plan has no image generation. |
| 402 | insufficient_credits | The balance cannot cover the call. Nothing ran. remaining is the balance. |
| 422 | prompt_rejected | The prompt failed the safety check. Nothing was charged. field names the field. |
| 502 | provider_error | The generation provider failed. The charge is refunded. |