Skip to main content

Create a prompt

Creates a new fine-tune model from training images which in turn will be used to create prompts and generate images.

Parameters​

text (required)​

Description of the image.

negative_prompt (optional)​

A comma separated list of words that should not appear in the image.

callback (optional)​

a URL that will be called when the prompt is done processing. The callback is a POST request where the body contains the prompt object. See more.

workspace_id (optional)​

Integer. Creates and bills the prompt in a workspace that the authenticated user can access. Omit it to use the user's personal scope.

community (optional)​

Boolean. Share the finished prompt to the Astria community feed.

num_images (optional)​

Number of images to generate. Range: 1-8.

seed (optional)​

Random number to create consistent results. Range: 0 to 2^32.

super_resolution (optional)​

Boolean. X4 super-resolution.

inpaint_faces (optional)​

Boolean. Requires super-resolution on. Inpaints faces.

hires_fix (optional)​

Boolean. Super resolution details. Available only when super_resolution is true. Adds details.

face_correct (optional)​

Boolean. Runs another AI model on top to correct the face in the image.

face_swap (optional)​

Boolean. Uses training images to swap face and enhance resemblance.

cfg_scale (optional)​

Float. How strictly the diffusion process adheres to the prompt text (higher values keep your image closer to your prompt). Range 0-15

steps (optional)​

Integer. Number of diffusion steps to run . Range 0-50

use_lpw (optional)​

Boolean. Use weighted prompts.

aspect_ratio (optional)​

enum: 1:1, 16:9, 9:16, 21:9, 9:21, 3:2, 2:3, 5:4, 4:5, 4:3, 3:4

ar (optional)​

Legacy aspect-ratio field. enum: 1:1, portrait, 16:9, landscape. New integrations should use aspect_ratio.

resolution (optional)​

Output resolution tier. enum: 1K, 2K, 4K. Availability depends on the selected foundation model; unsupported combinations return a validation error.

w (optional)​

width - In multiples of 8.

h (optional)​

height - In multiples of 8.

scheduler (optional)​

enum: euler, euler_a, dpm++2m_karras, dpm++sde_karras, dpm++2m, dpm++sde, lcm, tcd. If not specified the default account scheduler will be used.

backend_version (optional)​

enum: null, 1, If not specified will default to the account version will be used.

style (optional)​

enum: null, Cinematic, Animated, Digital Art, Photographic, Fantasy art, Neonpunk, Enhance, Comic book, Lowpoly, Line art. See more.

prompt_expansion (optional)​

Boolean. Ask supported models to expand the supplied prompt before generation. Defaults to false.

theme (optional)​

String metadata used to group prompts generated as part of the same theme.

color_grading (optional)​

enum: Film Velvia, Film Portra, Ektar.

film_grain (optional)​

boolean - Adds noise to the image to make it look more realistic.

Img2Img / ControlNet​

controlnet (optional)​

Requires input_image. Possible values: composition, reference, segroom, ipadapter, lineart, canny, depth, mlsd, hed, pose, tile, qr.

denoising_strength (optional)​

For img2img. 1.0 - Take prompt. 0.0 - Take image. Range: 0.0-1.0. Default: 0.8

controlnet_conditioning_scale (optional)​

Strength of controlnet conditioning. 0.0-1.0

controlnet_txt2img (optional)​

Boolean toggle. True for text to image controlnet. False for image to image controlnet.

input_image (optional)​

Binary multi-part request with the image. Used in conjunction with controlnet parameter.

input_image_base64 (optional)​

Base64 data URL alternative to input_image, for example data:image/png;base64,....

input_image_url (optional)​

URL to an image. Used in conjunction with controlnet parameter.

mask_image (optional)​

Binary multi-part request with one channel mask image. Used in conjunction with input_image parameter for inpainting

mask_image_url (optional)​

URL to a one channel mask image. Used in conjunction with input_image_url parameter for inpainting.

lora_scale (optional)​

Available only when used as prompts_attributes in POST /tunes request to override the default scale of the LoRA model.

pack_id (optional)​

Integer. Authors the prompt as a template prompt in an accessible pack. A template prompt must reference a fine-tuned tune.

base_pack_id (optional)​

Integer. Records an accessible pack as the provenance for a one-off prompt without making the prompt a reusable pack template.

Video​

Pass these alongside text to turn a prompt into a video. The image stage (driven by the chosen tune) renders the first frame from text; the video model then animates it using video_prompt. For text-to-video models the image stage can be skipped — see the model list.

video_model (required for video)​

enum: seedance_480p, seedance_v15_720p, seedance_v15_audio_720p, seedance2_fast_480p, seedance2_fast_720p, seedance2_fast_1080p, seedance2_fast_4k, seedance2_480p, seedance2_720p, seedance2_1080p, seedance2_4k, wan22_720p, wan22_fast_720p, wan22_fast_580p, wan22_fast_480p, wan25_720p, wan26_720p, wan26_1080p, wan27_720p, wan27_1080p, wan_animate_720p, ltx23_720p, ltx23_1080p, kling25, kling30_standard, kling30_standard_audio, kling30_pro, kling30_pro_audio, kling30_4k, kling30_motion_control, kling30_motion_control_pro, cinematic_video, dreamactor_m2, happyhorse_720p, happyhorse_1080p, happyhorse_motion_control, veo31_fast_720p, veo31_fast_audio_720p, veo31_fast_1080p, veo31_fast_audio_1080p, veo31_fast_4k, veo31_fast_audio_4k, veo31_lite_720p, veo31_lite_audio_720p, veo31_lite_1080p, veo31_lite_audio_1080p. See Image2Video for capabilities, pricing, and allowed durations per model.

video_prompt (required for video)​

Natural-language description of the motion / camera / scene action. Surround the value with quotes when posting via multipart/form-data.

For Seedance 2 reference-to-video, include each existing reference tune as <faceid:TUNE_ID:1> TUNE_NAME (or the corresponding lora token). The tune's class name must immediately follow the token. Astria resolves those tunes and supplies their images as video references; Seedance 2 accepts up to nine reference images in total.

image_references (optional)​

Ordered array of binary multipart image uploads used to condition a compatible video model. Repeat prompt[image_references][] for each image. The request must be a video prompt and the selected video_model must support multiple image references.

image_reference_urls (optional)​

Ordered array of publicly accessible image URLs, as an alternative to image_references. Repeat prompt[image_reference_urls][] for each URL. Reference order is preserved within each array; use one form when the exact order of a mixed file-and-URL sequence matters.

video_duration (optional)​

Integer seconds. Allowed values depend on video_model (see Image2Video). Defaults vary per model (commonly 5; 8 for VEO3; 10 for motion-control / animate models).

video_first_frame (optional)​

Binary multi-part image upload to use as the first frame, overriding the rendered image. When provided, the image stage is skipped and text is not required.

video_first_frame_url (optional)​

URL alternative to video_first_frame.

video_last_frame (optional)​

Binary multi-part image upload for first+last keyframe models (e.g. seedance_v15_*, seedance2_*, wan21_*, kling*, ltx23_*, veo31_*).

video_last_frame_url (optional)​

URL alternative to video_last_frame.

source_image_url (optional)​

URL of an existing generated image to animate as the first frame. This skips the image-generation stage. If video_first_frame or video_first_frame_url is also provided, the explicit first frame takes precedence.

input_video (optional)​

Binary multi-part video upload. Seedance 2 uses it as a reference video. It is also required for motion-control models: kling30_motion_control, kling30_motion_control_pro, wan_animate_720p, dreamactor_m2, happyhorse_motion_control.

input_video_url (optional)​

URL alternative to input_video.

audio_reference (optional)​

Binary multi-part audio upload for models that accept reference audio, including seedance2_*. Set video_audio=true so the output includes audio. You can refer to the track as @Audio1 in video_prompt; Astria adds that token on provider paths that require it when no @Audio token is present.

audio_reference_url (optional)​

URL alternative to audio_reference.

video_audio (optional)​

Boolean. Generate an audio track when the selected model supports generated audio, including seedance2_*. Defaults to false. Set it to true when using audio_reference.

video_upscale_model (optional)​

Post-process the generated video with an upscaler. enum: seedvr2.

video_upscale_target_resolution (optional)​

Target for video_upscale_model. enum: 720p, 1080p, 2k, 4k. Defaults to 1080p when an upscaler is selected.

video_fps_model (optional)​

Post-process the generated video with frame interpolation. enum: video_fps_increaser. It can be combined with video upscaling.

For Seedance 2 and Seedance 2.5, first/last-frame mode cannot be combined with image_references, image_reference_urls, input_video, or audio_reference. Use either first/last frames or reference images/video/audio in one request.

Video with ordered image references​

curl -X POST -H "Authorization: Bearer $API_KEY" \
  https://api.astria.ai/tunes/$TUNE_ID/prompts \
  -F 'prompt[video_model]=seedance2_fast_720p' \
  -F 'prompt[video_prompt]=Move from the product detail into the full look, preserving the garment design' \
  -F 'prompt[video_duration]=8' \
  -F 'prompt[image_references][]=@/path/to/detail.jpg' \
  -F 'prompt[image_references][]=@/path/to/full-look.jpg'

For hosted images, replace the last two fields with repeated URL fields:

-F 'prompt[image_reference_urls][]=https://example.com/detail.jpg' \
-F 'prompt[image_reference_urls][]=https://example.com/full-look.jpg'

The created prompt JSON returns the attached images as an ordered image_references array of URLs. Model-specific reference limits still apply.

Backwards-compatible legacy syntax: the --video --video_model … --video_prompt "…" --duration N CLI flags inside text are still accepted and promoted into the dedicated columns server-side. New integrations should use the form fields above.

Returns​

Returns a prompt object if successful which will start processing if tune is processed.

POST /tunes/:id/prompts​

curl -X POST -H "Authorization: Bearer $API_KEY" https://api.astria.ai/tunes/1/prompts \
          -F prompt[text]="a painting of ohwx man in the style of Van Gogh" \
          -F prompt[negative_prompt]="old, blemish, wrin" \
          -F prompt[super_resolution]=true \
          -F prompt[face_correct]=true \
          -F prompt[callback]="https://optional-callback-url.com/to-your-service-when-ready?prompt_id=1"

Response​

{
  "id": 1,
  "callback": "https://optional-callback-url.com/to-your-service-when-ready?prompt_id=1",
  "text": "a painting of ohwx man in the style of Van Gogh",
  "negative_prompt": "old, blemish, wrinkles, mole",
  "cfg_scale": null,
  "steps": null,
  "seed": null,
  "trained_at": null,
  "started_training_at": null,
  "created_at": "2022-10-06T16:12:54.505Z",
  "updated_at": "2022-10-06T16:12:54.505Z",
  "tune_id": 1,
  "url": "http://api.astria.ai/tunes/1/prompts/1.json"
}