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)

A video model family such as seedance25, seedance2_fast, veo31_fast, or kling30_pro. Pick the output resolution with video_resolution and audio with video_audio. The live catalog of families, their resolutions, and their default resolution is returned in video_model_families by GET https://api.astria.ai/cli/models; see Image2Video for the current table. An unknown video_model returns a 422 that lists the accepted families.

Legacy variant ids that bake the resolution and audio into the name (seedance25_720p, seedance2_fast_480p, veo31_fast_audio_1080p, ...) are still accepted and mean the same model as before. An explicit video_resolution or video_audio moves a variant id within its family, so video_model=seedance25_720p with video_resolution=1080p renders seedance25_1080p.

Accepted variant ids: 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_resolution (optional)

Output resolution within the video_model family, for example 480p, 720p, 1080p, or 4k. Allowed values are listed per family as resolutions in GET /cli/models. When omitted, a family uses its default_resolution and a legacy variant id keeps its own resolution. An unsupported value returns a 422 such as video_resolution must be one of 480p, 720p, 1080p for seedance25. Families without a resolution choice (for example kling30_pro, seedance25_draft, and cinematic_video) take no video_resolution; sending one returns a 422.

Inside prompt text, the equivalent flag is --video_resolution 1080p.

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.

For families that price audio as a separate model (Veo 3.1 Fast, Veo 3.1 Lite, Seedance 1.5 Pro, LTX-2 Fast, Kling 2.6 Pro, Kling 3.0 Standard, and Kling 3.0 Pro), video_audio=true selects the family's audio variant: video_model=veo31_fast + video_resolution=1080p + video_audio=true renders veo31_fast_audio_1080p. Other families pass video_audio to the model as generate_audio. An explicit video_audio=false also moves an _audio variant id to its silent variant.

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 a model family and resolution

curl -X POST -H "Authorization: Bearer $API_KEY" \
  https://api.astria.ai/tunes/$TUNE_ID/prompts \
  -F 'prompt[video_model]=seedance25' \
  -F 'prompt[video_resolution]=1080p' \
  -F 'prompt[video_prompt]=A lone explorer walks across endless dunes at sunrise, cinematic.' \
  -F 'prompt[video_duration]=5' \
  -F 'prompt[aspect_ratio]=16:9' \
  -F 'prompt[video_audio]=true'

Omit prompt[video_resolution] to render at the family's default resolution (720p for seedance25). The legacy form prompt[video_model]=seedance25_1080p creates the same prompt.

For a family with a separate audio variant, video_audio picks the variant:

-F 'prompt[video_model]=veo31_fast' \
-F 'prompt[video_resolution]=1080p' \
-F 'prompt[video_audio]=true'   # renders veo31_fast_audio_1080p

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_resolution … --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.

For video prompts the object includes the resolved model:

• video_model — the resolved variant id, for example seedance25_1080p. This is unchanged for existing integrations, including prompts created with a family name.
• video_model_family — the family, for example seedance25.
• video_resolution — the resolution, for example 1080p, or null for families without a resolution choice.
• video_audio — whether audio was requested.

{
  "id": 2,
  "is_video": true,
  "video_model": "seedance25_1080p",
  "video_model_family": "seedance25",
  "video_resolution": "1080p",
  "video_prompt": "A lone explorer walks across endless dunes at sunrise, cinematic.",
  "video_duration": 5,
  "video_audio": true
}

POST /tunes/:id/prompts

cURL

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" 

Node.js

const fetch = require(`node-fetch');
const FormData = require('form-data');

const API_URL = 'https://api.astria.ai/tunes/1/prompts';
const API_KEY = 'YOUR_API_KEY'; // Replace with your actual API key
const headers = { Authorization: `Bearer ${API_KEY}` }

const form = new FormData();
form.append('prompt[text]', 'a painting of ohwx man in the style of Van Gogh');
form.append('prompt[negative_prompt]', 'old, blemish, wrin');
form.append('prompt[super_resolution]', true);
form.append('prompt[face_correct]', true);
form.append('prompt[callback]', 'https://optional-callback-url.com/to-your-service-when-ready?prompt_id=1');

fetch(API_URL, {
  method: 'POST',
  headers: headers,
  body: form
}).then(response => response.json())

Python

import requests

API_URL = 'https://api.astria.ai/tunes/1/prompts'
API_KEY = 'YOUR_API_KEY'  # Replace with your actual API key

headers = {
    'Authorization': f'Bearer {API_KEY}'
}

data = {
  'prompt[text]': 'a painting of ohwx man in the style of Van Gogh',
  'prompt[negative_prompt]': 'old, blemish, wrin',
  'prompt[super_resolution]': True,
  'prompt[face_correct]': True,
  'prompt[callback]': 'https://optional-callback-url.com/to-your-service-when-ready?prompt_id=1'
}
files = []
files.append((f"prompt[input_image]", load_image(prompt['input_image'])))

response = requests.post(API_URL, headers=headers, files=files, data=data)

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"
}