Tasks

Create an asynchronous generation task

Validates the model input, reserves the estimated charge, chooses an available deployment, and creates a task in queued state. HTTP 202 means the task was accepted; it does not mean generation has completed.

An Idempotency-Key is optional but strongly recommended. For the same account and the same API key, repeating a key with the same normalized model, input, and callback URL within 24 hours returns the original task and does not reserve funds twice. A sibling API key cannot replay the mapping: it receives 409 Conflict without the original task ID. Reusing the key with different request semantics also returns 409 Conflict. Callbacks are optional and are validated against private/loopback destinations before acceptance.

post/api/v1/jobs/createTask

Request

  • Base URL: https://api.spicyapi.ai
  • URL: https://api.spicyapi.ai/api/v1/jobs/createTask
  • Auth: HTTP bearer

Query parameters

waitinteger

Seconds to hold the connection open waiting for the task to reach a terminal state, so you do not have to write a polling loop for the first call. Values above 60 are clamped to 60; anything that is not a positive integer is ignored rather than rejected, because a typo in an optimisation parameter should not fail a generation that would otherwise succeed.

Reaching a terminal state within the budget returns 200 with the same task record recordInfo returns. Running out of budget returns the ordinary 202 — identical to omitting wait — and you poll from there. Disconnecting stops the wait and nothing else: the task keeps running and is billed as usual.

The ceiling stays well under the 100-second edge timeout on purpose. Past that line the connection is cut by the CDN rather than by us, and the caller gets a 524 carrying neither the task ID nor any resumable state — while the task exists and the funds are already held.

Headers

Idempotency-Keystring

Stable key for one logical task submission; retained for 24 hours per account and bound to both the submitting API key and normalized request fingerprint. A sibling key receives 409 without the original task ID.

X-Spicy-Retentionstring

Retention for this one task, in whole seconds. It applies to both the generated outputs and the stored request text. The effective value is always min(header, account setting, platform maximum): a request can only shorten retention, never extend it. 0 is valid and means the outputs are removed as soon as the task reaches a terminal state. Values that cannot be applied never fail the request: a negative number is clamped to 0, a value above the ceiling is clamped to the ceiling, and a value that is not a decimal integer is ignored so the account setting applies. The effective result is always reported back in retention on the task record. Accepted by createTask and stream. retry inherits the source task's effective value and ignores this header, so one task family never ends up with two different expiry times. quote does not accept it because it does not create a task.

Request body

modelstring required

Exact model value from the model catalog.

inputobject required

Validated against the selected model's inputSchema. Declared image fields accept public HTTPS URLs, committed spicy:// file URIs, legacy persona image references spicy://p/<id> (personas became characters in your personal asset library on 2026-10-12; these references keep resolving to the same images, only in your personal library and only with API keys you created in your personal workspace, so team workspace keys, another account's id and an unknown id all get the same rejection, and they are refused in video, audio and file fields), saved assets as spicy://a/<id> in the media field of the matching kind (the asset must be in the library of the key's workspace: a personal key uses your personal library, a team key uses that team's library; any other asset gets the same rejection as an unknown id), or standard Base64 Data URIs (image/jpeg, image/png, image/webp, image/gif). Inline images are limited to 1048576 decoded bytes and 8388608 pixels each, 8192 pixels per side, and 16 images / 16777216 pixels in total. The complete JSON request must fit within 2097152 bytes. Model-specific limits still apply. Bare Base64, SVG and inline audio/video are not accepted; use HTTPS or file uploads instead. Inline images are stored as account-bound uploaded files; returned input contains file URIs, never the original Base64 bytes. Quote validation does not upload or reserve funds. If the model's inputSchema declares seed and you omit it, we pick a random seed for this task, so two identical requests do not come back with the same output. The chosen seed is returned in the task's input; pass it back to hold the draw steady (a fixed seed keeps runs comparable, it does not guarantee an identical result). On the few models that cannot honour seed on every request, we still vary it where it applies but do not echo it. A seed you send yourself is always used as given. Models that offer an economy route declare the boolean official_fallback (default true): the request runs on the economy route first and, if that fails and the field is true, is retried once on the official route. The hold is the highest price the request can be billed at (the official price while the fallback is allowed); you are billed the price of the route that actually produced the result and the rest of the hold is released. With false, only the economy route is tried and the hold is the economy price.

callBackUrlstring uri

Optional public HTTPS endpoint for terminal task delivery. http:// URLs are rejected: the delivery carries the prompt and signed result links. Explicit ports other than 443 and 80 are rejected, and URL credentials are rejected. The hostname must resolve to public IP addresses and is checked again when connecting. Invalid values return HTTP 400 with code 400, msg "Invalid callback URL", and request_id.

quoteIdstring

Signed quote returned by jobs/quote for this same account, API key and request. Does not replace Idempotency-Key.

expectedCoststring

Decimal USD amount encoded as a string to avoid binary floating-point loss.

Response

Returned only when wait was supplied and the task reached a terminal state inside that budget. The body is the task record, identical in shape to recordInfo. A terminal state is not necessarily a success - check data.state.

code200 required
msg'success' required
request_idstring required

Correlation identifier. Include it in support requests.

Changes

No recorded changes to this operation across all 1 revision of this API.