craterview-ai Account API

openapi: 3.2.0
info:
  title: CraterView.ai Account 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: Account
  description: What you have told us about your account.
paths:
  /v1/account/product-updates:
    get:
      tags:
      - Account
      summary: Get Product Updates
      description: 'Whether we may email you about product improvements and new guides.


        Nothing is sent until you say yes, and a guest account is never asked: there is no

        address to send to until it is signed in.'
      operationId: get_product_updates_v1_account_product_updates_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductUpdates'
        '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: []
    put:
      tags:
      - Account
      summary: Put Product Updates
      description: 'Say whether we may email you about product improvements and new guides.


        The emails go to the address you signed in with. The last answer holds, and you can

        change it whenever you like; once you have answered, the website and the app stop asking.'
      operationId: put_product_updates_v1_account_product_updates_put
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProductUpdatesAnswer'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductUpdates'
        '403':
          description: a guest account; there is no address to email until it is signed in
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '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:
    ProductUpdates:
      properties:
        opted_in:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Opted In
          description: 'Whether we may email you about product improvements and new guides: your last answer, or null if you have not given one. Nothing is sent until it is true. Receipts and notices about your account are sent either way.'
        ask:
          type: boolean
          title: Ask
          description: 'Whether the CraterView.ai website and app ask you this now: true until you answer, once the account is signed in and has run 5 jobs.'
      type: object
      required:
      - opted_in
      - ask
      title: ProductUpdates
    ProductUpdatesAnswer:
      properties:
        opted_in:
          type: boolean
          title: Opted In
          description: '`true` to receive product improvement and guide update emails, `false` not to. The last answer holds; change it whenever you like.'
      additionalProperties: false
      type: object
      required:
      - opted_in
      title: ProductUpdatesAnswer
    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'
  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.'