Models and prices — the catalogue and the estimate
This page covers GET /v2/models and POST /v2/jobs/estimate; the envelope is on Jobs API.
The model list
GET /v2/models is the list. There is no table here on purpose: a list printed on a page goes
stale the day a model is added, and this endpoint cannot. It answers with every model. Each entry has ten fields:
id, name, description, type, media, preview_image_url, max_output_count, max_runtime_sec, pricing and
input_schema. Also present are async and output_types, and prompt_enhance (the modes the model accepts) on a
model that takes it:
curl https://api.sociaro.com/v2/models -H "Authorization: Bearer $SOCIARO_API_KEY"
Video and image today — ByteDance's Seedance line, Alibaba's Wan, HappyHorse and Qwen models, Kling's video
models (Kling's 3.x image models, kling/kling-v3 and kling/kling-v3-omni, are /v1 only; kling/kling-4.0-image is served on both /v1 and /v2), Pruna's image and video models, and MiniMax's H3 video models (served only on /v2).
/v1 serves far more, including everything synchronous; Generations API lists which /v1 route
serves which model.
name is the model's display name and description is one or two sentences on what it makes and what sets
it apart; both are there for a person choosing a model (the model you send is the id). A model's entry
carries its input_schema, in which every field, nested ones too, has a short description, and the
required fields there are the whole minimal request. Some models need a media input as well as a prompt — an image-to-video model needs its
first frame — and the schema names it. A boolean option carries a default when the value it starts in is known
(watermark, generate_audio and the like); one without a default has none we can state, so leave it unset
rather than assume.
type
type is one string saying what the model does. New values can be added; treat a value you do not know as
other.
type |
the model |
|---|---|
text-to-video |
makes a video from a prompt alone |
image-to-video |
makes a video that starts from an image you send (the first frame) |
reference-to-video |
makes a video from a prompt and reference images or clips of a subject or style |
video-to-video |
edits, replaces part of, or re-renders a video you send |
video-upscale |
returns the video you send at a higher resolution |
avatar-video |
makes a talking video from a portrait and a sound or script |
omni-video |
one model id that covers several of the video modes above (prompt only, first and last frame, references) and picks the mode from what input carries: Seedance, Kling Omni, alibaba/wan-3-video, MiniMax H3 and Leda |
text-to-image |
makes an image from a prompt |
image-to-image |
redraws an image you send, guided by a prompt |
image-edit |
changes part of an image you send (inpaint, reframe, background, instruction edit) |
vectorize |
turns a raster image into a vector file |
preview_image_url
preview_image_url is on every model: the address of a sample image (WebP, 640 px wide) on docs.sociaro.com, or
null for a model that has none yet. Treat null as "no image".
input_schema
input_schema is JSON Schema draft 2020-12, closed and enforced at submit (see Model inputs).
A size property also carries x-min-pixels, x-max-pixels, x-min-aspect-ratio and x-max-aspect-ratio: bounds on
a "W*H" string's total pixels and on width over height, which JSON Schema cannot express. A size that matches the
pattern but is outside them is refused; x-max-pixels is absent where there is no upper limit.
pricing
pricing is what a job on the model costs, in US dollars, and has three parts. rows has one row per charge
(charge names the unit, options the choice the row is for, price the amount, note a qualification where the
row needs one; from and until are always null here: the catalogue shows the price in force now), and notes
says what else matters about how the model is billed. components is the same prices in machine-readable form, one
component per row and in the same order:
{"unit": "second", "of": "output_video", "usd": 0.126, "when": {"resolution": "720p", "audio": true}, "metered": "request"}
usdis the price in USD for oneunitofof.unitissecond,image,1M_tokensorjob.ofsays what is counted:output_video,output_image,input_video,input_image,input_audio,input_and_output_video,billed_video,tokensorminimum.whenholds the modifiers: the request fields and values the price applies to (resolution,rendering_speed,fpsand so on, named as in the model'sinput_schema; where the schema nests a field, as Kling'sresolutionundersettings, the key is that field's own name). A field you left out is its default (upscalefalse). The other keys are facts derived from the request, not fields: the booleansaudio(the request asks for sound; on Kling,settings.audioisnative),input_video,input_imagesandfps_over_30. An emptywhenmeans the price always applies.- A price by image size is the unit
imagewith the size inwhenassize_tier(1Kor2K, the tier the generator reports for the finished image). Both Qwen image ids carry it:alibaba/qwen-image-3-prowith two different prices,alibaba/qwen-image-3with the same price at both. - A job's price is the sum of every component whose
whenmatches the request, each multiplied by its quantity, except two kinds that are never added: - a component with
approx: truerestates another component in other units (Seedance's approximate dollars per second restate its per-token price) - a component with
floor: trueis the least the whole job is charged, so the price is the larger of the sum and itsusd, where for Seedance's minimum for a job with input video (itsusdis the floor for a 4 s output) the floor of an output of d seconds is itsusdx (4 + d) / 8 - On Leda,
upscale: true(or its deprecated aliasenhance: true) bills at another resolution's rate: the resolution's row carriesupscale: falseand a second row carriesupscale: trueat the rate it is billed at. A reference video is billed per second of the length you request for the output, for each clip, not per second of the clip. meteredisrequestwhen the price follows from your request, andresultwhen it follows from what the generator reports (generated tokens, the produced size tier, the measured length of an input clip). A component can also carryfree: N(the first N are not charged),approx: trueorfloor: true.- For
metered: "request"rows you can compute the charge from the components. For a token-metered model (Seedance:1M_tokensrows and ajobminimum) you cannot: ask the estimate for the total. GET /v2/modelsanswers503unavailablewith "model prices are temporarily unavailable" while your organisation's prices cannot be read yet, for example just after the service starts. Retry shortly.
The prices in the list are your organisation's prices, rows and components alike: the figure the estimate uses
and the figure a job is charged at, so the list, the estimate and cost_usd agree. Another organisation may see other
numbers. The public price page on docs.sociaro.com shows list prices and is not the same thing. cost_usd on the job
is always what was charged. A model with no price has no pricing.
Estimate
POST /v2/jobs/estimate tells you what a request would cost before you send it. It takes the same body as
POST /v2/jobs (model, input, output) and the same Authorization header. No job is created and nothing is
charged or held. An Idempotency-Key header is ignored.
The body is limited to 2 MB (2,097,152 bytes), where a submit takes more. Send an inline data: file as a URL that serves the same file:
the estimate reads it there (for a model priced on the length of an input file, it measures that file). A larger body is answered 413 (request_too_large).
curl https://api.sociaro.com/v2/jobs/estimate \
-H "Authorization: Bearer $SOCIARO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "kling/kling-3.0-t2v",
"input": {"prompt": "a paper boat drifting down a rain-soaked street",
"settings": {"resolution": "720p", "duration": 5}}
}'
{"model": "kling/kling-3.0-t2v", "estimated_cost_usd": 0.42, "estimate_kind": "exact"}
model repeats the id you sent. estimated_cost_usd is in US dollars, not rounded, at your organisation's price at the moment you ask. If a price
changes between the estimate and the job, cost_usd follows the price in force when the job is charged. Prompt
enhancement is free and is in neither number.
estimate_kind
estimate_kind is an addition to the two fields you asked for, and you may ignore it if you only need the number. It
says how cost_usd of the finished job relates to the estimate, because some models are billed on something only the
finished job shows:
estimate_kind |
cost_usd of the finished job |
models |
|---|---|---|
exact |
equals the estimate | Kling without input video, Ideogram, Leda, Pruna p-image, p-image-edit and p-video, Alibaba images except alibaba/qwen-image-3-pro |
upper_bound |
is never above the estimate; equal or lower | Seedance (billed per generated token: the estimate is the token count at the published 16:9 frame size plus 10%), MiniMax and Alibaba video without reference clips, alibaba/qwen-image-3-pro, Pruna Reference |
approximate |
can be slightly above or below | the price depends on the length of a video or audio file you send (Pruna Avatar with a voice_script and no audio is priced at the longest avatar): Kling 4.x with input videos, Pruna Avatar, Replace and Upscale, alibaba/happyhorse-video-edit, alibaba/wan-3-video and MiniMax with reference clips |
For an approximate model we read the length of the file ourselves when you ask for the estimate, from the file's own
header, and price that; the generator's own meter can differ slightly, so no bound is promised.
What is checked
The key is checked first (401), then the body. Invalid input is a 400 with error.type invalid_input: the same checks, with
the same message, as a submit. Two things the estimate does not check, so a 200 here is not a promise that submit accepts
the same body: your balance (an estimate is free, so a key with no balance may ask), and, for Kling, whether an
element or voice you reference exists in your library.
Other answers
400estimate_unavailable: the price depends on the length of an input file and we could not read it, so it cannot be priced. The message reads "the price depends on the length of input., which could not be read; submitting is unaffected", where <field>isaudio,video,video_url,reference_video_urlsorcontent[].video_url.503unavailable: "the price of this request is temporarily unavailable". Retry shortly.401,403and404as on submit. The403is the one a feature switch gives: the model needs a feature your organisation does not have switched on.- This route never answers
insufficient_balance.
No answer of this route carries job_created.