Sociaro

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"}
  • usd is the price in USD for one unit of of. unit is second, image, 1M_tokens or job. of says what is counted: output_video, output_image, input_video, input_image, input_audio, input_and_output_video, billed_video, tokens or minimum.
  • when holds the modifiers: the request fields and values the price applies to (resolution, rendering_speed, fps and so on, named as in the model's input_schema; where the schema nests a field, as Kling's resolution under settings, the key is that field's own name). A field you left out is its default (upscale false). The other keys are facts derived from the request, not fields: the booleans audio (the request asks for sound; on Kling, settings.audio is native), input_video, input_images and fps_over_30. An empty when means the price always applies.
  • A price by image size is the unit image with the size in when as size_tier (1K or 2K, the tier the generator reports for the finished image). Both Qwen image ids carry it: alibaba/qwen-image-3-pro with two different prices, alibaba/qwen-image-3 with the same price at both.
  • A job's price is the sum of every component whose when matches the request, each multiplied by its quantity, except two kinds that are never added:
  • a component with approx: true restates another component in other units (Seedance's approximate dollars per second restate its per-token price)
  • a component with floor: true is the least the whole job is charged, so the price is the larger of the sum and its usd, where for Seedance's minimum for a job with input video (its usd is the floor for a 4 s output) the floor of an output of d seconds is its usd x (4 + d) / 8
  • On Leda, upscale: true (or its deprecated alias enhance: true) bills at another resolution's rate: the resolution's row carries upscale: false and a second row carries upscale: true at 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.
  • metered is request when the price follows from your request, and result when it follows from what the generator reports (generated tokens, the produced size tier, the measured length of an input clip). A component can also carry free: N (the first N are not charged), approx: true or floor: true.
  • For metered: "request" rows you can compute the charge from the components. For a token-metered model (Seedance: 1M_tokens rows and a job minimum) you cannot: ask the estimate for the total.
  • GET /v2/models answers 503 unavailable with "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

  • 400 estimate_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> is audio, video, video_url, reference_video_urls or content[].video_url.
  • 503 unavailable: "the price of this request is temporarily unavailable". Retry shortly.
  • 401, 403 and 404 as on submit. The 403 is 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.