Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: CraterView.ai Usage API
description: 'CraterView.ai image enhancement and restoration API. ## How a job works
Three calls — upload to a presigned URL, run a job, and download the result. 1. `POST /v1/uploads` — get a presigned URL and an `input_key`
2. `PUT` your bytes to that URL
3. `POST /v1/jobs` — submit `input_key` plus parameters
Inference is asynchronous, because a job can occupy a GPU for minutes. Add `?wait=30` to
step 3 and a fast job comes back finished in the same response; otherwise poll
`GET /v1/jobs/{id}` or supply a `webhook_url`. ## Collecting the result
A finished job carries two links to the same object under `result.output`, both presigned
and both expiring. `url` serves it inline, for displaying a result in a page. `download_url` carries `Content-Disposition: attachment`, so a browser saves it under a
filename instead. Pick by what you are doing with it; a client cannot convert one into the
other, because the disposition is signed into the URL. ## Output format
By default the result comes back in the format you sent — a JPEG upload returns a JPEG —
except that a HEIC or HEIF photograph prefers JPEG and a TIFF scan comes back as PNG: the
platform reads those formats and does not write them. `output_format` names another. Either is a preference: kept wherever that format holds the
picture, and PNG where it does not — an alpha channel asked for as JPEG, more than 8 bits asked
for as JPEG or WebP, a result wider than the format holds. `result.output.content_type`
says which format came back. ## When a job fails
A failed job carries two fields. `error` is a sentence meant for a person and is reworded
whenever it can be made clearer, so show it rather than match on it. `error_code` is the
stable half, and it is what to branch on. **A job that produces no output is not charged**, whoever''s fault it was, so a failed job
always leaves your balance where it started. What the code tells you is whether retrying is
worth anything. `inference_failed` means the fault was ours and the same request is worth
sending again. Every other code refuses the request as you sent it, so an identical retry
fails identically — change something or tell the person who made it. A job that succeeded
with a result that is *wrong* is not a failure the API can see; report it with the job''s
`id` (see *Reporting a problem*). This list is not closed. New codes appear as new things become worth telling apart, so treat
an unfamiliar one as a failure you have no special handling for rather than as an error in
itself; a client that rejects a code it does not know breaks on the next one added. | `error_code` | What it means |
| --- | --- |
| `inference_failed` | Something on our side failed. Nothing was charged — a job is charged only when it succeeds — and the same request is worth sending again. |
| `unreadable_image` | The file is not an image the service can read: it may be damaged, in a format the service does not take, or not an image at all. Re-save or re-export it as PNG or JPEG; the same request will not succeed as it stands. |
| `undecodable_image` | The file starts as an image but its pixels cannot be read to the end: it is damaged, or was cut short, for instance by an upload that did not finish. Re-save or re-export it; the same request will not succeed as it stands. |
| `unsupported_tiff` | The TIFF stores its pixels in a form the service does not read: floating-point, signed or 32-bit samples; 16-bit CMYK, Lab or white-is-zero greyscale; colour planes stored separately; premultiplied transparency; or a compression other than LZW, ZIP or PackBits at 16 bits. Re-save it as 8- or 16-bit RGB or greyscale; the same request will not succeed as it stands. |
| `format_not_accepted` | The file is in a format the model does not take, whatever type it was uploaded as. The model''s `accepts` lists the formats it takes; convert the file to one of them. The same request will not succeed as it stands. |
| `no_face_found` | The model frames a headshot around a face and found none.'
version: 0.1.0
servers:
- url: https://api.craterview.ai
tags:
- name: Usage
description: What this account has consumed, all time.
paths:
/v1/usage:
get:
tags:
- Usage
summary: Get Usage
description: 'The account''s credit balance, what it has spent per model, and which queue your next
job enters.
Account-wide rather than per key, because that is what the balance belongs to.
A job is charged when it succeeds, so work still queued or running is not in these
figures yet, and a job that fails costs nothing. A balance of zero never refuses a
submission, and `community` says which queue the next one enters.'
operationId: get_usage_v1_usage_get
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/UsageResponse'
'401':
description: missing, malformed or unrecognized API key
headers:
WWW-Authenticate:
schema:
type: string
description: '`Bearer`'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'400':
description: the path, query or a JSON string in the body contains a NUL character or an unpaired surrogate; the body is not JSON encoded as UTF-8, or carries a number JSON cannot represent (NaN, Infinity, or one too large) or nesting too deep to read; or an Idempotency-Key header is longer than 255 characters or not printable ASCII. The request was not read
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'413':
description: the request body is larger than 1 MiB. The request was not read
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
security:
- bearerAuth: []
components:
schemas:
UsageResponse:
properties:
credits_spent:
type: integer
title: Credits Spent
description: 'Credits spent, all time. Not the balance: that is `credits_remaining`.'
credits_granted:
type: integer
title: Credits Granted
description: Credits added to this account, all time — bought, granted, and arrears written off — less any refunded purchase.
credits_remaining:
type: integer
title: Credits Remaining
description: 'Credits left to spend. Zero does not stop a submission: the job is accepted and runs on the community queue, as `community` says. Never below zero: what your balance does not cover is never collected, and is written off when credit next arrives or a subscription renews.'
community:
type: boolean
title: Community
description: Whether your next job goes to the community queue, which runs on shared, free capacity and can wait longer at busy times. True while the account is not paying, and a submission is still accepted. False while it is, by holding credit or by a subscription with work left this period, which puts its work on paid compute that scales with demand. A job already queued stays where it went. The same answer `community` gives on each model in the catalogue.
subscribed_until:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Subscribed Until
description: 'When the current subscription''s paid period ends, ISO-8601 — null when there is no subscription. Informational: `subscribed` is the answer to which queue your work enters, decided here rather than by comparing this against your own clock.'
subscribed:
type: boolean
title: Subscribed
description: Whether a subscription is currently putting this account's work on paid compute. While it is true, work runs there at any balance — and the balance means what it always did, because a subscription grants no credit and jobs are charged as usual. A capped subscription gives it for `subscription_allowance` credits of work a period; past that, work runs on the community queue until the period renews.
default: false
subscription_allowance:
anyOf:
- type: integer
- type: 'null'
title: Subscription Allowance
description: 'How many credits of work a period the subscription puts on paid compute, or null for one with no cap or when there is no subscription. Nothing is granted: jobs are charged as usual, and the window holds until the period''s charges reach this figure.'
subscription_allowance_remaining:
anyOf:
- type: integer
- type: 'null'
title: Subscription Allowance Remaining
description: 'Under a capped subscription, how much of `subscription_allowance` is left this period: how many more credits of work it will put on paid compute. Credit on the account is counted separately, as `credits_remaining`, and is spent first. Null where there is no cap.'
is_guest:
type: boolean
title: Is Guest
description: Whether this account has no sign-in attached to it. An account created in a browser or on a device starts this way and works normally — it submits, it spends credit, it holds keys. What it cannot do is buy or publish, and it cannot be reached from anywhere else, because there is nothing to sign in with. Signing in attaches one and this becomes false, keeping the same account, keys and history.
default: false
jobs:
type: integer
title: Jobs
description: Jobs submitted, all time, whatever their outcome.
output_bytes:
type: integer
title: Output Bytes
description: Total size of the results produced, in bytes — the results only, not the input or the preview kept beside them.
by_model:
items:
$ref: '#/components/schemas/ModelUsage'
type: array
title: By Model
description: The same figures broken down per model, largest spend first.
jobs_in_flight:
type: integer
title: Jobs In Flight
description: Your jobs queued or running right now.
default: 0
max_jobs_in_flight:
type: integer
minimum: 1.0
title: Max Jobs In Flight
description: The most you may have queued or running at once. Submitting past it is refused with a 429. It is higher once the account is signed in, so read it rather than assuming it.
type: object
required:
- credits_spent
- credits_granted
- credits_remaining
- community
- jobs
- output_bytes
- by_model
- max_jobs_in_flight
title: UsageResponse
Error:
type: object
required:
- detail
- code
properties:
detail:
description: What went wrong, for a person. It may change; do not match on it. A validation refusal lists each field.
anyOf:
- type: string
- type: array
items:
type: object
required:
- loc
- msg
- type
properties:
loc:
type: array
items:
anyOf:
- type: string
- type: integer
description: 'Where: `body`, `query` or `header`, then the field, then an index where the field is a list.'
msg:
type: string
description: What is wrong there, for a person.
type:
type: string
description: The kind of failure, for a program.
code:
type: string
description: 'What went wrong, for a program: stable, so branch on this. Handle a code you do not know by its status.
- `missing_api_key`: no `Authorization: Bearer` header
- `invalid_api_key`: the key is not recognized, or was revoked
- `rate_limited`: too many requests a minute on this key; wait for `Retry-After`
- `too_many_uploads`: this account''s upload URLs a minute; wait for `Retry-After`
- `too_many_jobs`: this account''s jobs queued or running; wait for one to finish
- `queue_full`: the queue this job would join is full for now; wait for `Retry-After`
- `too_many_keys`: new keys this hour; wait for `Retry-After`
- `gallery_allowance_spent`: gallery submissions in the last 24 hours
- `sign_in_required`: a guest account cannot do this
- `consent_required`: `consent` was not true
- `model_not_found`: no model by that name
- `model_coming_soon`: the model is listed and not yet in service
- `video_coming_soon`: video is not taken yet
- `type_not_accepted`: the content type is not one taken here
- `upload_too_large`: the declared length is over the upload limit
- `upload_not_found`: nothing was uploaded under `input_key`
- `invalid_params`: `params` did not validate against the model''s schema
- `invalid_request`: the request did not validate; `detail` lists where
- `idempotency_conflict`: the `Idempotency-Key` was used with a different body
- `job_not_found`: no job of yours with that id
- `no_finished_job`: no finished job of yours with that id
- `job_not_settled`: the job is still queued or running
- `no_image`: the model returns no image
- `media_deleted`: the job''s pictures are gone
- `already_submitted`: the job is already awaiting moderation or published
- `submission_not_found`: no submission of yours with that id
- `key_not_found`: no active key of yours with that id
- `current_key`: that is the key you are calling with
- `only_key`: that is the account''s only way in
- `jobs_in_flight`: jobs still queued or running stop the account closing
- `account_not_found`: the key no longer reaches an account
- `unavailable`: briefly unavailable and nothing was done; send the same request again after a pause
- `malformed_request`: the request could not be read
- `body_too_large`: the request body is over the limit
- `internal_error`: a fault of ours; it may or may not have taken effect, so check before sending it again; quote `X-Trace-Id`
- `bad_request`: the request was refused
- `not_found`: nothing is at that address
- `method_not_allowed`: the address does not take that method'
ModelUsage:
properties:
model:
type: string
title: Model
description: The model the jobs were submitted to.
jobs:
type: integer
title: Jobs
description: Jobs submitted to this model, all time, whatever their outcome.
credits_spent:
type: integer
title: Credits Spent
description: Credits spent on this model, all time.
output_bytes:
type: integer
title: Output Bytes
description: Total size of this model's results, in bytes.
type: object
required:
- model
- jobs
- credits_spent
- output_bytes
title: ModelUsage
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: 'Your API key, as `Authorization: Bearer cv_...`. Every `/v1` route needs one except the model catalogue, which answers without a key as it would for an account that has not paid.'