--- title: "Start a generation" method: POST path: "/api/v2/generations" tags: ["Generations"] --- # Start a generation `POST /api/v2/generations` ## Request - Base URL: `https://azurade.com` - URL: `https://azurade.com/api/v2/generations` - Auth: one of: - HTTP bearer - API key in header `Authorization` Submits an image or video generation. The model's type decides which; parameters beyond model and prompt vary per model (see GET /api/v2/models/{id}). Credits are reserved when the job is accepted and refunded automatically if it fails; a model priced per image refunds the images it does not deliver. Send an idempotency_key so a retry after a timeout returns the first job, marked idempotent_replay, instead of charging twice. Every prompt is screened against the content policy first, and every input URL is fetched once (its first byte): one that does not download, or is a web page or text rather than a file, answers 400 validation_failed naming the field, before anything is charged. A job that cannot be started answers 502 generation_failed with its id and charges nothing; GET /api/v2/generations/{id} then carries the reason. ## Request body - GenerationRequest: model, plus the fields that model takes (GET /api/v2/models/{id}), enhance_prompt / translate_prompt, which every model with a prompt takes, and idempotency_key and callback_url, which every model takes. A field the model does not take, a missing required field or an invalid value answers 400 validation_failed, on the estimate as on the generation, except that the estimate does not require input images or videos, so a request can be priced before its files are uploaded. (A web-app session is lenient: it may estimate before the prompt exists, and its extra fields are ignored.) - `aspect_ratio` string: Output aspect ratio - `audio` string: URL of an audio file (voice or music) the video syncs to - `audio_setting` string: Video editing: auto generates new audio, origin keeps the input video's audio - `background` string: Whether the background is transparent or opaque - `callback_url` string, uri: Optional https URL, up to 2048 characters. When the job is final, completed with its outputs or failed or canceled with its error, it is POSTed there once, as JSON: the body GET /api/v2/generations/{id} answers. A network error, a 5xx or a 429 is retried for about six minutes; any other answer ends it. Nothing signs the request, so read the job back with GET before trusting what it says - `camera_fixed` boolean: Keep the camera position fixed - `character_orientation` string: Character orientation source for motion control - `duration` integer: Video duration in seconds - `enable_sequential` boolean: Batch mode: generate a set of related images (up to 12) - `enhance_prompt` boolean: Rewrite the prompt in more detail before generating, with the model's prompting guide or its own built-in rewriter (GET /api/v2/models/{id} says which); free, included in the generation price - `first_clip_url` string: URL of a video clip to continue (image-to-video mode); use instead of image and last_image - `fps` integer: Frames per second - `generate_audio` boolean: Generate a soundtrack for the video - `go_fast` boolean: Use faster generation mode - `google_search` boolean: Enable Google Search grounding for image generation - `guidance` number: Guidance scale (CFG scale) - `guidance_scale` number: Guidance scale (CFG scale) - `height` integer: Output height in pixels - `high_performance` boolean: Use high performance mode (better quality) - `idempotency_key` string: Any string you choose, up to 255 characters. A create repeated with the same key (after a timeout, say) returns the first job, marked idempotent_replay: true, instead of starting and charging a second; while the first is still being submitted the repeat answers 409 idempotency_in_progress. A different request under a used key answers 422 idempotency_key_reused, so use a new key for a new request - `image` string: Input image URL: the image to edit, animate or work on - `image_input` string[]: Multiple image URLs for editing or reference - `infer_steps` integer: Number of denoising steps - `input_image` string: Input image URL - `is_pro` boolean: Use Pro variant - `last_image` string: URL of the image the video ends on; pair with image, which it starts on - `lora_scale` number: LoRA scale factor - `lora_scale_transformer` number: How strongly the transformer LoRA is applied - `lora_scale_transformer_2` number: How strongly the second transformer LoRA is applied - `lora_weights` string: LoRA weights URL or identifier - `lora_weights_transformer` string: URL of LoRA weights (.safetensors) for the transformer - `lora_weights_transformer_2` string: URL of a second set of LoRA weights (.safetensors) for the transformer - `max_images` integer: Most images to make; state the same number in the prompt. The model may make fewer, and images not delivered are refunded - `megapixels` string: Approximate output size in megapixels - `model` 'flux-dev' | 'flux-kontext-pro' | 'gpt-image-2' | 'gpt-image-2.5' | 'hunyuan' | 'imagen-4-ultra' | 'kling-3.0' | 'kling-3.0-turbo' | 'motion-control' | 'nano-banana' | 'nano-banana-2' | 'nano-banana-2-lite' | 'nano-banana-2.1' | 'nano-banana-pro' | 'qwen-image' | 'qwen-image-2.1' | 'qwen-image-edit' | 'qwen-image-edit-plus' | 'qwen-image-edit-plus-lora' | 'qwen-image-layered' | 'recraft-crisp-upscale' | 'remove-background' | 'restore-image' | 'seedance-2' | 'seedance-2-mini' | 'seedance-2.5' | 'seedance-pro' | 'seedream-3' | 'seedream-4' | 'seedream-4.5' | 'seedream-5-flash' | 'seedream-5-lite' | 'seedream-5-pro' | 'veo2' | 'veo3' | 'veo3-fast' | 'veo3.1' | 'vidu-q4' | 'vidu-q4-reference' | 'wan-2.2' | 'wan-2.6' | 'wan-2.7' | 'wan-2.7-image' | 'wan-3.0' | 'wan-3.0-prime', required: Model id from GET /api/v2/models - `n` integer: Number of images, billed per image: 1-4, or 1-12 with enable_sequential. 1 when omitted. Images not delivered are refunded - `negative_prompt` string: Negative prompt to avoid certain content - `num_frames` integer: Clip length in frames: the clip lasts num_frames / fps seconds. 121 when omitted (5 s at 24 fps), or 81 with high_performance (3.4 s) - `num_inference_steps` integer: Number of denoising steps - `num_layers` integer: Number of layers to split the image into, 2 to 8 (billed per layer) - `num_outputs` integer: Number of images to generate, billed per image; images not delivered are refunded - `optimize_prompt` boolean: The model's own option: it translates the prompt to Chinese before generating. Independent of translate_prompt, which translates the prompt to English before the model gets it; one of the two is enough for a prompt in another language - `output_format` string: Output image format - `output_quality` integer: Output quality (1-100) - `prompt` string: The prompt to generate from - `prompt_extend` boolean: Let the model expand the prompt before generating - `prompt_strength` number: Strength of prompt influence for image-to-image - `quality` string: Quality level: basic (2K) or high (4K) - `reference_audios` string[]: Audio URLs that steer the soundtrack (3 to 5 at most, by model); ignored when image or last_image is set - `resolution` string: Output resolution - `sample_shift` number: Shifts the denoising schedule: higher values favour overall composition and motion, lower values fine detail - `seed` integer: Random seed for reproducibility; 0 or omitted picks one at random - `size` string: Output size preset - `thinking_mode` boolean: Reason about the prompt before generating; text-to-image without enable_sequential only - `translate_prompt` boolean: Translate the prompt to English before generating; free, included in the generation price - `veo31_generation_type` string: How the images in veo31_image_urls are used. Leave it out and the count decides: no images is TEXT_2_VIDEO, one or two are the first and last frames (FIRST_AND_LAST_FRAMES_2_VIDEO), three are reference images (REFERENCE_2_VIDEO, which takes veo3_fast and 16:9 only) - `veo31_image_urls` string[]: 1 to 3 image URLs: one image is the first frame, two are the first and last frames, three are reference images for the subject and style - `veo31_model` string: Quality tier: veo3 renders at higher quality, veo3_fast renders faster and costs less - `veo31_watermark` string: Watermark text to put on the video - `video_input` string[]: Multiple video URLs for video-to-video generation - `video_length` integer: Clip length in frames: the clip lasts video_length / fps seconds, 129 frames at 24 fps (5.4 s) by default - `watermark` boolean: Add a watermark to the output - `web_search` boolean: Let the model look up the prompt's subject on the web; text-to-video only - `width` integer: Output width in pixels ## Response `202` Accepted - GenerationAccepted - `cost` number - `id` string - `idempotent_replay` boolean: true when an earlier idempotency_key answered with its job: cost was charged once, by the first request. Absent for a new job - `model` string - `status` 'pending' | 'completed' | 'failed' | 'stalled' | 'canceled': pending for a new job; a repeat with an earlier idempotency_key answers that job's current status - `type` 'image' | 'video' ## Other responses - `400`: Invalid request - `401`: Missing or invalid credentials - `402`: Insufficient credits - `409`: idempotency_in_progress: a create with the same idempotency_key is still being submitted; retry in a few seconds - `422`: idempotency_key_reused: the idempotency_key was first sent with a different request; send a new key - `502`: generation_failed: the job could not be started and nothing was charged. id names the failed job; GET /api/v2/generations/{id} carries the reason a few seconds later - `503`: A dependency is unavailable; retry later --- [API](https://skmtc.dev/azurade/apis/azurade-ai-api.md) · [All operations](https://skmtc.dev/azurade/apis/azurade-ai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/azurade/apis/azurade-ai-api/revisions/0530fd2c8b63?raw)