{"openapi":"3.1.0","info":{"title":"Instasize API","version":"1.0.0-beta","description":"Image tools from Instasize as HTTP endpoints. Utility: resize to social presets, remove background. Generative (GPU): AI expand (outpainting), AI upscale, AI object removal.\n\n## Authentication\nCreate a key in your Instasize account (Account → API keys) and send it on every call as `x-api-key: <key>` or `Authorization: Bearer <key>`.\n\n| Key | Prefix | Cost | Limits | Output |\n|---|---|---|---|---|\n| Sandbox | `isk_test_` | free, no card | 1,000 successful calls per calendar month per account (all sandbox keys together), 20 requests per minute | watermarked \"instasize sandbox\" |\n| Live | `isk_live_` | credits from the key owner's account | 120 requests per minute | clean |\n\nLive credits come in two tiers:\n\n| Tier | Operations | Price |\n|---|---|---|\n| Utility | `resize` (per output image — a `presets` call with five presets costs five), `remove-background` | 1 credit |\n| Generative | `expand`, `upscale`, `remove-object` | 5 credits |\n\nCredits are spent before the work starts and refunded automatically when a provider fails (`502 upstream_failed`). Each operation carries an `x-credits` extension with its price.\n\n## Errors\nEvery refusal is `{ \"error\": { \"code\", \"message\", \"request_id\" } }`. Branch on `code`, never on the message. `request_id` (also the `X-Request-Id` header) identifies the call in our logs — quote it in support requests.\n\n## Rate limits\nEvery response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset` (seconds until the window resets). Exceeding the per-minute limit returns `429 rate_limited` with `Retry-After`. A sandbox key past its monthly allowance returns `429 usage_exceeded`.","contact":{"name":"Instasize","url":"https://instasize.com/developers"}},"servers":[{"url":"https://instasize.com","description":"Production"}],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"tags":[{"name":"Images","description":"Utility operations that take an image and return an image. 1 credit per output on live keys."},{"name":"Generative","description":"GPU-backed AI operations (expand, upscale, remove-object). 5 credits per call on live keys; slower (up to ~60s)."},{"name":"Reference","description":"Public, unauthenticated reference data."}],"paths":{"/api/v1/remove-background":{"post":{"tags":["Images"],"operationId":"removeBackground","summary":"Remove the background from an image","description":"Returns a PNG with a transparent background. Append `?response=json` to receive a JSON body with a data URL instead of binary. Costs 1 credit on live keys; sandbox output is watermarked.","x-credits":{"live":1,"sandbox":0,"unit":"call"},"parameters":[{"name":"response","in":"query","required":false,"schema":{"type":"string","enum":["json"]},"description":"Set to `json` for a JSON envelope with a data URL."}],"requestBody":{"required":true,"description":"The source image, one of three ways:\n- `multipart/form-data` with the file in field `image`; other parameters as plain fields.\n- `application/json` with `image` as a data URL or raw base64.\n- `application/json` with `image_url` (https, fetched with a 15s timeout).\nPNG, JPEG, WebP, GIF (first frame), TIFF and AVIF inputs are accepted. Request bodies (multipart or base64) take up to 4MB; image_url fetches up to 20MB.","content":{"multipart/form-data":{"schema":{"type":"object","required":["image"],"properties":{"image":{"type":"string","format":"binary"}}}},"application/json":{"schema":{"allOf":[{"type":"object","description":"Exactly one of `image` or `image_url`.","properties":{"image":{"type":"string","description":"Data URL (`data:image/png;base64,...`) or raw base64."},"image_url":{"type":"string","format":"uri","description":"Absolute https URL of the image."}}},{"type":"object","required":[],"properties":{}}]}}}},"responses":{"200":{"description":"The cut-out as PNG (default) or JSON.","headers":{"X-Request-Id":{"description":"Unique id for this call; quote it in support requests.","schema":{"type":"string","example":"req_5f0f1c9d2a6b4d3e8c7f6a5b4c3d2e1f"}},"X-RateLimit-Limit":{"description":"Requests allowed per minute for this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current minute.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"integer"}},"X-Credits-Charged":{"description":"Credits charged for this call (0 for sandbox keys).","schema":{"type":"integer"}},"X-Sandbox":{"description":"`true` when the output is watermarked sandbox output.","schema":{"type":"string","enum":["true","false"]}},"X-Image-Width":{"schema":{"type":"integer"}},"X-Image-Height":{"schema":{"type":"integer"}}},"content":{"image/png":{"schema":{"type":"string","format":"binary"}},"application/json":{"schema":{"$ref":"#/components/schemas/ImageResult"}}}},"400":{"description":"`invalid_request` — a parameter is missing or malformed. The message says which.","headers":{"X-Request-Id":{"description":"Unique id for this call; quote it in support requests.","schema":{"type":"string","example":"req_5f0f1c9d2a6b4d3e8c7f6a5b4c3d2e1f"}},"X-RateLimit-Limit":{"description":"Requests allowed per minute for this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current minute.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"`unauthorized` (no key), `invalid_key`, `key_revoked` or `key_expired`.","headers":{"X-Request-Id":{"description":"Unique id for this call; quote it in support requests.","schema":{"type":"string","example":"req_5f0f1c9d2a6b4d3e8c7f6a5b4c3d2e1f"}},"X-RateLimit-Limit":{"description":"Requests allowed per minute for this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current minute.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"`payment_required` — the live key's account has no plan or credits for this call. Sandbox keys never see this.","headers":{"X-Request-Id":{"description":"Unique id for this call; quote it in support requests.","schema":{"type":"string","example":"req_5f0f1c9d2a6b4d3e8c7f6a5b4c3d2e1f"}},"X-RateLimit-Limit":{"description":"Requests allowed per minute for this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current minute.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"`payload_too_large` — the image exceeds 4MB in the request body (use `image_url` for files up to 20MB).","headers":{"X-Request-Id":{"description":"Unique id for this call; quote it in support requests.","schema":{"type":"string","example":"req_5f0f1c9d2a6b4d3e8c7f6a5b4c3d2e1f"}},"X-RateLimit-Limit":{"description":"Requests allowed per minute for this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current minute.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"415":{"description":"`unsupported_media_type` — the body is not multipart/JSON, or the file is not a decodable image.","headers":{"X-Request-Id":{"description":"Unique id for this call; quote it in support requests.","schema":{"type":"string","example":"req_5f0f1c9d2a6b4d3e8c7f6a5b4c3d2e1f"}},"X-RateLimit-Limit":{"description":"Requests allowed per minute for this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current minute.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"`rate_limited` (per-minute burst; see `Retry-After`), `usage_exceeded` (sandbox monthly allowance) or `payment_required` (daily credit pool exhausted).","headers":{"X-Request-Id":{"description":"Unique id for this call; quote it in support requests.","schema":{"type":"string","example":"req_5f0f1c9d2a6b4d3e8c7f6a5b4c3d2e1f"}},"X-RateLimit-Limit":{"description":"Requests allowed per minute for this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current minute.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"`internal` — our fault. Retry; include the request id if it persists.","headers":{"X-Request-Id":{"description":"Unique id for this call; quote it in support requests.","schema":{"type":"string","example":"req_5f0f1c9d2a6b4d3e8c7f6a5b4c3d2e1f"}},"X-RateLimit-Limit":{"description":"Requests allowed per minute for this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current minute.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"502":{"description":"`upstream_failed` — the processing provider failed. Credits are refunded.","headers":{"X-Request-Id":{"description":"Unique id for this call; quote it in support requests.","schema":{"type":"string","example":"req_5f0f1c9d2a6b4d3e8c7f6a5b4c3d2e1f"}},"X-RateLimit-Limit":{"description":"Requests allowed per minute for this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current minute.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/resize":{"post":{"tags":["Images"],"operationId":"resizeImage","summary":"Resize an image to a size or to social presets","description":"Give `width`/`height`, one `preset`, or a `presets` list. Single sizes answer with the image (or JSON with `?response=json`); `presets` answers with JSON containing every output. Sides up to 8192px and 40MP per output. Costs 1 credit per output image on live keys.","x-credits":{"live":1,"sandbox":0,"unit":"output image"},"parameters":[{"name":"response","in":"query","required":false,"schema":{"type":"string","enum":["json"]},"description":"Set to `json` for a JSON envelope on single-output calls."}],"requestBody":{"required":true,"description":"The source image, one of three ways:\n- `multipart/form-data` with the file in field `image`; other parameters as plain fields.\n- `application/json` with `image` as a data URL or raw base64.\n- `application/json` with `image_url` (https, fetched with a 15s timeout).\nPNG, JPEG, WebP, GIF (first frame), TIFF and AVIF inputs are accepted. Request bodies (multipart or base64) take up to 4MB; image_url fetches up to 20MB.","content":{"multipart/form-data":{"schema":{"type":"object","required":["image"],"properties":{"image":{"type":"string","format":"binary"},"width":{"type":"integer","minimum":1,"maximum":8192,"description":"Output width in pixels. With `height` omitted the aspect ratio is kept."},"height":{"type":"integer","minimum":1,"maximum":8192,"description":"Output height in pixels."},"preset":{"type":"string","description":"A preset id from GET /v1/presets, e.g. `instagram/story`. Answers with the image.","example":"instagram/story"},"presets":{"type":"array","items":{"type":"string"},"maxItems":20,"description":"Up to 20 preset ids (a comma-separated string in multipart). Answers with JSON containing every output. Costs 1 credit per output on live keys.","example":["instagram/story","instagram/square"]},"fit":{"type":"string","enum":["cover","contain","fill"],"default":"cover","description":"`cover` crops to fill, `contain` pads with `background`, `fill` stretches."},"background":{"type":"string","default":"#ffffff","description":"Hex color (#rgb, #rrggbb, #rrggbbaa) or `transparent` (png/webp only). Used by `contain`."},"format":{"type":"string","enum":["png","jpeg","webp"],"description":"Default: png when the source has transparency, otherwise jpeg."},"quality":{"type":"integer","minimum":1,"maximum":100,"default":85,"description":"jpeg/webp encoder quality."}}}},"application/json":{"schema":{"allOf":[{"type":"object","description":"Exactly one of `image` or `image_url`.","properties":{"image":{"type":"string","description":"Data URL (`data:image/png;base64,...`) or raw base64."},"image_url":{"type":"string","format":"uri","description":"Absolute https URL of the image."}}},{"type":"object","required":[],"properties":{"width":{"type":"integer","minimum":1,"maximum":8192,"description":"Output width in pixels. With `height` omitted the aspect ratio is kept."},"height":{"type":"integer","minimum":1,"maximum":8192,"description":"Output height in pixels."},"preset":{"type":"string","description":"A preset id from GET /v1/presets, e.g. `instagram/story`. Answers with the image.","example":"instagram/story"},"presets":{"type":"array","items":{"type":"string"},"maxItems":20,"description":"Up to 20 preset ids (a comma-separated string in multipart). Answers with JSON containing every output. Costs 1 credit per output on live keys.","example":["instagram/story","instagram/square"]},"fit":{"type":"string","enum":["cover","contain","fill"],"default":"cover","description":"`cover` crops to fill, `contain` pads with `background`, `fill` stretches."},"background":{"type":"string","default":"#ffffff","description":"Hex color (#rgb, #rrggbb, #rrggbbaa) or `transparent` (png/webp only). Used by `contain`."},"format":{"type":"string","enum":["png","jpeg","webp"],"description":"Default: png when the source has transparency, otherwise jpeg."},"quality":{"type":"integer","minimum":1,"maximum":100,"default":85,"description":"jpeg/webp encoder quality."}}}]}}}},"responses":{"200":{"description":"The resized image, or JSON for `presets` / `?response=json`.","headers":{"X-Request-Id":{"description":"Unique id for this call; quote it in support requests.","schema":{"type":"string","example":"req_5f0f1c9d2a6b4d3e8c7f6a5b4c3d2e1f"}},"X-RateLimit-Limit":{"description":"Requests allowed per minute for this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current minute.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"integer"}},"X-Credits-Charged":{"description":"Credits charged for this call (0 for sandbox keys).","schema":{"type":"integer"}},"X-Sandbox":{"description":"`true` when the output is watermarked sandbox output.","schema":{"type":"string","enum":["true","false"]}},"X-Image-Width":{"schema":{"type":"integer"}},"X-Image-Height":{"schema":{"type":"integer"}}},"content":{"image/png":{"schema":{"type":"string","format":"binary"}},"image/jpeg":{"schema":{"type":"string","format":"binary"}},"image/webp":{"schema":{"type":"string","format":"binary"}},"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ImageResult"},{"$ref":"#/components/schemas/ResizeOutputs"}]}}}},"400":{"description":"`invalid_request` — a parameter is missing or malformed. The message says which.","headers":{"X-Request-Id":{"description":"Unique id for this call; quote it in support requests.","schema":{"type":"string","example":"req_5f0f1c9d2a6b4d3e8c7f6a5b4c3d2e1f"}},"X-RateLimit-Limit":{"description":"Requests allowed per minute for this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current minute.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"`unauthorized` (no key), `invalid_key`, `key_revoked` or `key_expired`.","headers":{"X-Request-Id":{"description":"Unique id for this call; quote it in support requests.","schema":{"type":"string","example":"req_5f0f1c9d2a6b4d3e8c7f6a5b4c3d2e1f"}},"X-RateLimit-Limit":{"description":"Requests allowed per minute for this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current minute.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"`payment_required` — the live key's account has no plan or credits for this call. Sandbox keys never see this.","headers":{"X-Request-Id":{"description":"Unique id for this call; quote it in support requests.","schema":{"type":"string","example":"req_5f0f1c9d2a6b4d3e8c7f6a5b4c3d2e1f"}},"X-RateLimit-Limit":{"description":"Requests allowed per minute for this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current minute.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"`payload_too_large` — the image exceeds 4MB in the request body (use `image_url` for files up to 20MB).","headers":{"X-Request-Id":{"description":"Unique id for this call; quote it in support requests.","schema":{"type":"string","example":"req_5f0f1c9d2a6b4d3e8c7f6a5b4c3d2e1f"}},"X-RateLimit-Limit":{"description":"Requests allowed per minute for this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current minute.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"415":{"description":"`unsupported_media_type` — the body is not multipart/JSON, or the file is not a decodable image.","headers":{"X-Request-Id":{"description":"Unique id for this call; quote it in support requests.","schema":{"type":"string","example":"req_5f0f1c9d2a6b4d3e8c7f6a5b4c3d2e1f"}},"X-RateLimit-Limit":{"description":"Requests allowed per minute for this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current minute.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"`rate_limited` (per-minute burst; see `Retry-After`), `usage_exceeded` (sandbox monthly allowance) or `payment_required` (daily credit pool exhausted).","headers":{"X-Request-Id":{"description":"Unique id for this call; quote it in support requests.","schema":{"type":"string","example":"req_5f0f1c9d2a6b4d3e8c7f6a5b4c3d2e1f"}},"X-RateLimit-Limit":{"description":"Requests allowed per minute for this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current minute.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"`internal` — our fault. Retry; include the request id if it persists.","headers":{"X-Request-Id":{"description":"Unique id for this call; quote it in support requests.","schema":{"type":"string","example":"req_5f0f1c9d2a6b4d3e8c7f6a5b4c3d2e1f"}},"X-RateLimit-Limit":{"description":"Requests allowed per minute for this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current minute.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"502":{"description":"`upstream_failed` — the processing provider failed. Credits are refunded.","headers":{"X-Request-Id":{"description":"Unique id for this call; quote it in support requests.","schema":{"type":"string","example":"req_5f0f1c9d2a6b4d3e8c7f6a5b4c3d2e1f"}},"X-RateLimit-Limit":{"description":"Requests allowed per minute for this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current minute.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/expand":{"post":{"tags":["Generative"],"operationId":"expandImage","summary":"AI expand (outpainting) — grow the canvas and fill the new area","description":"Give the pixels to add per side, an `aspect` ratio, or a `preset` id; the worker paints the new area to continue the scene. Sides round up to multiples of 64px and stop at 2000px each. Because the rounding is per side, an `aspect` result can be a few dozen pixels off the exact ratio — read `added` (JSON) or `X-Expand-Added` (binary) for what was produced. The output is the worker's ~1024px-class render, so large sources come back smaller than they went in; full-resolution re-blending is a documented follow-up. Costs 5 credits on live keys, spent before the worker runs and refunded if it fails; sandbox output is watermarked.","x-credits":{"live":5,"sandbox":0,"unit":"call"},"parameters":[{"name":"response","in":"query","required":false,"schema":{"type":"string","enum":["json"]},"description":"Set to `json` for a JSON envelope with a data URL."}],"requestBody":{"required":true,"description":"The source image, one of three ways:\n- `multipart/form-data` with the file in field `image`; other parameters as plain fields.\n- `application/json` with `image` as a data URL or raw base64.\n- `application/json` with `image_url` (https, fetched with a 15s timeout).\nPNG, JPEG, WebP, GIF (first frame), TIFF and AVIF inputs are accepted. Request bodies (multipart or base64) take up to 4MB; image_url fetches up to 20MB.\n\nThen exactly ONE of: `left`/`right`/`top`/`bottom` (pixels to add on each side, any subset), an `aspect` ratio, or a `preset` id. Every side is rounded up to a multiple of 64 and capped at 2000px — a request that needs more is refused with `400 invalid_request` and a message saying which side and by how much. A request that adds nothing (all sides 0, or an aspect the image already has) is also `400`.","content":{"multipart/form-data":{"schema":{"type":"object","required":["image"],"properties":{"image":{"type":"string","format":"binary"},"left":{"type":"integer","minimum":0,"maximum":2000,"description":"Pixels to add on the left. Rounded UP to a multiple of 64; at most 2000 after rounding (so 1984 is the largest accepted value)."},"right":{"type":"integer","minimum":0,"maximum":2000,"description":"Pixels to add on the right. Rounded UP to a multiple of 64; at most 2000 after rounding (so 1984 is the largest accepted value)."},"top":{"type":"integer","minimum":0,"maximum":2000,"description":"Pixels to add on the top. Rounded UP to a multiple of 64; at most 2000 after rounding (so 1984 is the largest accepted value)."},"bottom":{"type":"integer","minimum":0,"maximum":2000,"description":"Pixels to add on the bottom. Rounded UP to a multiple of 64; at most 2000 after rounding (so 1984 is the largest accepted value)."},"aspect":{"type":"string","pattern":"^\\d+:\\d+$","description":"Target aspect ratio as `W:H` (`1:1`, `4:5`, `9:16`, `16:9`, `3:4`, `4:3`, `2:3`, `3:2`, or any positive integers). The canvas grows along ONE axis, centred, so the source is never cropped or shrunk; the added pixels are then rounded up per side.","example":"1:1"},"preset":{"type":"string","description":"A preset id from GET /v1/presets, e.g. `instagram/story`; its width:height is used exactly like `aspect`.","example":"instagram/story"},"prompt":{"type":"string","description":"What should appear in the new area. Optional; the worker defaults to a neutral continuation."},"negative_prompt":{"type":"string","description":"What to avoid in the new area."},"seed":{"type":"integer","minimum":0,"description":"Fix the seed for reproducible output."}}}},"application/json":{"schema":{"allOf":[{"type":"object","description":"Exactly one of `image` or `image_url`.","properties":{"image":{"type":"string","description":"Data URL (`data:image/png;base64,...`) or raw base64."},"image_url":{"type":"string","format":"uri","description":"Absolute https URL of the image."}}},{"type":"object","properties":{"left":{"type":"integer","minimum":0,"maximum":2000,"description":"Pixels to add on the left. Rounded UP to a multiple of 64; at most 2000 after rounding (so 1984 is the largest accepted value)."},"right":{"type":"integer","minimum":0,"maximum":2000,"description":"Pixels to add on the right. Rounded UP to a multiple of 64; at most 2000 after rounding (so 1984 is the largest accepted value)."},"top":{"type":"integer","minimum":0,"maximum":2000,"description":"Pixels to add on the top. Rounded UP to a multiple of 64; at most 2000 after rounding (so 1984 is the largest accepted value)."},"bottom":{"type":"integer","minimum":0,"maximum":2000,"description":"Pixels to add on the bottom. Rounded UP to a multiple of 64; at most 2000 after rounding (so 1984 is the largest accepted value)."},"aspect":{"type":"string","pattern":"^\\d+:\\d+$","description":"Target aspect ratio as `W:H` (`1:1`, `4:5`, `9:16`, `16:9`, `3:4`, `4:3`, `2:3`, `3:2`, or any positive integers). The canvas grows along ONE axis, centred, so the source is never cropped or shrunk; the added pixels are then rounded up per side.","example":"1:1"},"preset":{"type":"string","description":"A preset id from GET /v1/presets, e.g. `instagram/story`; its width:height is used exactly like `aspect`.","example":"instagram/story"},"prompt":{"type":"string","description":"What should appear in the new area. Optional; the worker defaults to a neutral continuation."},"negative_prompt":{"type":"string","description":"What to avoid in the new area."},"seed":{"type":"integer","minimum":0,"description":"Fix the seed for reproducible output."}}}]},"examples":{"aspect":{"summary":"Expand to square","value":{"image_url":"https://example.com/photo.jpg","aspect":"1:1","prompt":"sandy beach, soft light"}},"sides":{"summary":"Add 256px left and right","value":{"image_url":"https://example.com/photo.jpg","left":256,"right":256}},"preset":{"summary":"Expand to an Instagram story","value":{"image_url":"https://example.com/photo.jpg","preset":"instagram/story"}}}}}},"responses":{"200":{"description":"The expanded image (JPEG or PNG, whichever the worker produced) or JSON.","headers":{"X-Request-Id":{"description":"Unique id for this call; quote it in support requests.","schema":{"type":"string","example":"req_5f0f1c9d2a6b4d3e8c7f6a5b4c3d2e1f"}},"X-RateLimit-Limit":{"description":"Requests allowed per minute for this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current minute.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"integer"}},"X-Credits-Charged":{"description":"Credits charged for this call (0 for sandbox keys).","schema":{"type":"integer"}},"X-Sandbox":{"description":"`true` when the output is watermarked sandbox output.","schema":{"type":"string","enum":["true","false"]}},"X-Image-Width":{"schema":{"type":"integer"}},"X-Image-Height":{"schema":{"type":"integer"}},"X-Expand-Added":{"description":"Pixels actually added as `left,right,top,bottom` (after rounding).","schema":{"type":"string","example":"0,0,192,192"}}},"content":{"image/jpeg":{"schema":{"type":"string","format":"binary"}},"image/png":{"schema":{"type":"string","format":"binary"}},"application/json":{"schema":{"$ref":"#/components/schemas/ExpandResult"}}}},"400":{"description":"`invalid_request` — no sides/aspect/preset (or more than one), a side that is not an integer ≥ 0, a malformed `aspect`, an unknown `preset`, nothing to add, or a side over 2000px after rounding (the message names the side and the limit).","headers":{"X-Request-Id":{"description":"Unique id for this call; quote it in support requests.","schema":{"type":"string","example":"req_5f0f1c9d2a6b4d3e8c7f6a5b4c3d2e1f"}},"X-RateLimit-Limit":{"description":"Requests allowed per minute for this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current minute.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"`unauthorized` (no key), `invalid_key`, `key_revoked` or `key_expired`.","headers":{"X-Request-Id":{"description":"Unique id for this call; quote it in support requests.","schema":{"type":"string","example":"req_5f0f1c9d2a6b4d3e8c7f6a5b4c3d2e1f"}},"X-RateLimit-Limit":{"description":"Requests allowed per minute for this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current minute.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"`payment_required` — the live key's account has no plan or credits for this call. Sandbox keys never see this.","headers":{"X-Request-Id":{"description":"Unique id for this call; quote it in support requests.","schema":{"type":"string","example":"req_5f0f1c9d2a6b4d3e8c7f6a5b4c3d2e1f"}},"X-RateLimit-Limit":{"description":"Requests allowed per minute for this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current minute.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"`payload_too_large` — the image exceeds 4MB in the request body (use `image_url` for files up to 20MB).","headers":{"X-Request-Id":{"description":"Unique id for this call; quote it in support requests.","schema":{"type":"string","example":"req_5f0f1c9d2a6b4d3e8c7f6a5b4c3d2e1f"}},"X-RateLimit-Limit":{"description":"Requests allowed per minute for this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current minute.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"415":{"description":"`unsupported_media_type` — the body is not multipart/JSON, or the file is not a decodable image.","headers":{"X-Request-Id":{"description":"Unique id for this call; quote it in support requests.","schema":{"type":"string","example":"req_5f0f1c9d2a6b4d3e8c7f6a5b4c3d2e1f"}},"X-RateLimit-Limit":{"description":"Requests allowed per minute for this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current minute.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"`rate_limited` (per-minute burst; see `Retry-After`), `usage_exceeded` (sandbox monthly allowance) or `payment_required` (daily credit pool exhausted).","headers":{"X-Request-Id":{"description":"Unique id for this call; quote it in support requests.","schema":{"type":"string","example":"req_5f0f1c9d2a6b4d3e8c7f6a5b4c3d2e1f"}},"X-RateLimit-Limit":{"description":"Requests allowed per minute for this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current minute.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"`internal` — our fault. Retry; include the request id if it persists.","headers":{"X-Request-Id":{"description":"Unique id for this call; quote it in support requests.","schema":{"type":"string","example":"req_5f0f1c9d2a6b4d3e8c7f6a5b4c3d2e1f"}},"X-RateLimit-Limit":{"description":"Requests allowed per minute for this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current minute.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"502":{"description":"`upstream_failed` — the processing provider failed. Credits are refunded.","headers":{"X-Request-Id":{"description":"Unique id for this call; quote it in support requests.","schema":{"type":"string","example":"req_5f0f1c9d2a6b4d3e8c7f6a5b4c3d2e1f"}},"X-RateLimit-Limit":{"description":"Requests allowed per minute for this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current minute.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/upscale":{"post":{"tags":["Generative"],"operationId":"upscaleImage","summary":"AI upscale — enlarge and sharpen an image","description":"The image is the only input; the worker picks the factor and answers JPEG. Costs 5 credits on live keys, spent before the worker runs and refunded if it fails; sandbox output is watermarked.","x-credits":{"live":5,"sandbox":0,"unit":"call"},"parameters":[{"name":"response","in":"query","required":false,"schema":{"type":"string","enum":["json"]},"description":"Set to `json` for a JSON envelope with a data URL."}],"requestBody":{"required":true,"description":"The source image, one of three ways:\n- `multipart/form-data` with the file in field `image`; other parameters as plain fields.\n- `application/json` with `image` as a data URL or raw base64.\n- `application/json` with `image_url` (https, fetched with a 15s timeout).\nPNG, JPEG, WebP, GIF (first frame), TIFF and AVIF inputs are accepted. Request bodies (multipart or base64) take up to 4MB; image_url fetches up to 20MB.","content":{"multipart/form-data":{"schema":{"type":"object","required":["image"],"properties":{"image":{"type":"string","format":"binary"}}}},"application/json":{"schema":{"allOf":[{"type":"object","description":"Exactly one of `image` or `image_url`.","properties":{"image":{"type":"string","description":"Data URL (`data:image/png;base64,...`) or raw base64."},"image_url":{"type":"string","format":"uri","description":"Absolute https URL of the image."}}},{"type":"object","required":[],"properties":{}}]}}}},"responses":{"200":{"description":"The upscaled image as JPEG (default) or JSON.","headers":{"X-Request-Id":{"description":"Unique id for this call; quote it in support requests.","schema":{"type":"string","example":"req_5f0f1c9d2a6b4d3e8c7f6a5b4c3d2e1f"}},"X-RateLimit-Limit":{"description":"Requests allowed per minute for this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current minute.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"integer"}},"X-Credits-Charged":{"description":"Credits charged for this call (0 for sandbox keys).","schema":{"type":"integer"}},"X-Sandbox":{"description":"`true` when the output is watermarked sandbox output.","schema":{"type":"string","enum":["true","false"]}},"X-Image-Width":{"schema":{"type":"integer"}},"X-Image-Height":{"schema":{"type":"integer"}}},"content":{"image/jpeg":{"schema":{"type":"string","format":"binary"}},"application/json":{"schema":{"$ref":"#/components/schemas/UpscaleResult"}}}},"400":{"description":"`invalid_request` — a parameter is missing or malformed. The message says which.","headers":{"X-Request-Id":{"description":"Unique id for this call; quote it in support requests.","schema":{"type":"string","example":"req_5f0f1c9d2a6b4d3e8c7f6a5b4c3d2e1f"}},"X-RateLimit-Limit":{"description":"Requests allowed per minute for this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current minute.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"`unauthorized` (no key), `invalid_key`, `key_revoked` or `key_expired`.","headers":{"X-Request-Id":{"description":"Unique id for this call; quote it in support requests.","schema":{"type":"string","example":"req_5f0f1c9d2a6b4d3e8c7f6a5b4c3d2e1f"}},"X-RateLimit-Limit":{"description":"Requests allowed per minute for this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current minute.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"`payment_required` — the live key's account has no plan or credits for this call. Sandbox keys never see this.","headers":{"X-Request-Id":{"description":"Unique id for this call; quote it in support requests.","schema":{"type":"string","example":"req_5f0f1c9d2a6b4d3e8c7f6a5b4c3d2e1f"}},"X-RateLimit-Limit":{"description":"Requests allowed per minute for this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current minute.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"`payload_too_large` — the image exceeds 4MB in the request body (use `image_url` for files up to 20MB).","headers":{"X-Request-Id":{"description":"Unique id for this call; quote it in support requests.","schema":{"type":"string","example":"req_5f0f1c9d2a6b4d3e8c7f6a5b4c3d2e1f"}},"X-RateLimit-Limit":{"description":"Requests allowed per minute for this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current minute.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"415":{"description":"`unsupported_media_type` — the body is not multipart/JSON, or the file is not a decodable image.","headers":{"X-Request-Id":{"description":"Unique id for this call; quote it in support requests.","schema":{"type":"string","example":"req_5f0f1c9d2a6b4d3e8c7f6a5b4c3d2e1f"}},"X-RateLimit-Limit":{"description":"Requests allowed per minute for this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current minute.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"`rate_limited` (per-minute burst; see `Retry-After`), `usage_exceeded` (sandbox monthly allowance) or `payment_required` (daily credit pool exhausted).","headers":{"X-Request-Id":{"description":"Unique id for this call; quote it in support requests.","schema":{"type":"string","example":"req_5f0f1c9d2a6b4d3e8c7f6a5b4c3d2e1f"}},"X-RateLimit-Limit":{"description":"Requests allowed per minute for this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current minute.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"`internal` — our fault. Retry; include the request id if it persists.","headers":{"X-Request-Id":{"description":"Unique id for this call; quote it in support requests.","schema":{"type":"string","example":"req_5f0f1c9d2a6b4d3e8c7f6a5b4c3d2e1f"}},"X-RateLimit-Limit":{"description":"Requests allowed per minute for this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current minute.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"502":{"description":"`upstream_failed` — the processing provider failed. Credits are refunded.","headers":{"X-Request-Id":{"description":"Unique id for this call; quote it in support requests.","schema":{"type":"string","example":"req_5f0f1c9d2a6b4d3e8c7f6a5b4c3d2e1f"}},"X-RateLimit-Limit":{"description":"Requests allowed per minute for this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current minute.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/remove-object":{"post":{"tags":["Generative"],"operationId":"removeObject","summary":"AI object removal — paint out whatever the mask covers","description":"Send the image and a same-size mask (white where the object is). Answers PNG when the result has transparency, otherwise JPEG. Costs 5 credits on live keys, spent before the worker runs and refunded if it fails; sandbox output is watermarked.","x-credits":{"live":5,"sandbox":0,"unit":"call"},"parameters":[{"name":"response","in":"query","required":false,"schema":{"type":"string","enum":["json"]},"description":"Set to `json` for a JSON envelope with a data URL."}],"requestBody":{"required":true,"description":"Two images. The source image, one of three ways:\n- `multipart/form-data` with the file in field `image`; other parameters as plain fields.\n- `application/json` with `image` as a data URL or raw base64.\n- `application/json` with `image_url` (https, fetched with a 15s timeout).\nPNG, JPEG, WebP, GIF (first frame), TIFF and AVIF inputs are accepted. Request bodies (multipart or base64) take up to 4MB; image_url fetches up to 20MB.\n\nThe mask travels the same way as the image: multipart field `mask` (a file), JSON `mask` (data URL or base64), or JSON `mask_url` (https). A mask the SAME pixel size as `image`: white (or opaque) where the object to remove is, black elsewhere. PNG/JPEG/WebP; up to 4MB in the body or 20MB via `mask_url`. A size mismatch is refused with `400 invalid_request`.","content":{"multipart/form-data":{"schema":{"type":"object","required":["image","mask"],"properties":{"image":{"type":"string","format":"binary"},"mask":{"type":"string","format":"binary","description":"A mask the SAME pixel size as `image`: white (or opaque) where the object to remove is, black elsewhere. PNG/JPEG/WebP; up to 4MB in the body or 20MB via `mask_url`. A size mismatch is refused with `400 invalid_request`."}}}},"application/json":{"schema":{"allOf":[{"type":"object","description":"Exactly one of `image` or `image_url`.","properties":{"image":{"type":"string","description":"Data URL (`data:image/png;base64,...`) or raw base64."},"image_url":{"type":"string","format":"uri","description":"Absolute https URL of the image."}}},{"type":"object","description":"Exactly one of `mask` or `mask_url`.","properties":{"mask":{"type":"string","description":"Data URL or raw base64. A mask the SAME pixel size as `image`: white (or opaque) where the object to remove is, black elsewhere. PNG/JPEG/WebP; up to 4MB in the body or 20MB via `mask_url`. A size mismatch is refused with `400 invalid_request`."},"mask_url":{"type":"string","format":"uri","description":"Absolute https URL of the mask."}}}]}}}},"responses":{"200":{"description":"The image with the masked area filled in, as JPEG/PNG or JSON.","headers":{"X-Request-Id":{"description":"Unique id for this call; quote it in support requests.","schema":{"type":"string","example":"req_5f0f1c9d2a6b4d3e8c7f6a5b4c3d2e1f"}},"X-RateLimit-Limit":{"description":"Requests allowed per minute for this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current minute.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"integer"}},"X-Credits-Charged":{"description":"Credits charged for this call (0 for sandbox keys).","schema":{"type":"integer"}},"X-Sandbox":{"description":"`true` when the output is watermarked sandbox output.","schema":{"type":"string","enum":["true","false"]}},"X-Image-Width":{"schema":{"type":"integer"}},"X-Image-Height":{"schema":{"type":"integer"}}},"content":{"image/jpeg":{"schema":{"type":"string","format":"binary"}},"image/png":{"schema":{"type":"string","format":"binary"}},"application/json":{"schema":{"$ref":"#/components/schemas/ImageResult"}}}},"400":{"description":"`invalid_request` — `mask` missing, or its pixel size differs from `image` (the message gives both sizes; resize the mask to match).","headers":{"X-Request-Id":{"description":"Unique id for this call; quote it in support requests.","schema":{"type":"string","example":"req_5f0f1c9d2a6b4d3e8c7f6a5b4c3d2e1f"}},"X-RateLimit-Limit":{"description":"Requests allowed per minute for this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current minute.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"`unauthorized` (no key), `invalid_key`, `key_revoked` or `key_expired`.","headers":{"X-Request-Id":{"description":"Unique id for this call; quote it in support requests.","schema":{"type":"string","example":"req_5f0f1c9d2a6b4d3e8c7f6a5b4c3d2e1f"}},"X-RateLimit-Limit":{"description":"Requests allowed per minute for this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current minute.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"`payment_required` — the live key's account has no plan or credits for this call. Sandbox keys never see this.","headers":{"X-Request-Id":{"description":"Unique id for this call; quote it in support requests.","schema":{"type":"string","example":"req_5f0f1c9d2a6b4d3e8c7f6a5b4c3d2e1f"}},"X-RateLimit-Limit":{"description":"Requests allowed per minute for this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current minute.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"`payload_too_large` — the image or the mask exceeds 4MB in the request body (20MB via URL).","headers":{"X-Request-Id":{"description":"Unique id for this call; quote it in support requests.","schema":{"type":"string","example":"req_5f0f1c9d2a6b4d3e8c7f6a5b4c3d2e1f"}},"X-RateLimit-Limit":{"description":"Requests allowed per minute for this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current minute.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"415":{"description":"`unsupported_media_type` — the body is not multipart/JSON, or the image or mask is not a decodable image.","headers":{"X-Request-Id":{"description":"Unique id for this call; quote it in support requests.","schema":{"type":"string","example":"req_5f0f1c9d2a6b4d3e8c7f6a5b4c3d2e1f"}},"X-RateLimit-Limit":{"description":"Requests allowed per minute for this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current minute.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"`rate_limited` (per-minute burst; see `Retry-After`), `usage_exceeded` (sandbox monthly allowance) or `payment_required` (daily credit pool exhausted).","headers":{"X-Request-Id":{"description":"Unique id for this call; quote it in support requests.","schema":{"type":"string","example":"req_5f0f1c9d2a6b4d3e8c7f6a5b4c3d2e1f"}},"X-RateLimit-Limit":{"description":"Requests allowed per minute for this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current minute.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"`internal` — our fault. Retry; include the request id if it persists.","headers":{"X-Request-Id":{"description":"Unique id for this call; quote it in support requests.","schema":{"type":"string","example":"req_5f0f1c9d2a6b4d3e8c7f6a5b4c3d2e1f"}},"X-RateLimit-Limit":{"description":"Requests allowed per minute for this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current minute.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"502":{"description":"`upstream_failed` — the processing provider failed. Credits are refunded.","headers":{"X-Request-Id":{"description":"Unique id for this call; quote it in support requests.","schema":{"type":"string","example":"req_5f0f1c9d2a6b4d3e8c7f6a5b4c3d2e1f"}},"X-RateLimit-Limit":{"description":"Requests allowed per minute for this key.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current minute.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/presets":{"get":{"tags":["Reference"],"operationId":"listPresets","summary":"List social size presets","description":"Every preset id `POST /v1/resize` accepts, with platform, name and pixel size. Public; cached for an hour.","security":[],"x-credits":{"live":0,"sandbox":0,"unit":"call"},"responses":{"200":{"description":"Presets grouped flat, ids like `instagram/story`.","content":{"application/json":{"schema":{"type":"object","required":["presets"],"properties":{"presets":{"type":"array","items":{"$ref":"#/components/schemas/Preset"}}}}}}}}}},"/api/v1/openapi.json":{"get":{"tags":["Reference"],"operationId":"getOpenApi","summary":"This document","security":[],"x-credits":{"live":0,"sandbox":0,"unit":"call"},"responses":{"200":{"description":"The OpenAPI 3.1 document.","content":{"application/json":{"schema":{"type":"object"}}}}}}}},"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"`isk_live_…` or `isk_test_…` key."},"BearerAuth":{"type":"http","scheme":"bearer","description":"The same key as `Authorization: Bearer <key>`."}},"schemas":{"ErrorEnvelope":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id"],"properties":{"code":{"type":"string","enum":["unauthorized","invalid_key","key_revoked","key_expired","usage_exceeded","rate_limited","payment_required","invalid_request","payload_too_large","unsupported_media_type","upstream_failed","internal"]},"message":{"type":"string","description":"Human-readable; may change. Branch on `code`."},"request_id":{"type":"string"}},"additionalProperties":true}},"example":{"error":{"code":"invalid_request","message":"Unknown preset: instagram/storie. GET /v1/presets lists the ids.","request_id":"req_5f0f1c9d2a6b4d3e8c7f6a5b4c3d2e1f"}}},"ImageResult":{"type":"object","required":["image","width","height","credits_charged","sandbox"],"properties":{"image":{"type":"string","description":"Data URL of the output image."},"width":{"type":"integer"},"height":{"type":"integer"},"format":{"type":"string","enum":["png","jpeg","webp"]},"preset":{"type":["string","null"],"description":"Preset id when one was used."},"credits_charged":{"type":"integer"},"sandbox":{"type":"boolean","description":"true when the output is watermarked sandbox output."}}},"ExpandResult":{"allOf":[{"$ref":"#/components/schemas/ImageResult"},{"type":"object","required":["added"],"properties":{"added":{"type":"object","description":"Pixels added on each side after rounding up to a multiple of 64.","required":["left","right","top","bottom"],"properties":{"left":{"type":"integer"},"right":{"type":"integer"},"top":{"type":"integer"},"bottom":{"type":"integer"}},"example":{"left":0,"right":0,"top":192,"bottom":192}}}}]},"UpscaleResult":{"allOf":[{"$ref":"#/components/schemas/ImageResult"},{"type":"object","required":["source"],"properties":{"source":{"type":"object","description":"Pixel size of the image that was sent, for computing the effective factor.","required":["width","height"],"properties":{"width":{"type":"integer"},"height":{"type":"integer"}}}}}]},"ResizeOutputs":{"type":"object","required":["outputs","credits_charged","sandbox"],"properties":{"outputs":{"type":"array","items":{"type":"object","required":["preset","width","height","format","bytes","image"],"properties":{"preset":{"type":"string"},"width":{"type":"integer"},"height":{"type":"integer"},"format":{"type":"string","enum":["png","jpeg","webp"]},"bytes":{"type":"integer"},"image":{"type":"string","description":"Data URL."}}}},"credits_charged":{"type":"integer"},"sandbox":{"type":"boolean"}}},"Preset":{"type":"object","required":["id","platform","name","width","height","ratio"],"properties":{"id":{"type":"string","example":"instagram/story"},"platform":{"type":"string","example":"Instagram"},"name":{"type":"string","example":"Story"},"width":{"type":"integer","example":1080},"height":{"type":"integer","example":1920},"ratio":{"type":"string","example":"9:16"}}}}}}