Skip to content

Generate an image

POSThttps://api.vidmoat.com/v1/ai/images
Bearer tokenScope ai.image60 credits Grok; OpenAI from 128 creditsTry it in the playground

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

  • promptstringrequired
    Up to 800 characters; anything longer is cut to 800.
  • providerenumdefault auto
    Who generates it. Auto picks the lowest compatible quote between Grok and OpenAI.
    One of auto, grok, openai
  • resolutionenumdefault 2k
    Affects OpenAI prices.
    One of 1k, 2k
  • aspectRatiostring
    For example 16:9, 9:16, 1:1, 4:5, 21:9.
  • referenceUrlsarray of strings
    Up to 5 reference images: your upload URLs (png, jpg, webp, avif) or public HTTPS URLs.
  • castIdsarray of strings
    Up to 6 saved Cast members (cm_... from GET /v1/cast). Each adds its best reference view and its description; counted with referenceUrls. 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 to castIds (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 in scene.applied.
  • shotobject
    Optional 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. A move or pace is refused for a still with the nearest framing, and an unknown id is refused with the list, before any charge.
  • framingenum
    Which Cast views to send with castIds. Default medium.
    One of close, medium, wide
  • consistencyobject
    { check?: boolean }. With castIds the finished image is face-checked against each member (free) and the reply carries consistency verdicts.
  • maxCreditsnumber
    Never spend more than this.
  • quoteOnlyboolean
    true returns the route and price without generating or charging.

Response#

Returns 200.

Response fields#

  • urlstring
    The image. Use as a clip src.
  • routeobject
    The provider route chosen: provider, model, credits, maxCredits, reason and policy (and voiceId for speech).
  • shotobject
    When you sent shot: the preset applied, with shotDescription in words.
  • sceneobject
    When you sent scene: what the scene added, in scene.applied.
  • castIdsarray of strings
    When Cast members were used: the members, after the scene's were added.
  • referencesUsedarray
    When Cast members were used: { memberId, name, view, url } per reference image sent.
  • consistencyarray
    With consistency.check: one verdict per member, as Check consistency returns them; consistencySummary says it in one line.
  • creditsobject
    { charged, remaining }: what this call cost and the balance after it.
  • hintstring
    What to do with it.
  • quoteOnlyboolean
    With quoteOnly: true the reply is { route, quoteOnly: true } plus the shot, scene and Cast fields above.

Errors#

Besides the errors any request can get (authentication, rate limits):

StatusCodeWhen
400invalid_requestNo prompt, a refused reference, provider vertex (Google models are not offered through the API), or no provider matches the options and maxCredits.
402plan_requiredThe plan has no image generation.
402insufficient_creditsThe balance cannot cover the call. Nothing ran. remaining is the balance.
422prompt_rejectedThe prompt failed the safety check. Nothing was charged. field names the field.
502provider_errorThe generation provider failed. The charge is refunded.