Create a video

The smallest useful brief

Provide video_idea and a whole-number video_length_sec from 5 to 300. A URL by itself is not enough: describe what happens, the subjects, the message and the tone.

curl --fail-with-body https://app.jemsu.ai/api/v1/videos \
  -H "Authorization: Bearer $JEMSU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "video_idea": "A small paper boat drifts across a sunlit pond. Gentle ripples, a low camera angle and a peaceful ending.",
  "video_length_sec": 10,
  "speech": "no",
  "music": "no",
  "aspectratio": "9:16"
}'

Creative field reference

Style selection

Pass preset_style or my_style with an ID returned by the corresponding API. Do not send both. A style may supply defaults, but every resolved brief still needs a video idea and valid duration. Some product/dealership styles require a matching URL.

Successful response

Migrating older requests

Use video_idea, optional segments[].idea and notes. Classic per-segment instruction fields, video_mode and explicit legacy voice IDs are rejected with 422 classic_fields_unsupported. Its fields and hint explain what to change. A bare URL returns 400 video_idea_required.

The URL remains /api/v1/videos; the current implementation uses the Ava director. API path version and video pipeline version are separate.

Error codes and recovery →

Voice, media and ordered segment hints

1. Set speech, then choose audio_source. Native audio makes people on screen speak; voiceover uses an off-screen narrator; voice_clone uses your sample; voice_design uses your description. speech: no selects ambient sound with audio_source: none.
2. For a narrator, set voice_gender and voice_style. Use voice_script_mode: dictate for your exact words, or planner to let the director write. assist without a script falls back to planner.
3. Dictated narrator, cloned and designed voices are paced at 2.0 words per second; native speech is paced at 2.5. A script that outruns the requested duration fails validation.
4. Combine image_sources when you need both page images and uploads. reference_images always adds upload. Media must be reachable public HTTPS images or audio, at most 10 MB each; foreign-host files are copied into your library.
5. Up to 10 segments can pin the exact segment count, order, idea and references. Each hint accepts up to 10 reference images plus continuation. The director plans production within that structure. The classic segments[] object fields textPrompt, imagePrompt, motionPrompt and referenceImageUrls are also accepted.

The in-app Memory pickers are not available to API callers. Pass media URLs in reference_images, segment references, logo_url or voice_clone_sample_url.

A narrated video brief

curl --fail-with-body -X POST https://app.jemsu.ai/api/v1/videos \
  -H "Authorization: Bearer $JEMSU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "video_idea": "A 20-second promo for a neighborhood bakery: warm morning light, sourdough out of the oven, a close-up of the crust, end on the shop sign.",
  "video_length_sec": 20,
  "speech": "yes",
  "audio_source": "voiceover",
  "voice_gender": "female",
  "voice_style": "warm and friendly",
  "voice_script_mode": "planner",
  "music": "yes",
  "music_notes": "upbeat acoustic",
  "captions": "yes",
  "aspectratio": "9:16",
  "notes": "Never show prices. The sign reads BAKED DAILY."
}'

Example creation response

Illustrative 20-second response. Credit cost depends on the chosen model, duration and resolution; read the actual response for your job. The warnings example shows a mapped legacy alias.

{
  "ok": true,
  "jobId": "YOUR_JOB_ID",
  "conversationId": "YOUR_CONVERSATION_ID",
  "creditsReserved": 1440,
  "costSource": "v2:pinned:seedance-2.0@720p@20s",
  "warnings": [
    "mapped videolength \u2192 video_length_sec"
  ]
}

creditsReserved is the pinned model’s rate multiplied by the requested seconds. costSource identifies the model, resolution and duration used for pricing. The final charge is reconciled after delivery; any difference is refunded.

Classic aliases that are mapped

Each alias mapping and ignored field appears in warnings. Canonical values are coerced leniently: for example, “true” becomes yes and “30” becomes 30. Values outside an allowed list are ignored with a warning; unresolved requirements return 422 brief_invalid.

Classic fields that are refused

Sending one of these fields with a value returns 422 classic_fields_unsupported. The suffix N represents a numbered legacy segment field.

Server-managed fields

These fields are silently stripped from requests and loaded styles; sending them does not change the account, job protocol or callback configuration: