Create Video
Start a video generation. Returns a task to poll.
Video is asynchronous: this call returns immediately with a task id, and you poll GET /v1/videos/tasks/{id} until it succeeds or fails.
Image-to-video models need an image_url your account generated. Every image, clip and audio input must come from your own account: images from GET /v1/images, clips from your own finished tasks, audio from POST /v1/audio or POST /v1/audio/speech. Failed generations are refunded automatically.
Model families. The Motion 2 generation: spicy-motion-1, spicy-motion-2, spicy-video-1 and spicy-character-video-1. The Motion 3 generation: spicy-motion-3 and spicy-motion-3-fast, with the wider parameter set noted per field below; an input video_url clip is billed per second on top of the output (bills_input_video_seconds), and they take action. The draft tier: spicy-motion-draft-1, silent image-to-video at a quarter of the price, for checking motion before rendering the keeper on Spicy Motion 2 or 3. The Cinema engine: spicy-cinema-1 (text only), spicy-cinema-1-image (first frame) and spicy-cinema-1-character (a character or up to 9 reference images, named Image 1, Image 2 in the prompt), 3 to 15 seconds at 480P to 1080P with native audio always on, no negative prompt, no enhance_prompt and no audio inputs.
Prices per output second: $0.20/s 720P, $0.30/s 1080P on the Motion 2 generation; $0.10/s 480P, $0.20/s 720P, $0.40/s 1080P on spicy-motion-3; $0.14/s 480P, $0.28/s 720P, $0.56/s 1080P on spicy-motion-3-fast; $0.05/s 720P, $0.075/s 1080P on spicy-motion-draft-1; $0.14/s 480P, $0.28/s 720P, $0.36/s 1080P on the Cinema models. To edit or restyle a finished clip, or to transfer its motion onto another person, use POST /v1/videos/edits.
Input combinations. Which inputs may travel together is per model and comes from inputs on GET /v1/models; a request that mixes them wrongly is a 400 that names what you sent and quotes the valid combinations below. Audio comes in two modes: driving audio (spicy-motion-2, spicy-video-1) makes the clip the soundtrack of the output, the mouth follows it, and it goes alongside a first frame where the model takes one; reference audio (spicy-motion-3, spicy-motion-3-fast) leaves the sound to the model, which uses the clip for voice, tone and beat while the words come from the prompt, and only goes with a text prompt or references, never with a first frame. Send audio_mode to assert which one you expect.
spicy-motion-3: reference audio: the model generates sound and uses the clip for voice, tone and beat, up to 5 clips and 15 seconds total. Text prompt only, with aspect_ratio; dialogue written in the prompt is spoken natively. First frame (image_url), optionally a last frame (last_frame_url); no references or audio in the same request. Reference images (up to 10, or a character) plus a text prompt: same person, framing chosen by the model. Reference images, a reference video (video_url, 15s max) and reference audio (up to 5 clips, 15s total) in any mix, with a text prompt; audio guides voice, tone and beat while the words come from the prompt.
spicy-motion-3-fast: reference audio: the model generates sound and uses the clip for voice, tone and beat, up to 5 clips and 15 seconds total. Text prompt only, with aspect_ratio; dialogue written in the prompt is spoken natively. First frame (image_url), optionally a last frame (last_frame_url); no references or audio in the same request. Reference images (up to 10, or a character) plus a text prompt: same person, framing chosen by the model. Reference images, a reference video (video_url, 15s max) and reference audio (up to 5 clips, 15s total) in any mix, with a text prompt; audio guides voice, tone and beat while the words come from the prompt.
spicy-cinema-1-image: no audio input. First frame (image_url) with a text prompt; the output keeps the image's shape.
spicy-motion-2: driving audio: the clip is the soundtrack and the mouth follows it. First frame (image_url), optionally a last frame (last_frame_url). First frame plus driving audio (audio_url): the clip becomes the soundtrack and the mouth follows it. First frame, last frame and driving audio together. A clip to continue (video_url, 2 to 10s) instead of a first frame, optionally with a last frame.
spicy-character-video-1: no audio input. A character (or reference images) plus a text prompt. A character plus a first frame (image_url) that opens the clip.
spicy-cinema-1-character: no audio input. A character or reference images (up to 9) plus a text prompt that names them Image 1, Image 2....
spicy-cinema-1: no audio input. Text prompt only, with aspect_ratio; the clip has native audio.
spicy-video-1: driving audio: the clip is the soundtrack and the mouth follows it. Text prompt only, with aspect_ratio. Text prompt plus driving audio (audio_url): the clip becomes the soundtrack and motion follows it.
spicy-motion-draft-1: no audio input. First frame (image_url) with a text prompt; the clip is silent.
spicy-motion-1: no audio input. First frame (image_url) with a text prompt.
curl --request POST \
--url https://api.spicyapi.com/v1/videos/generations \
--header 'Authorization: Bearer $SPICYAPI_KEY' \
--header 'Content-Type: application/json' \
--data '{
"model": "spicy-motion-3",
"action": "pov-missionary",
"image_url": "https://cdn.spicyapi.com/outputs/a1b2/req_8f2a91c4-0.png",
"prompt": "hotel room at night, warm lamp light, white sheets",
"resolution": "720P"
}'{
"id": "task_5d9e2f10",
"object": "task",
"type": "video",
"model": "spicy-motion-3",
"status": "queued",
"output": null,
"error": null,
"cost_usd": 3.2,
"poll_url": "/v1/videos/tasks/task_5d9e2f10"
}Body
application/jsonA video model id, e.g. spicy-motion-3, spicy-motion-draft-1 or spicy-cinema-1.
What should happen in the clip. Capped at the model's limits.maxPromptChars (1500 on spicy-motion-1 and spicy-motion-draft-1, 5000 on the rest of the Motion 2 generation and the Cinema models, 20000 on spicy-motion-3 and spicy-motion-3-fast); longer prompts are a 400. May be empty when image_url is set, or with action, where it describes the scene (setting, outfit, lighting) rather than the motion. On spicy-cinema-1-character refer to the references as Image 1, Image 2 and so on.
First frame; must be one of your generated images. Required where requires_image is true (including spicy-motion-draft-1 and spicy-cinema-1-image). Optional on spicy-motion-3, spicy-motion-3-fast and spicy-character-video-1, which generate from text alone when it is omitted; on spicy-character-video-1 only together with a character. Rejected on spicy-video-1, spicy-cinema-1 and spicy-cinema-1-character. Cannot be combined with reference_image_urls, nor with video_url on the Motion 2 generation. With action it is not the first frame but the woman who performs the act (identity reference).
Closing frame, one of your generated images; the clip travels from image_url to it. Needs image_url (or a continuation video_url). Models with inputs.last_frame: spicy-motion-2, spicy-motion-3 and spicy-motion-3-fast. See Input combinations above.
Up to inputs.reference_images of your generated images that guide identity and look without fixing the opening shot (a character counts as one; its sheet goes first as Image 1). spicy-character-video-1, spicy-motion-3, spicy-motion-3-fast (up to 10) and spicy-cinema-1-character (up to 9). Exclusive with image_url. See Input combinations above.
A saved character id (chr_...) to keep the same person. Same models as reference_image_urls; on other models generate a first frame with the character and pass it as image_url. On spicy-motion-3 and spicy-motion-3-fast with an image_url, the first frame sets the person, so the sheet and views are not sent (those models refuse a first frame with reference images).
With character: the body view ids to send (cv_... from the character's views), up to 2 (in the free reference slots), or [] for none. Omitted: the views that fit the prompt are picked for you (a back view for a shot from behind, a close-up for a close-up), listed in the response as character_views. Not with action. No extra charge.
spicy-motion-3 and spicy-motion-3-fast only: the id of a ready-made sex act from GET /v1/videos/actions (e.g. pov-missionary, pov-blowjob-deepthroat). The action's reference clip supplies camera angle, framing, pose and motion second for second; image_url (or reference_image_urls, or a character, one of which is required) supplies the woman; prompt is optional and sets the scene, and without it she is in a plain light bedroom. Not combinable with video_url or last_frame_url. duration defaults to 8 and aspect_ratio to the action's own. The reference clip is the first 4 seconds of the act (5 on two actions, see duration_s); the model follows it, then carries the same act on as one continuous take. Its seconds are billed as input seconds on top of the output seconds, so an 8 second 720P clip bills 12 seconds.
An art style id from GET /v1/styles (photorealistic, studio, anime, 3d or cartoon), on every video model. One sentence tells the model the whole video's art style, matched to the first frame or reference image. With action it keeps a stylised woman stylised: without it the photoreal reference clip pulls her toward realistic. Same model and price. Omit it for the model's natural look.
One of your own finished clips (the video_url of a succeeded task; uploads and external videos are rejected). On spicy-motion-2 it continues the clip: it takes the place of image_url, must be 2 to 10 seconds long, duration is the whole output including the clip (so set it longer than the clip) and you are billed for the whole duration. On spicy-motion-3 and spicy-motion-3-fast it is a reference clip to extend or edit: at most 15 seconds, clip plus duration cannot exceed 30 seconds, and it cannot be combined with image_url (on those models a first frame pairs only with last_frame_url); with duration: -1 the model fills what is left of the 30. Other models reject it. inputs.continuation_clip and inputs.reference_video say which; see Input combinations above.
A clip you uploaded with POST /v1/audio or generated with POST /v1/audio/speech (its url, byte-for-byte), 2 to 30 seconds long. What it does depends on the model's inputs.audio.mode: driving audio (spicy-motion-2, spicy-video-1) is the soundtrack and the mouth follows it, one clip, alongside image_url where the model takes one; reference audio (spicy-motion-3, spicy-motion-3-fast) guides voice, tone and beat while the model generates the sound, and never goes with image_url (a first frame pairs only with last_frame_url there). Rejected on spicy-motion-1 and spicy-character-video-1. See Input combinations above.
Several of your clips, up to the model's inputs.audio.max_clips (5 on spicy-motion-3 and spicy-motion-3-fast, 15 seconds total); other models take a single audio_url. See Input combinations above.
Optional guard, driving or reference: what you expect the audio to do. It must equal the model's inputs.audio.mode, otherwise a 400 names a model that offers the requested mode (driving: spicy-motion-2 or spicy-video-1; reference: spicy-motion-3 or spicy-motion-3-fast). When omitted the model's mode applies.
One of the model's limits.resolutions from GET /v1/models: 720P or 1080P on the Motion 2 generation and spicy-motion-draft-1; 480P, 720P or 1080P on spicy-motion-3, spicy-motion-3-fast and the Cinema models. Defaults to 720P.
Text-to-video only. One of the model's limits.aspectRatios: 16:9, 9:16, 1:1, 4:3, 3:4 on spicy-video-1 (default 16:9); those plus 21:9 on spicy-motion-3 and spicy-motion-3-fast, where omitting it lets the model pick a shape to suit the prompt; those plus 4:5, 5:4, 9:21 and 21:9 on spicy-cinema-1 and spicy-cinema-1-character. Not accepted with image_url or video_url: the output follows the source. With action any of the model's ratios may be requested; the default is the action's own aspect_ratio.
Seconds, between the model's minDuration and maxDuration (2 to 10 on spicy-motion-1, 2 to 15 on the rest of the Motion 2 generation and spicy-motion-draft-1, 3 to 15 on the Cinema models, 2 to 30 on spicy-motion-3 and spicy-motion-3-fast). Defaults to 5, or 8 with action (the action's 8 seconds plus duration cannot exceed 30). On spicy-motion-3 and spicy-motion-3-fast, -1 lets the model choose the length: you are debited for the maximum (30 seconds, less any video_url clip) and the difference is refunded when the task finishes, with the task's cost_usd settling to the rendered length shown in usage.output_seconds.
What to avoid. Accepted and ignored on spicy-motion-3, spicy-motion-3-fast and the Cinema models, which have no negative prompt.
Let the model expand the prompt with lighting, camera and detail cues before generating. Defaults to false: the prompt is sent exactly as written.
Generate audio where the model supports it. Ignored on spicy-motion-draft-1 (always silent) and the Cinema models (native audio always on).
30 (default) or 60, on every video model. 60 frame-interpolates the finished clip to 60 fps for smoother motion, keeping the audio, for 20% of the video's own price (input and action clip seconds included), added to the task's cost_usd. The task takes about a minute longer. If the 60 fps step fails, the 30 fps clip is delivered and that fee refunded; the finished task's usage.fps says which. Other values are a 400, as is 60 at 1080P with aspect_ratio 21:9 or 9:21 (over the 1920x1080 pixel limit for 60 fps; use 720P); 503 when 60 fps is unavailable.
Reproducibility seed.
When true, validates and screens the request and returns { object: "dry_run", cost_usd, moderation } without generating or charging. A blocked prompt still returns the normal 422.
Your own id for the end user making this request (up to 128 characters; send an opaque id, not an email). Send it if your product serves many people: declined-prompt history, strikes and suspensions are then kept per end user, so one person's behaviour never affects another's requests or your account. After 10 severe violations that user gets 403 end_user_suspended; the id is echoed back as user in every screening error so you can act on it. It is stored with the requests it was sent on, so DELETE /v1/end-users/{user} can erase that person's data.
Response
200 · application/jsonSuccessful Response
A task you can poll.
Task id. Pass it to GET /v1/videos/tasks/{id}.
Always task.
Always video.
The model generating the clip.
queued, processing, finalizing, succeeded, or failed.
Null until the task succeeds.
Why the task failed, when it did.
blocked when the model declined the content (refunded); otherwise null.
What was debited now, including any billed input clip seconds. With duration: -1 this is the maximum; the task's cost_usd settles to the rendered length when it finishes.
The character's body views sent as references, when any were.
/v1/videos/tasks/{id}, relative to the base URL.
Was this page helpful?