API reference

Renders

Start an image or video render, then poll it to completion. Renders run asynchronously; the create call returns immediately with the credit charge, and failures refund automatically.

POST/api/v1/renders

JSON body. kind and prompt are required. Unknown fields are ignored; invalid values return 422 with the field named in the message.

Field	Type	Description
`kind`required	"image" \| "video"	What to generate. Selects which parameter set below applies.
`prompt`required	string	The generation prompt, up to 8,000 characters.

Image parameters

Field	Type	Description
`imageModel`	string	`seedream` (default) · `nano-banana` · `nano-banana-pro` · `gpt-image-2`
`imageResolution`	string	`1K` · `2K` · `4K`
`imageQuality`	string	`low` · `medium` · `high` (gpt-image-2 only)
`imageAspectRatio`	string	`9:16` (default) · `1:1` · `16:9`
`imageCount`	integer	1–4 variants. The response returns one id per variant in `ids`, grouped by `batchId`.
`referenceImageUrls`	string[]	Up to 10 upload URLs for image-to-image guidance.

Video parameters

Field	Type	Description
`model`	string	`kling` (default) · `seedance` · `seedance-fast` · `veo-3.1` · `veo-3.1-fast` · `veo-3.1-lite`
`durationSeconds`	integer	kling 5–15 · seedance 5–60 (longer runs are generated as stitched clips) · veo 4–8 (snapped to 4/6/8)
`resolution`	string	Per model: kling `720p/1080p/4k`, seedance `480p/720p/1080p`, seedance-fast `720p`, veo `720p/1080p/4k` (lite has no 4k).
`aspectRatio`	string	`9:16` · `1:1` · `16:9`
`generateAudio`	boolean	Generate an audio track alongside the video.
`negativePrompt`	string	What to avoid, up to 500 characters.
`referenceImageUrls`	string[]	Upload URLs; per-model caps apply and extras are dropped silently. The first entry becomes the start frame.
`referenceVideoUrls`	string[]	Reference videos (kling and seedance); per-model caps apply.
`referenceAudioUrls`	string[]	Reference audio for voice/lip-sync — seedance only.

Response

202 Accepted

{
  "id": "b3f1…",
  "ids": ["b3f1…"],
  "batchId": null,
  "kind": "video",
  "status": "pending",
  "renderModel": "kling-720p",
  "creditsCharged": 200
}

Polling

GET/api/v1/renders/{id}

status moves pending → running → ready (or failed). Poll every few seconds — images typically finish in under a minute, videos in one to several minutes by model and duration. An id that doesn't exist on your account returns 404 not_found.

Field	Type	Description
`outputUrl`	string \| null	The finished media (durable URL; also visible in the app).
`errorMessage`	string \| null	On failure, why the render failed.
`creditsRefunded`	integer	The automatic refund amount on failure (0 otherwise).
`chain`	{ clipsReady, clipsTotal }	Long seedance renders report stitching progress while clips complete.

Credits & billing

Image renders are plan-included on Team and above — creditsCharged: 0. Fair-use limits apply to sustained bulk generation; you'll get a 429 with Retry-After rather than a charge.
Video renders debit render credits at the same per-second, per-model rates as the app. The 202 response reports creditsCharged up front.
Failed renders refund automatically; long stitched renders that partially complete refund the unmade portion.
Balance and top-ups live in Billing — the API never charges beyond your credit balance. How credits work in general is covered in the billing guide.