JobResponse

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/craterview-ai/json-schema/craterview-ai-job-response-schema.json",
  "title": "JobResponse",
  "description": "A job as the API states it.\n\nAn absent field means it does not apply to this job — a queued one has no result, a\nfinished one has no estimate — rather than that it is unknown.",
  "x-generated": "2026-10-30",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/craterview-ai-openapi.json#/components/schemas/JobResponse",
  "properties": {
    "id": {
      "type": "string",
      "title": "Id"
    },
    "custom_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Custom Id",
      "description": "Your own identifier for the job, if you sent one."
    },
    "model": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Model",
      "description": "The model this job was sent to."
    },
    "status": {
      "$ref": "#/$defs/JobStatus",
      "description": "`queued`, `running`, `succeeded` or `failed`. A callback is only sent for the last two, since it is sent once a job has settled."
    },
    "flagged": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "title": "Flagged",
      "description": "Whether an automated check thought this job's images may fall outside what the service allows: the part of your image the job worked on (all of it, unless you named a region), and for some jobs the one that came back. `null` means they were not all checked."
    },
    "error": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Error",
      "description": "Why a failed job failed, in words meant for a person."
    },
    "error_code": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Error Code",
      "description": "The same fact as `error`, as a stable identifier to branch on. 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 failed job is never charged, whatever the code; `inference_failed` is the one worth singling out, because it means the fault was ours and the same request is worth retrying."
    },
    "community": {
      "type": "boolean",
      "title": "Community",
      "description": "Whether the job runs on the community queue, which runs on shared, free capacity and can wait longer at busy times. Explains a long wait that is not a fault. Charged like any other job, and nothing past your balance is collected.",
      "default": false
    },
    "credits": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "title": "Credits",
      "description": "What this job was billed. A job is charged when it succeeds — a still at the model's image price, a video by its length — so this reads 0 until then, and stays 0 for a job that fails. What your balance does not cover is never collected: it is written off when credit next arrives or a subscription renews."
    },
    "created_at": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time"
        },
        {
          "type": "null"
        }
      ],
      "title": "Created At",
      "description": "When the job was submitted. ISO-8601, UTC."
    },
    "finished_at": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time"
        },
        {
          "type": "null"
        }
      ],
      "title": "Finished At",
      "description": "When the job settled. ISO-8601, UTC. Not stated while a job is still queued or running."
    },
    "result": {
      "anyOf": [
        {
          "$ref": "#/$defs/JobResult"
        },
        {
          "type": "null"
        }
      ],
      "description": "The model's own answer, with an `output` object carrying links to the file when the job produced one. Not stated until the job succeeds."
    },
    "thumbnail_url": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Thumbnail Url",
      "description": "A temporary link to a small preview of the job's picture — the result, or the image the model worked from when the job produced no file — for showing a list of jobs without fetching each one whole. Absent until the job succeeds, where no preview could be made, and once the job's pictures are deleted."
    },
    "kept": {
      "type": "boolean",
      "title": "Kept",
      "description": "Whether this result was asked to outlive the ordinary retention schedule.",
      "default": false
    },
    "gallery": {
      "anyOf": [
        {
          "$ref": "#/$defs/GalleryState"
        },
        {
          "type": "null"
        }
      ],
      "description": "Where this job stands with the public gallery, when you have offered it: `pending` while it is being reviewed, `approved` once it is shown. Absent when it is not offered, including after you withdraw it."
    },
    "progress": {
      "anyOf": [
        {
          "$ref": "#/$defs/JobProgress"
        },
        {
          "type": "null"
        }
      ],
      "description": "How far the job has got while it runs: its stage, and roughly what fraction is done. Absent while the job is queued and once it has settled, so a callback never carries one."
    },
    "eta_seconds": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "title": "Eta Seconds",
      "description": "Rough seconds until the job finishes — the wait for capacity plus the time running. Not stated once a job has settled, so a callback never carries one."
    }
  },
  "type": "object",
  "required": [
    "id",
    "status"
  ],
  "$defs": {
    "GalleryState": {
      "properties": {
        "status": {
          "type": "string",
          "enum": [
            "pending",
            "approved"
          ],
          "title": "Status",
          "description": "`pending` while the submission is being reviewed, `approved` once it is on the gallery."
        },
        "post_id": {
          "type": "string",
          "title": "Post Id",
          "description": "The submission's id — what `DELETE /v1/gallery/{post_id}` withdraws."
        }
      },
      "type": "object",
      "required": [
        "status",
        "post_id"
      ],
      "title": "GalleryState",
      "description": "A job's live gallery submission, as a read of the job reports it."
    },
    "JobFile": {
      "properties": {
        "url": {
          "type": "string",
          "title": "Url",
          "description": "A temporary link that serves the file inline. Expires; fetch the file rather than keeping the link."
        },
        "content_type": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Content Type",
          "description": "The file's media type."
        },
        "bytes": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "title": "Bytes",
          "description": "The file's size, in bytes."
        }
      },
      "type": "object",
      "required": [
        "url"
      ],
      "title": "JobFile",
      "description": "A file a job produced, other than the principal output."
    },
    "JobOutput": {
      "properties": {
        "url": {
          "type": "string",
          "title": "Url",
          "description": "A temporary link that serves the file inline, for showing a result in a page. Expires; fetch the file rather than keeping the link."
        },
        "download_url": {
          "type": "string",
          "title": "Download Url",
          "description": "The same file, served as a download so a browser saves it under a filename. A separate link because the disposition is signed in; neither can be turned into the other."
        },
        "content_type": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Content Type",
          "description": "The file's media type."
        },
        "bytes": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "title": "Bytes",
          "description": "The file's size, in bytes."
        }
      },
      "type": "object",
      "required": [
        "url",
        "download_url"
      ],
      "title": "JobOutput",
      "description": "Where a finished job's file is, and what it is."
    },
    "JobProgress": {
      "properties": {
        "stage": {
          "type": "string",
          "enum": [
            "starting",
            "processing",
            "saving"
          ],
          "title": "Stage",
          "description": "`starting` while your file is fetched and read, `processing` while the model runs, `saving` while the result is stored."
        },
        "fraction": {
          "anyOf": [
            {
              "type": "number",
              "exclusiveMaximum": 1.0,
              "minimum": 0.0
            },
            {
              "type": "null"
            }
          ],
          "title": "Fraction",
          "description": "Roughly how much of the run is done, from 0 up to but never reaching 1, estimated from how long recent jobs like this one have taken. Null when no estimate holds: none is available yet, or the job has run past it."
        }
      },
      "type": "object",
      "required": [
        "stage"
      ],
      "title": "JobProgress",
      "description": "How far a running job has got."
    },
    "JobResult": {
      "properties": {
        "output": {
          "anyOf": [
            {
              "$ref": "#/$defs/JobOutput"
            },
            {
              "type": "null"
            }
          ],
          "description": "Links to the file the job produced, when it produced one."
        },
        "input": {
          "anyOf": [
            {
              "$ref": "#/$defs/JobFile"
            },
            {
              "type": "null"
            }
          ],
          "description": "The image the model worked from. Where you named a region, this is that region — so what was used is something you can look at rather than something to take on trust. It is not the file you uploaded but a new one written from it: turned the way your file's orientation tag says, carrying none of its metadata except the colour profile, and compressed again where it is written as JPEG or WebP, so those pixels differ slightly from yours. Do not expect a hash of it to match your file's. Yours is removed on its own schedule. It is written in the format `auto` would return for what you sent, whatever `output_format` asked of the result."
        }
      },
      "additionalProperties": true,
      "type": "object",
      "title": "JobResult",
      "description": "A job's whole answer: the model's own fields, and the files it produced.\n\nA model that answers only in fields carries no `output`; one that produces only a file\ncarries `output` and nothing else; one doing both needs nothing new. The model's fields\nare its own, and the model's `result_schema` in the catalog describes them."
    },
    "JobStatus": {
      "type": "string",
      "enum": [
        "queued",
        "running",
        "succeeded",
        "failed"
      ],
      "title": "JobStatus"
    }
  }
}