{"openapi":"3.1.0","info":{"title":"auray-serverless/stabilityai-stable-diffusion-3","version":"1.0.0","description":"`POST https://queue.auray.run/auray-serverless/stabilityai-stable-diffusion-3` submits; the response carries a `request_id` and the three URLs to use next.\n\n`POST https://auray.run/auray-serverless/stabilityai-stable-diffusion-3` is the same request run synchronously: the connection is held and the response is the model's OUTPUT, the same document the result URL would have answered. A request that usually takes longer than a run may hold its connection is refused `400 model_not_synchronous` there before anything is charged, naming `expected_seconds` and `wait_ceiling_seconds` — submit it to the queue instead. Past the deadline a run is `504 run_timed_out` with `X-Auray-Request-Timeout-Type: user` — the request is still alive, running and charged or, while it waits to start, not yet charged (`charged` says which) — so poll `status_url` rather than resending, or resend with the same `idempotency_key` to be handed this request again instead of a second one. A run holds one of the connections this platform, this product and your account may keep waiting; with all of them in use it is refused `429 wait_capacity` with `Retry-After` before anything is charged (`charged: false`), and retrying after that pause is safe.\n\nOne of Auray's catalogue models, billed once in credits. Whether it runs right now is `GET /v1/catalogue`'s `addresses` (no key needed): `connected` runs; `described` answers `501 model_not_connected` and `paused` `503 model_disabled`, both before anything is charged.\n\nPrice: Credits per megapixel (counted as `width*height*steps+ultralytics.steps@48`): 0.1034. From 1.0486 to 17.4763 megapixels a request. Quoted when you submit, at the most the request can cost; the charge settles to what the job cost and never above the quote.\n\nFields as published for this model.\n\nEvery error code is explained at https://auray.ai/docs/api/errors.","contact":{"url":"https://auray.ai/docs"},"x-auray-model-id":"auray-serverless-stabilityai-stable-diffusion-3","x-auray-hosted-by":"auray-serverless","x-auray-scope":"image:write","x-auray-scopes":["image:write","external:write"],"x-auray-price":{"kind":"quoted","note":"Credits per megapixel (counted as `width*height*steps+ultralytics.steps@48`): 0.1034. From 1.0486 to 17.4763 megapixels a request. Quoted when you submit, at the most the request can cost; the charge settles to what the job cost and never above the quote.","rule":{"unit":"megapixel","counts":"width*height*steps+ultralytics.steps@48","counts_request":true,"bands":[{"when":{},"credits_per_unit":0.1034,"min_units":1.0486,"max_units":17.4763,"max_inputs":{}}]},"metered":true},"x-auray-surface-enabled":true},"servers":[{"url":"https://queue.auray.run"},{"url":"https://auray.run"}],"paths":{"/auray-serverless/stabilityai-stable-diffusion-3":{"post":{"operationId":"submit","summary":"Run auray-serverless/stabilityai-stable-diffusion-3","tags":["Queue"],"parameters":[{"name":"wait","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":300},"description":"Hold the request open until the job settles, up to 300 seconds. The answer is still a status document; `timed_out` says the wait ran out rather than the job failing. One product refuses it outright and says so with `wait_unsupported`."},{"name":"logs","in":"query","required":false,"schema":{"type":"string","enum":["1","0","true","false"]},"description":"Include the runner's log lines on a read. Off by default, because a status polled at 10 Hz that carries a growing log is the same lines paid for a hundred times."},{"name":"webhook","in":"query","required":false,"schema":{"type":"string","format":"uri"},"description":"An https address to POST this job's outcome to once, beside any endpoint the account has registered. Checked when it is stored and again before it is sent: https only, no user-info, no private or loopback host, at most 2,000 characters. Signed `Auray-Signature v2` with a `kid`; verify it against our JWKS. No ownership challenge here, so the body names the account the job belongs to in `account` (the `id` `GET /v1/me` returns), inside what the signature covers: a receiver compares it with its own and refuses anything else."},{"name":"fal_webhook","in":"query","required":false,"schema":{"type":"string","format":"uri"},"description":"An https address to POST this job's outcome to once, beside any endpoint the account has registered. Checked when it is stored and again before it is sent: https only, no user-info, no private or loopback host, at most 2,000 characters. Signed `Auray-Signature v2` with a `kid`; verify it against our JWKS. No ownership challenge here, so the body names the account the job belongs to in `account` (the `id` `GET /v1/me` returns), inside what the signature covers: a receiver compares it with its own and refuses anything else. An alias for `webhook`; sending both with different values is refused with `conflicting_options`."},{"name":"max_queue_length","in":"query","required":false,"schema":{"type":"integer","minimum":0,"maximum":2147483647},"description":"Refuse with 429 `queue_too_long` rather than queue behind more than this many waiting requests. `0` is a real value and means \"only if nobody is waiting\". Decided before anything is charged. On a model that does not queue — every catalogue model today, whose `lifecycle.queue` in `GET /v1/models` is `refuses` — sending it is refused 422 `queue_not_offered` before anything is charged."},{"name":"fal_max_queue_length","in":"query","required":false,"schema":{"type":"integer","minimum":0,"maximum":2147483647},"description":"Refuse with 429 `queue_too_long` rather than queue behind more than this many waiting requests. `0` is a real value and means \"only if nobody is waiting\". Decided before anything is charged. On a model that does not queue — every catalogue model today, whose `lifecycle.queue` in `GET /v1/models` is `refuses` — sending it is refused 422 `queue_not_offered` before anything is charged. An alias for `max_queue_length`; sending both with different values is refused with `conflicting_options`."},{"name":"X-Auray-Priority","in":"header","required":false,"schema":{"type":"string","enum":["normal","low"]},"description":"`low` puts this request behind every normal one. Nothing else changes. On a model that does not queue — every catalogue model today, whose `lifecycle.queue` in `GET /v1/models` is `refuses` — sending it is refused 422 `queue_not_offered` before anything is charged."},{"name":"X-Fal-Queue-Priority","in":"header","required":false,"schema":{"type":"string","enum":["normal","low"]},"description":"`low` puts this request behind every normal one. Nothing else changes. On a model that does not queue — every catalogue model today, whose `lifecycle.queue` in `GET /v1/models` is `refuses` — sending it is refused 422 `queue_not_offered` before anything is charged. An alias for `X-Auray-Priority`; sending both with different values is refused with `conflicting_options`."},{"name":"X-Auray-Request-Timeout","in":"header","required":false,"schema":{"type":"number","minimum":1,"maximum":86400},"description":"Seconds to wait for a seat. A request still waiting past it is failed `request_timeout` and refunded. It is a time-to-START and never a bound on inference: a job that has been dispatched is not stopped by it. On a model that does not queue — every catalogue model today, whose `lifecycle.queue` in `GET /v1/models` is `refuses` — it is accepted and has nothing to bound: such a model starts at once or refuses at once."},{"name":"X-Fal-Request-Timeout","in":"header","required":false,"schema":{"type":"number","minimum":1,"maximum":86400},"description":"Seconds to wait for a seat. A request still waiting past it is failed `request_timeout` and refunded. It is a time-to-START and never a bound on inference: a job that has been dispatched is not stopped by it. On a model that does not queue — every catalogue model today, whose `lifecycle.queue` in `GET /v1/models` is `refuses` — it is accepted and has nothing to bound: such a model starts at once or refuses at once. An alias for `X-Auray-Request-Timeout`; sending both with different values is refused with `conflicting_options`."},{"name":"X-Auray-Covered-Only","in":"header","required":false,"schema":{"type":"string","enum":["1","true"]},"description":"Run this job only if a pass or a promotion of yours pays for it. A job neither pays for is refused 409 `not_covered` before anything is held or charged — or, when your pass had ended by the time the job started, refunded and refused so — where without this header your credits would pay for it; a job your plan runs only through a pass is refused as the plan refuses it (`model_not_in_plan`, `pass_does_not_cover`). For a job it lets through, the submit's answer on `queue.auray.run` says `credits_charged: 0` and what paid in `coverage`, and so does `GET /v1/jobs/{id}`; a run on `auray.run` answers the job's output, which says neither — read `GET /v1/jobs/{id}` with its `request_id`. `true` is read as `1`; any other value as no header."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Input"}}}},"responses":{"200":{"description":"Accepted, and charged and running — or, when the platform is full, waiting in the queue and charged when it starts: `credits_charged` is what has been taken, `credits_quoted` what it costs. Always this status: a submit's outcome is in `status`, never in the status line.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/QueueStatus"},{"type":"object","properties":{"product":{"type":"string","enum":["photo","music","threed","video","external"],"description":"Which of this platform's products ran it."},"provider_job_id":{"type":["string","null"],"description":"The id the job runs under, once it has been handed to its model — possibly while still `queued`; null before. Quote it to support."},"model":{"type":"string","description":"The address that ran it, echoed back."},"engine":{"type":["string","null"],"description":"The service's own name for the model that ran, where it reports one — a catalogue model's is its `id` on GET /v1/models; null otherwise. What `model` carried before it carried the address."},"attribution":{"type":["string","null"],"description":"The credit line the model's licence requires you to show; null where none is required."},"credits_charged":{"type":"integer","examples":[1],"description":"What this job cost. 0 on a replay, or when a pass or a promotion paid for it (`coverage` says which)."},"credits_quoted":{"type":"integer","examples":[1],"description":"What this job costs, in credits: the price it was quoted at submit. Equal to `credits_charged` once it has been charged; while it waits in the queue to start, `credits_charged` is 0 and this is what it will be charged when it starts (a cancel before then costs nothing) — and a replay of a job still waiting quotes the body that job was queued with, which is the one it runs, not the replay's. For a catalogue model it is the hold, and the settle may give part of it back — a settled read's `credits_charged` says what it finally cost."},"coverage":{"type":"object","description":"Present when a pass or a promotion paid for this job — `{\"by\": \"pass\", \"pass\": \"seedance-2-5\"}` or `{\"by\": \"promotion\"}`, and `credits_charged` is 0 — or when you hold a pass for this model that did not cover this job: `{\"by\": null, \"miss\": {\"pass\": \"video\", \"why\": \"door\"}}`, `why` being `door` (the pass does not work here) or `shape` (it does not cover this kind of job). Absent otherwise. Send `X-Auray-Covered-Only: 1` to run a job only if a pass or a promotion pays for it."},"credits_remaining":{"type":"integer","examples":[1],"description":"The balance after it."},"expected_seconds":{"type":"integer","examples":[1],"description":"A rough render time, for a progress bar; 0 where nothing is published."},"give_up_after_seconds":{"type":"integer","examples":[1],"description":"The longest this job may take from its submit: the longest it may wait to start (your X-Auray-Request-Timeout, or the product's queue deadline) plus the longest it may run before it is stopped and refunded. Waiting longer is waiting for nothing; the official clients wait this long by default. For a catalogue model the part it may run is its own reap as its registry row states it (`lifecycle.stall_ceiling_seconds` on GET /v1/models); otherwise these are the published limits: we may lengthen them during an incident, never shorten them."},"replayed":{"type":"boolean","description":"`true` when your `idempotency_key` matched a job this platform already had. Nothing was charged and nothing was rendered twice."},"waited":{"type":"boolean","description":"Present when `wait` was asked for. The rest of this group comes with it."},"timed_out":{"type":"boolean","description":"The wait ran out before the job settled. Still a 2xx, never a 408 or 504 — a library that retries on those would resubmit and you would pay twice. Poll `status_url`."},"wait_declined":{"type":"string","enum":["platform_busy","product_busy","account_busy"],"description":"No seat was free to hold the connection with, so the request was answered at once. `platform_busy`: no product would have helped. `product_busy`: another product's queue might. `account_busy`: you are already waiting on every seat your plan's lanes allow. The job is running either way; poll it."},"status_url":{"type":"string","description":"Poll this."},"response_url":{"type":"string","description":"Fetch the result from this once the status is COMPLETED."},"cancel_url":{"type":"string","description":"`PUT` to this to ask for a cancellation."}}}]}}}},"202":{"description":"The dispatch could not be confirmed (`dispatch_unresolved`): the charge stands, the request exists and is `IN_QUEUE`, and the body is its status document with `message` and `docs` beside it. Poll `status_url` — never resend under a new key, which would be a second charge. If it never starts, it is declared lost and refunded.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/QueueStatus"},{"type":"object","properties":{"status_url":{"type":"string","description":"Poll this."},"response_url":{"type":"string","description":"Fetch the result from this once the status is COMPLETED."},"cancel_url":{"type":"string","description":"`PUT` to this to ask for a cancellation."},"message":{"type":"string","description":"Why the dispatch could not be confirmed, and what to do."},"docs":{"type":"string","description":"The `dispatch_unresolved` entry on the errors page."}}}]}}}},"400":{"description":"A refusal: `error_type` is ConflictError or ValidationError. The code is in `error`, and every code is explained at https://auray.ai/docs/api/errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"A refusal: `error_type` is AuthenticationError. On `auray.run`, a request that ran and failed: `error_type` is AuthenticationError. The code is in `error`, and every code is explained at https://auray.ai/docs/api/errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"A refusal: `error_type` is PaymentError. On `auray.run`, a request that ran and failed: `error_type` is PaymentError. The code is in `error`, and every code is explained at https://auray.ai/docs/api/errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A refusal: `error_type` is PermissionError. On `auray.run`, a request that ran and failed: `error_type` is PermissionError. The code is in `error`, and every code is explained at https://auray.ai/docs/api/errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"A refusal: `error_type` is NotFoundError. On `auray.run`, a request that ran and failed: `error_type` is NotFoundError. The code is in `error`, and every code is explained at https://auray.ai/docs/api/errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"A refusal: `error_type` is ValidationError. The code is in `error`, and every code is explained at https://auray.ai/docs/api/errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A refusal: `error_type` is CancellationError or ConflictError. On `auray.run`, a request that ran and failed: `error_type` is CancellationError or ConflictError. The code is in `error`, and every code is explained at https://auray.ai/docs/api/errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"A refusal: `error_type` is GoneError or NotFoundError. On `auray.run`, a request that ran and failed: `error_type` is GoneError. The code is in `error`, and every code is explained at https://auray.ai/docs/api/errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"A refusal: `error_type` is PayloadTooLargeError. On `auray.run`, a request that ran and failed: `error_type` is PayloadTooLargeError. The code is in `error`, and every code is explained at https://auray.ai/docs/api/errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"A refusal of what the request says — an option, the body, a field — decided before anything is charged, or the model's own refusal of the request as it was written (its content filter, a value or a file it would not take), refunded: `error_type` is ContentPolicyError or ValidationError, and `detail` is a list of `{loc, msg, type}`, `loc` naming where (`[\"body\"]` when the parser names no field). On `auray.run`, a request that ran and failed: `error_type` is ContentPolicyError or ValidationError. The code is in `error`, and every code is explained at https://auray.ai/docs/api/errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"428":{"description":"A refusal: `error_type` is PreconditionError. On `auray.run`, a request that ran and failed: `error_type` is PreconditionError. The code is in `error`, and every code is explained at https://auray.ai/docs/api/errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A refusal: `error_type` is CapacityError or RateLimitError. On `auray.run`, a request that ran and failed: `error_type` is RateLimitError. The code is in `error`, and every code is explained at https://auray.ai/docs/api/errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"451":{"description":"A refusal: `error_type` is RegionError. On `auray.run`, a request that ran and failed: `error_type` is RegionError. The code is in `error`, and every code is explained at https://auray.ai/docs/api/errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"A refusal: `error_type` is ConfigurationError or InternalError. On `auray.run`, a request that ran and failed: `error_type` is ExecutionError or InternalError. The code is in `error`, and every code is explained at https://auray.ai/docs/api/errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"501":{"description":"This address is not open yet: `model_not_connected`, before anything is charged. `GET /v1/catalogue` lists which addresses run. A refusal: `error_type` is NotImplementedError. On `auray.run`, a request that ran and failed: `error_type` is NotImplementedError. The code is in `error`, and every code is explained at https://auray.ai/docs/api/errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"A refusal: `error_type` is ContentPolicyError or UpstreamError. On `auray.run`, a request that ran and failed: `error_type` is UpstreamError. The code is in `error`, and every code is explained at https://auray.ai/docs/api/errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The model, its family or its product is paused: `model_disabled`, `vendor_disabled` or `api_disabled`, with the reason, before anything is charged. A refusal: `error_type` is CapacityError or ConfigurationError or InternalError or UpstreamError. On `auray.run`, a request that ran and failed: `error_type` is CapacityError or ConfigurationError. The code is in `error`, and every code is explained at https://auray.ai/docs/api/errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"504":{"description":"A refusal: `error_type` is TimeoutError. On `auray.run`, a request that ran and failed: `error_type` is TimeoutError. The code is in `error`, and every code is explained at https://auray.ai/docs/api/errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/auray-serverless/stabilityai-stable-diffusion-3/requests/{request_id}":{"get":{"operationId":"result","summary":"The result","tags":["Queue"],"parameters":[{"name":"request_id","in":"path","required":true,"schema":{"type":"string"},"description":"The `request_id` the submit answered with."},{"name":"logs","in":"query","required":false,"schema":{"type":"string","enum":["1","0","true","false"]},"description":"Include the runner's log lines on a read. Off by default, because a status polled at 10 Hz that carries a growing log is the same lines paid for a hundred times."}],"responses":{"200":{"description":"The request and its output, once its status is COMPLETED.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/QueueStatus"},{"type":"object","properties":{"status_url":{"type":"string","description":"Poll this."},"response_url":{"type":"string","description":"Fetch the result from this once the status is COMPLETED."},"cancel_url":{"type":"string","description":"`PUT` to this to ask for a cancellation."}}}]}}}},"400":{"description":"The request has not finished: `request_in_progress`, with its `status` (`IN_QUEUE` or `IN_PROGRESS`), `queue_position` while it waits, and `Retry-After`. Nothing a job made part-way is its result: poll `status_url` until COMPLETED, then read this again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The request produced no output. `error_type` is AuthenticationError; the code is in `error` and the sentence in `detail`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"The request produced no output. `error_type` is PaymentError; the code is in `error` and the sentence in `detail`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The request produced no output. `error_type` is PermissionError; the code is in `error` and the sentence in `detail`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"The request produced no output. `error_type` is NotFoundError; the code is in `error` and the sentence in `detail`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The request produced no output. `error_type` is ConflictError or CancellationError; the code is in `error` and the sentence in `detail`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"The request produced no output. `error_type` is GoneError; the code is in `error` and the sentence in `detail`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request produced no output. `error_type` is PayloadTooLargeError; the code is in `error` and the sentence in `detail`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The request produced no output. `error_type` is ValidationError or ContentPolicyError; the code is in `error` and the sentence in `detail`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"428":{"description":"The request produced no output. `error_type` is PreconditionError; the code is in `error` and the sentence in `detail`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"The request produced no output. `error_type` is RateLimitError; the code is in `error` and the sentence in `detail`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"451":{"description":"The request produced no output. `error_type` is RegionError; the code is in `error` and the sentence in `detail`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"The request produced no output. `error_type` is ExecutionError or InternalError; the code is in `error` and the sentence in `detail`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"501":{"description":"The request produced no output. `error_type` is NotImplementedError; the code is in `error` and the sentence in `detail`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"The request produced no output. `error_type` is UpstreamError; the code is in `error` and the sentence in `detail`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The request produced no output. `error_type` is CapacityError or ConfigurationError; the code is in `error` and the sentence in `detail`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"504":{"description":"The request produced no output. `error_type` is TimeoutError; the code is in `error` and the sentence in `detail`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/auray-serverless/stabilityai-stable-diffusion-3/requests/{request_id}/status":{"get":{"operationId":"status","summary":"The status","description":"The same document the result answers, and it is 200 for a failed or unfinished request where the result is not: this address reports, the result IS the output. `GET /auray-serverless/stabilityai-stable-diffusion-3/requests/{request_id}/status/stream` streams this document as `text/event-stream` until it is COMPLETED; each stream closes after about five minutes with no final frame, having sent `retry:` at its top, so reconnect and keep reading until COMPLETED — every frame is the whole status, and the official clients reconnect on their own. It takes a seat from the same pool `wait` does and is 503 `stream_declined` when none is free.","tags":["Queue"],"parameters":[{"name":"request_id","in":"path","required":true,"schema":{"type":"string"},"description":"The `request_id` the submit answered with."},{"name":"logs","in":"query","required":false,"schema":{"type":"string","enum":["1","0","true","false"]},"description":"Include the runner's log lines on a read. Off by default, because a status polled at 10 Hz that carries a growing log is the same lines paid for a hundred times."}],"responses":{"200":{"description":"Where the request is.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/QueueStatus"},{"type":"object","properties":{"status_url":{"type":"string","description":"Poll this."},"response_url":{"type":"string","description":"Fetch the result from this once the status is COMPLETED."},"cancel_url":{"type":"string","description":"`PUT` to this to ask for a cancellation."}}}]}}}},"404":{"description":"A refusal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/auray-serverless/stabilityai-stable-diffusion-3/requests/{request_id}/cancel":{"put":{"operationId":"cancel","summary":"Ask for a cancellation","description":"202 means REQUESTED, not cancelled: a model can decline to stop and keep going, so the body carries `cancelled` and the settled charge for a caller who needs to know which happened. `POST` to the same address answers this platform's own cancel envelope, unchanged.","tags":["Queue"],"parameters":[{"name":"request_id","in":"path","required":true,"schema":{"type":"string"},"description":"The `request_id` the submit answered with."}],"responses":{"202":{"description":"The cancellation was accepted.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","const":"CANCELLATION_REQUESTED"},"request_id":{"type":"string"},"job_id":{"type":"string","description":"The same job reference as `request_id`, under the one name every host uses."},"product":{"type":"string"},"job_status":{"type":"string"},"settled":{"type":"boolean"},"cancelled":{"type":"boolean"},"credits_charged":{"type":["integer","null"],"description":"What the job cost after the cancel's refund — the ledger's net; null, with `settled_unknown`, when it could not be read."},"credits_reserved":{"type":["integer","null"],"description":"What was taken when the job was charged."},"settled_unknown":{"type":"boolean","description":"Present, and `true`, when the cancel happened and its figures could not be read."}},"required":["status","request_id","job_id","cancelled"]}}}},"400":{"description":"A refusal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"A refusal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","bearerFormat":"auray_sk_","description":"A platform key: auray_sk_ and 62 more characters, 71 in all. `Authorization: Bearer <key>` or `Authorization: Key <key>`; both are accepted on every address, and the scheme word is case-insensitive."}},"schemas":{"Input":{"type":"object","properties":{"inputs":{"type":"object","properties":{"seedImage":{"type":"string","format":"uri","examples":["https://v3b.auray.media/examples/samples/still-life.jpg"],"description":"Image used as a starting point for the generation (an http(s) URL; upload a local file first and send its read URL)."},"maskImage":{"type":"string","format":"uri","examples":["https://v3b.auray.media/examples/samples/still-life-mask.png"],"description":"Image used to specify which areas of the input image should be edited (an http(s) URL; upload a local file first and send its read URL). White marks the area to edit, black is preserved."}}},"positivePrompt":{"type":"string","description":"Text prompt describing elements to include in the generated output. Documented range: 2 to 3,000 characters."},"negativePrompt":{"type":"string","description":"Prompt to guide what to exclude from generation. Ignored when guidance is disabled (CFGScale ≤ 1). Documented range: 2 to 3,000 characters."},"width":{"type":"integer","default":1024,"description":"Width of the generated media in pixels. Documented range: 128 to 2,048."},"height":{"type":"integer","default":1024,"description":"Height of the generated media in pixels. Documented range: 128 to 2,048."},"seed":{"type":"integer","examples":[1],"description":"Random seed for reproducible generation. When not provided, a random seed is generated in the unsigned 32-bit range. Documented range: 0 to 9,223,372,036,854,776,000."},"steps":{"type":"integer","default":28,"description":"Total number of denoising steps. Higher values generally produce more detailed results but take longer. Documented range: 1 to 100."},"scheduler":{"type":"string","enum":["DDIM","DDIMScheduler","DDPMScheduler","DEISMultistepScheduler","Default","DPM++","DPM++ 2M","DPM++ 2M Beta","DPM++ 2M Exponential","DPM++ 2M Karras","DPM++ 2M SDE","DPM++ 2M SDE Beta","DPM++ 2M SDE Exponential","DPM++ 2M SDE Karras","DPM++ 2M SDE Uniform","DPM++ 2M Uniform","DPM++ 3M","DPM++ 3M Beta","DPM++ 3M Exponential","DPM++ 3M Karras","DPM++ 3M SDE Uniform","DPM++ 3M Uniform","DPM++ Beta","DPM++ Exponential","DPM++ Karras","DPM++ SDE","DPM++ SDE Beta","DPM++ SDE Exponential","DPM++ SDE Karras","DPM++ Uniform","DPM++ Uniform Beta","DPM++ Uniform Exponential","DPM++ Uniform Karras","DPMSolverMultistepInverse","DPMSolverMultistepScheduler","DPMSolverSinglestepScheduler","EDMDPMSolverMultistepScheduler","EDMEulerScheduler","Euler","Euler a","Euler Beta","Euler Exponential","Euler Karras","EulerAncestralDiscreteScheduler","EulerDiscreteScheduler","FlowMatchEulerDiscreteScheduler","Heun","HeunDiscreteScheduler","Heun Karras","IPNDMScheduler","IPNDM Uniform","IPNDM Uniform Beta","IPNDM Uniform Exponential","IPNDM Uniform Karras","KDPM2AncestralDiscreteScheduler","KDPM2DiscreteScheduler","LCM","LCMScheduler","LMS","LMSDiscreteScheduler","LMS Karras","PNDMScheduler","TCDScheduler","UniPC","UniPC 2M","UniPC 2M Karras","UniPC 2M Uniform","UniPC 3M","UniPC 3M Karras","UniPC 3M Uniform","UniPC Karras","UniPC Uniform","UniPC Uniform Beta","UniPC Uniform Exponential","UniPC Uniform Karras"],"description":"Scheduler to use for the diffusion process."},"CFGScale":{"type":"number","examples":[1],"description":"Guidance scale representing how closely the output will resemble the prompt. Higher values produce results more aligned with the prompt. Documented range: 0 to 30."},"strength":{"type":"number","default":0.8,"description":"Strength of the transformation. Lower values result in more influence from the original input. Documented range: 0 to 1."},"maskMargin":{"type":"integer","examples":[32],"description":"Extra context pixels around the masked region during inpainting. The model zooms into the masked area with these additional pixels for better integration. Documented range: 32 to 128."},"clipSkip":{"type":"integer","examples":[1],"description":"Number of layers to skip in the CLIP model. Documented range: 0 to 4."},"acceleratorOptions":{"type":"object","properties":{"cacheEndStep":{"type":"integer","examples":[1],"description":"Absolute step number to end caching. Must be greater than `cacheStartStep` and less than or equal to `steps`. Documented range: 1 or more."},"cacheEndStepPercentage":{"type":"integer","examples":[1],"description":"Percentage of steps to end caching. Alternative to `cacheEndStep`. Must be greater than `cacheStartStepPercentage`. Documented range: 1 to 100."},"cacheMaxConsecutiveSteps":{"type":"integer","default":3,"description":"Limits the maximum number of consecutive steps that can use cached computations before forcing a fresh computation. Documented range: 1 to 5."},"cacheStartStep":{"type":"integer","examples":[1],"description":"Absolute step number to start caching. Must be less than `cacheEndStep`. Documented range: 0 or more."},"cacheStartStepPercentage":{"type":"integer","examples":[1],"description":"Percentage of steps to start caching. Alternative to `cacheStartStep`. Must be less than `cacheEndStepPercentage`. Documented range: 0 to 99."},"teaCache":{"type":"boolean","description":"TeaCache acceleration for transformer-based models. Estimates step differences to skip redundant computations."},"teaCacheDistance":{"type":"number","default":0.5,"description":"Controls the aggressiveness of the TeaCache feature. Lower values prioritize quality, higher values prioritize speed. Documented range: 0 to 1."},"dbCache":{"type":"boolean","description":"DB Cache (CacheDiT) acceleration. Caches and reuses intermediate transformer block outputs to skip redundant computations."},"dbCacheThreshold":{"type":"number","default":0.25,"description":"Controls the sensitivity threshold for DB Cache. Lower values reuse cached blocks more aggressively, higher values prioritize quality. Documented range: 0 to 1."},"dbCacheSkipInterval":{"type":"integer","default":5,"description":"Controls how many steps to skip between cache refreshes. Higher values skip more steps for faster generation at the cost of quality. Documented range: 1 or more."}}},"outpaint":{"type":"object","properties":{"top":{"type":"integer","examples":[1],"description":"Number of pixels to extend to the top. Documented range: 0 or more."},"bottom":{"type":"integer","examples":[1],"description":"Number of pixels to extend to the bottom. Documented range: 0 or more."},"left":{"type":"integer","examples":[1],"description":"Number of pixels to extend to the left. Documented range: 0 or more."},"right":{"type":"integer","examples":[1],"description":"Number of pixels to extend to the right. Documented range: 0 or more."},"blur":{"type":"integer","examples":[1],"description":"Amount of blur to apply to the mask edge. Documented range: 0 to 32."}}},"lora":{"type":"array","items":{"type":"object","properties":{"model":{"type":"string","description":"LoRA model identifier."},"weight":{"type":"number","default":1,"description":"Strength of the LoRA influence. A value of 0 means no influence. Higher values increase the influence, and negative values can be used to steer away from the LoRA's style. Documented range: -4 to 4."}}}},"controlNet":{"type":"array","items":{"type":"object","properties":{"model":{"type":"string","enum":["auray-serverless:32@1","auray-serverless:33@1"],"description":"ControlNet model identifier."},"weight":{"type":"number","default":1,"description":"Strength of the ControlNet influence. A value of 0 means no influence. Higher values increase the influence, and negative values can be used to steer away from the guide image. Documented range: -4 to 4."},"guideImage":{"type":"string","format":"uri","examples":["https://v3b.auray.media/examples/samples/still-life.jpg"],"description":"Reference image for ControlNet guidance (an http(s) URL; upload a local file first and send its read URL)."},"controlMode":{"type":"string","enum":["balanced","controlnet","prompt"],"default":"balanced","description":"ControlNet guidance mode."},"endStep":{"type":"integer","examples":[1],"description":"Absolute step number to end ControlNet influence. Must be greater than `startStep` and less than or equal to `steps`. Documented range: 1 or more."},"endStepPercentage":{"type":"integer","examples":[1],"description":"Percentage of steps to end ControlNet influence. Must be greater than `startStepPercentage`. Documented range: 1 to 100."},"startStep":{"type":"integer","examples":[1],"description":"Absolute step number to start ControlNet influence. Must be less than `endStep`. Documented range: 0 or more."},"startStepPercentage":{"type":"integer","examples":[1],"description":"Percentage of steps to start ControlNet influence. Must be less than `endStepPercentage`. Documented range: 0 to 99."}}}},"ultralytics":{"type":"object","properties":{"CFGScale":{"type":"number","default":8,"description":"Face refinement guidance scale. Documented range: 0 to 50."},"confidence":{"type":"number","default":0.9,"description":"Confidence threshold for detection. Documented range: 0 to 1."},"inpaintSize":{"type":"integer","default":1024,"description":"Image size (in pixels) to use for each inpainting region. YOLO detects faces, crops the region, and scales it to this size before running diffusion. Set so most faces land in the 2–4× range of their original pixel size. Going beyond 8× may degrade identity resemblance. Documented range: 128 to 2,048."},"maskBlur":{"type":"integer","default":5,"description":"Mask feathering amount. Higher values create softer transitions between the enhanced face region and surrounding areas. Documented range: 0 to 100."},"maskPadding":{"type":"integer","default":5,"description":"Padding around detected face in pixels. Expands the refinement area to include surrounding context like hair and neck. Documented range: 0 to 20."},"negativePrompt":{"type":"string","description":"Negative prompt for detection."},"positivePrompt":{"type":"string","description":"Positive prompt for detection."},"steps":{"type":"integer","default":20,"description":"Number of face refinement steps. Documented range: 1 to 100."},"strength":{"type":"number","default":0.3,"description":"Refinement strength. Lower values preserve more of the original, higher values allow more aggressive reconstruction. Documented range: up to 1."}}},"outputType":{"type":"string","enum":["URL"],"default":"URL","description":"Image output type."},"outputFormat":{"type":"string","enum":["JPG","PNG","WEBP"],"default":"JPG","description":"Specifies the file format of the generated output. The available values depend on the task type and the specific model's capabilities. - \\`JPG\\`: Best for photorealistic images with smaller file sizes (no transparency). - \\`PNG\\`: Lossless compression, supports high quality and transparency (alpha channel). - \\`WEBP\\`: Modern format providing superior compression and transparency support. - \\`MP4\\`: Widely supported video container (H.264), recommended for general use. - \\`WEBM\\`: Optimized for web delivery. - \\`MOV\\`: QuickTime format, common in professional workflows (Apple ecosystem). - \\`GIF\\`: Animated image format (no audio), suitable for short loops or previews. - \\`MP3\\`: Compressed audio, smaller file size. - \\`WAV\\`: Uncompressed, high-quality audio. - \\`FLAC\\`: Lossless compression. - \\`OGG\\`: Open-source compressed audio format (Vorbis codec). - \\`SVG\\`: Scalable Vector Graphics. - \\`TIFF\\`: High-quality output supporting layers. - \\`GLB\\`: Binary glTF format for 3D models, including geometry, textures, and PBR materials. > [!NOTE] > \\*\\*Transparency\\*\\*: If you are using features like background removal or LayerDiffuse that require transparency, you must select a format that supports an alpha channel (e.g., \\`PNG\\`, \\`WEBP\\`, \\`TIFF\\`). \\`JPG\\` does not support transparency."},"outputQuality":{"type":"integer","default":95,"description":"Compression quality of the output. Higher values preserve quality but increase file size. Documented range: 20 to 99."},"safety":{"type":"object","properties":{"checkContent":{"type":"boolean","description":"Enable or disable content safety checking. Increases total generation time. Always on: a false is sent as true."}}},"advancedFeatures":{"type":"object","properties":{"watermark":{"type":"object","properties":{"text":{"type":"string","description":"Watermark text. Documented range: 2 to 32 characters."},"image":{"type":"string","format":"uri","examples":["https://v3b.auray.media/examples/samples/still-life.jpg"],"description":"Watermark image (an http(s) URL; upload a local file first and send its read URL)."},"displayPosition":{"type":"string","enum":["top-left","top-center","top-right","center-left","center-center","center-right","bottom-left","bottom-center","bottom-right","tiled"],"description":"Watermark position."},"opacity":{"type":"number","examples":[1],"description":"Watermark opacity. Documented range: 0.1 to 1."},"fontColor":{"type":"string","description":"Text color in hex format."},"bgColor":{"type":"string","description":"Background color in hex format."}}}}},"idempotency_key":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9._-]{1,64}$","description":"Your own name for this request. Send the same one twice and the second call is answered with the first request rather than charged again. `Idempotency-Key:` as a header is accepted as an alias — that is the spelling a retrying proxy replays, and the one to use when running a model on `auray.run`, where a request that outlives its connection is answered 504 and recovered by replay. Omit it and the platform mints one."}},"required":["positivePrompt","width","height"],"additionalProperties":false,"x-auray-rules":[{"dependentRequired":{"width":["height"],"height":["width"]}},{"if":{"anyOf":[{"required":["strength"]},{"required":["inputs"],"properties":{"inputs":{"required":["maskImage"]}}}]},"then":{"required":["inputs"],"properties":{"inputs":{"required":["seedImage"]}}}},{"properties":{"acceleratorOptions":{"allOf":[{"not":{"required":["cacheStartStep","cacheStartStepPercentage"]}},{"not":{"required":["cacheEndStep","cacheEndStepPercentage"]}},{"not":{"required":["teaCache","dbCache"],"properties":{"teaCache":{"const":true},"dbCache":{"const":true}}}}]}}},{"properties":{"outpaint":{"anyOf":[{"required":["top"]},{"required":["bottom"]},{"required":["left"]},{"required":["right"]}]}}},{"properties":{"lora":{"minItems":1,"items":{"required":["model"]}}}},{"properties":{"controlNet":{"minItems":1,"items":{"required":["model","guideImage"],"not":{"required":["startStep","startStepPercentage"]},"allOf":[{"not":{"required":["endStep","endStepPercentage"]}}]}}}},{"properties":{"advancedFeatures":{"properties":{"watermark":{"oneOf":[{"required":["text"]},{"required":["image"]}]}}}}}],"description":"The model's own fields, in the shape the model reads them, plus `idempotency_key`. Rules across fields, as the model's documentation states them, judged by this API before any charge (warned with a Deprecation header until enforcement starts): (1) Send `height` whenever `width` is sent. Send `width` whenever `height` is sent. (2) When `strength` is sent or `inputs.maskImage` is sent, `inputs.seedImage` is required. (3) Do not send `acceleratorOptions.cacheStartStep` and `acceleratorOptions.cacheStartStepPercentage` together. Do not send `acceleratorOptions.cacheEndStep` and `acceleratorOptions.cacheEndStepPercentage` together. Do not send a request where `acceleratorOptions.teaCache` is true and `acceleratorOptions.dbCache` is true. (4) When `outpaint` is sent: send at least one of `outpaint.top`, `outpaint.bottom`, `outpaint.left` or `outpaint.right`. (5) `lora` must hold at least 1 item. In every item of `lora`: `lora[].model` is required. (6) `controlNet` must hold at least 1 item. In every item of `controlNet`: `controlNet[].model` and `controlNet[].guideImage` are required. In every item of `controlNet`: do not send `controlNet[].endStep` and `controlNet[].endStepPercentage` together. In every item of `controlNet`: do not send `controlNet[].startStep` and `controlNet[].startStepPercentage` together. (7) When `advancedFeatures.watermark` is sent: send exactly one of `advancedFeatures.watermark.text` or `advancedFeatures.watermark.image`."},"QueueStatus":{"oneOf":[{"type":"object","title":"IN_QUEUE","properties":{"status":{"type":"string","const":"IN_QUEUE"},"request_id":{"type":"string","description":"This request's job reference — `<product>_<your idempotency key>`. It is the id every other address on this platform takes, and it is what the three URLs below are built from. The id of the HTTP call itself is in `X-Request-Id` (and `x-fal-request-id` beside it)."},"job_id":{"type":"string","description":"The same job reference under the one name every host uses for it — `id` on `/v1`. `request_id` is the queue protocol's name for it on this host, and means the HTTP call on every other body this API sends."},"logs":{"type":"array","items":{"type":"object","properties":{"message":{"type":"string"},"timestamp":{"type":"string"}},"required":["message","timestamp"]},"description":"Empty unless `?logs=1` asked for them, and empty is a statement."},"metrics":{"type":"object","properties":{"inference_time":{"type":"number","description":"Seconds spent computing, when the runner reported it."}},"description":"`{}` when nothing was reported, which is what the queue protocol sends and what its clients test for."},"give_up_after_seconds":{"type":"integer","description":"Present while the request is open: the longest it may take from its submit — the longest it may wait to start plus the longest it may run before it is stopped and refunded, the figure the submit answered. Waiting longer is waiting for nothing; the official clients wait this long by default."},"queue_position":{"type":"integer","description":"How many requests are ahead of this one. `0` on a read today: the read path looks a job up by credit key and never selects the row id a position needs."}},"required":["status","request_id","job_id","logs","metrics","queue_position"]},{"type":"object","title":"IN_PROGRESS","properties":{"status":{"type":"string","const":"IN_PROGRESS"},"request_id":{"type":"string","description":"This request's job reference — `<product>_<your idempotency key>`. It is the id every other address on this platform takes, and it is what the three URLs below are built from. The id of the HTTP call itself is in `X-Request-Id` (and `x-fal-request-id` beside it)."},"job_id":{"type":"string","description":"The same job reference under the one name every host uses for it — `id` on `/v1`. `request_id` is the queue protocol's name for it on this host, and means the HTTP call on every other body this API sends."},"logs":{"type":"array","items":{"type":"object","properties":{"message":{"type":"string"},"timestamp":{"type":"string"}},"required":["message","timestamp"]},"description":"Empty unless `?logs=1` asked for them, and empty is a statement."},"metrics":{"type":"object","properties":{"inference_time":{"type":"number","description":"Seconds spent computing, when the runner reported it."}},"description":"`{}` when nothing was reported, which is what the queue protocol sends and what its clients test for."},"give_up_after_seconds":{"type":"integer","description":"Present while the request is open: the longest it may take from its submit — the longest it may wait to start plus the longest it may run before it is stopped and refunded, the figure the submit answered. Waiting longer is waiting for nothing; the official clients wait this long by default."}},"required":["status","request_id","job_id","logs","metrics"]},{"type":"object","title":"COMPLETED","properties":{"status":{"type":"string","const":"COMPLETED"},"request_id":{"type":"string","description":"This request's job reference — `<product>_<your idempotency key>`. It is the id every other address on this platform takes, and it is what the three URLs below are built from. The id of the HTTP call itself is in `X-Request-Id` (and `x-fal-request-id` beside it)."},"job_id":{"type":"string","description":"The same job reference under the one name every host uses for it — `id` on `/v1`. `request_id` is the queue protocol's name for it on this host, and means the HTTP call on every other body this API sends."},"logs":{"type":"array","items":{"type":"object","properties":{"message":{"type":"string"},"timestamp":{"type":"string"}},"required":["message","timestamp"]},"description":"Empty unless `?logs=1` asked for them, and empty is a statement."},"metrics":{"type":"object","properties":{"inference_time":{"type":"number","description":"Seconds spent computing, when the runner reported it."}},"description":"`{}` when nothing was reported, which is what the queue protocol sends and what its clients test for."},"error":{"type":["string","null"],"description":"The failure code, or `null` when the request produced its output."},"error_type":{"type":["string","null"],"enum":["AuthenticationError","PermissionError","PaymentError","ValidationError","ContentPolicyError","PayloadTooLargeError","NotFoundError","GoneError","ConflictError","CancellationError","PreconditionError","RegionError","RateLimitError","CapacityError","ConfigurationError","TimeoutError","UpstreamError","ExecutionError","InternalError","NotImplementedError",null],"description":"The class of the failure, or `null`. One of twenty; the code is in `error`."}},"required":["status","request_id","job_id","logs","metrics","error","error_type"]}],"discriminator":{"propertyName":"status"}},"Error":{"type":"object","properties":{"error":{"type":"string","description":"The code. Every one is explained at https://auray.ai/docs/api/errors."},"error_type":{"type":"string","enum":["AuthenticationError","PermissionError","PaymentError","ValidationError","ContentPolicyError","PayloadTooLargeError","NotFoundError","GoneError","ConflictError","CancellationError","PreconditionError","RegionError","RateLimitError","CapacityError","ConfigurationError","TimeoutError","UpstreamError","ExecutionError","InternalError","NotImplementedError"],"description":"The class of the code, also sent as the `X-Auray-Error-Type` header."},"message":{"type":"string","description":"What went wrong and what to do about it."},"detail":{"oneOf":[{"type":"string","description":"The same sentence as `message`. The queue protocol's key; its clients print it."},{"type":"array","description":"A refusal about the input, answered 422: one entry per problem, `loc` naming where it was spelt (`[\"query\", \"max_queue_length\"]`, `[\"header\", \"x-fal-request-timeout\"]`, or `[\"body\"]` when the parser reports no field).","items":{"type":"object","properties":{"loc":{"type":"array","items":{"type":"string"}},"msg":{"type":"string"},"type":{"type":"string","description":"The code, which is this platform's own taxonomy."}},"required":["loc","msg","type"]}}]},"docs":{"type":"string","description":"A link to this code's explanation."},"request_id":{"type":"string","description":"The HTTP call's id. Quote it."}},"required":["error","error_type","message","detail"]}}},"security":[{"apiKey":[]}],"request_id":"9daa9e01-f214-4ed2-a189-0a7f855ea18a"}