Create Prints Artwork API

openapi: 3.2.0
info:
  title: Createprints Ai Artwork API
  version: 1.1.0
  contact:
    name: Create Prints support
    url: https://www.createprints.ai/contact
  license:
    name: Proprietary
    url: https://www.createprints.ai/terms
  description: 'Operations tagged Artwork across 2 of this provider''s published API definitions: createprints-ai-openapi.json, createprints-ai-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.createprints.ai
  description: Create Prints API origin
tags:
- name: Artwork
  description: Create, import, inspect, retry, and list account-owned artwork.
paths:
  /api/image-generations:
    post:
      operationId: createArtwork
      summary: Queue an artwork generation
      description: 'Spends one available generation credit and queues an artwork job. For text-only creation, send JSON with `inputType: describe`, a prompt, and an image-model size. Multipart form data additionally supports an uploaded reference image; `printPhoto` and `interiorPhoto` require that image. An interior photo supplies palette, mood, and style context—the output is standalone artwork, not a recreation of the room. Use the selected print variant''s exact `generation.imageModelSize` to guarantee aspect compatibility at checkout.'
      tags:
      - Artwork
      security:
      - agentApiKey: []
      - agentBearer: []
      - userSessionBearer: []
      - oauth2:
        - artwork:create
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateArtworkJson'
            example:
              inputType: describe
              prompt: A calm abstract coastal landscape in muted blue and sand tones
              size: 1536x1024
              keywords:
              - coastal
              - abstract
              - calm
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/CreateArtworkMultipart'
      responses:
        '202':
          description: The artwork job was queued.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueuedArtwork'
              example:
                jobId: 1ae94a6e-f1dd-44c7-8314-a869e8357cc1
                status: queued
                statusUrl: /api/image-generations?id=1ae94a6e-f1dd-44c7-8314-a869e8357cc1
                creditsRemaining: 4
        '400':
          description: Missing or invalid input.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: The credential is missing, invalid, revoked, or expired.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: The credential lacks the required scope or cannot perform this operation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Create Prints could not complete the request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    get:
      operationId: getArtworkStatus
      summary: Get an artwork job
      description: Returns processing state and print eligibility for one account-owned artwork. `purchasable` becomes true only after processing completes and an image is uploaded. For a private import, image paths are returned only to the signed-in owner using a user-session token and are null for account API keys and MCP access tokens.
      tags:
      - Artwork
      security:
      - agentApiKey: []
      - agentBearer: []
      - userSessionBearer: []
      - oauth2:
        - artwork:read
      parameters:
      - $ref: '#/components/parameters/ArtworkJobId'
      responses:
        '200':
          description: Current artwork state and metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArtworkStatus'
        '400':
          description: Missing or invalid input.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: The credential is missing, invalid, revoked, or expired.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: The credential lacks the required scope or cannot perform this operation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: The resource was not found for the authenticated account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Create Prints could not complete the request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    servers:
    - url: https://api.createprints.ai
      description: Create Prints API origin
  /api/image-generations/import:
    post:
      operationId: importArtwork
      summary: Import a standalone artwork file
      description: Runs safety and artwork-presentation checks on a PNG, JPEG, or WebP file up to 20 MB. An accepted file is stored privately and returned as completed and purchasable (`201`). If it appears to be a room scene, framed mockup, or another image rather than standalone artwork, no bytes or job are retained and the endpoint returns a structured rejection with HTTP `200`. If the safety service cannot run, the import is not accepted and the endpoint returns `503`.
      tags:
      - Artwork
      security:
      - agentApiKey: []
      - agentBearer: []
      - userSessionBearer: []
      - oauth2:
        - artwork:create
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
              - image
              properties:
                image:
                  type: string
                  format: binary
                  description: Standalone PNG, JPEG, or WebP artwork; maximum 20 MB.
                title:
                  type: string
                  description: Optional title stored with an accepted import.
      responses:
        '200':
          description: The file was rejected as non-standalone artwork and was not retained.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RejectedImport'
        '201':
          description: The artwork passed both checks and was retained privately.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AcceptedImport'
        '400':
          description: Missing or invalid input.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: The credential is missing, invalid, revoked, or expired.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: The credential lacks the required scope or cannot perform this operation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Create Prints could not complete the request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: The image safety check was unavailable; the file was not imported.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    servers:
    - url: https://api.createprints.ai
      description: Create Prints API origin
  /api/image-generations/list:
    get:
      operationId: listArtworks
      summary: List account artwork
      description: Returns the authenticated account's artwork newest first. Set `purchasable=true` to retain only completed jobs with uploaded images. Private image paths are exposed only to the signed-in owner using a user-session token; API keys and MCP tokens receive `null`.
      tags:
      - Artwork
      security:
      - agentApiKey: []
      - agentBearer: []
      - userSessionBearer: []
      - oauth2:
        - artwork:read
      parameters:
      - name: limit
        in: query
        description: Maximum records to return. Values are clamped to 1–50.
        schema:
          type: integer
          minimum: 1
          maximum: 50
          default: 10
      - name: cursor
        in: query
        description: Return records created before this ISO 8601 timestamp, normally the previous response's cursor.
        schema:
          type: string
          format: date-time
      - name: purchasable
        in: query
        description: Return only completed artwork with an uploaded image.
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: A cursor-paginated artwork page.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArtworkList'
        '400':
          description: Missing or invalid input.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: The credential is missing, invalid, revoked, or expired.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: The credential lacks the required scope or cannot perform this operation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Create Prints could not complete the request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    servers:
    - url: https://api.createprints.ai
      description: Create Prints API origin
  /api/image-generations/retry:
    post:
      operationId: retryArtworkGeneration
      summary: Requeue a stalled artwork job
      description: Requeues an account-owned processing job only after it has been inactive for at least 90 seconds. Completed, failed, and actively processing jobs return `409`; create a new generation instead of retrying a job marked failed.
      tags:
      - Artwork
      security:
      - agentApiKey: []
      - agentBearer: []
      - userSessionBearer: []
      - oauth2:
        - artwork:create
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ArtworkJobRequest'
      responses:
        '202':
          description: The stalled job was requeued.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequeuedArtwork'
        '400':
          description: Missing or invalid input.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: The credential is missing, invalid, revoked, or expired.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: The credential lacks the required scope or cannot perform this operation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: The resource was not found for the authenticated account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: The resource state does not permit this operation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Create Prints could not complete the request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    servers:
    - url: https://api.createprints.ai
      description: Create Prints API origin
components:
  schemas:
    QueuedArtwork:
      type: object
      required:
      - jobId
      - status
      - statusUrl
      - creditsRemaining
      properties:
        jobId:
          type: string
          format: uuid
        status:
          type: string
          const: queued
        statusUrl:
          type: string
          description: Relative polling URL.
        creditsRemaining:
          type: integer
          minimum: 0
    ColorScheme:
      type: object
      description: Persisted colour classification and affect analysis. Legacy palette fields retain their stored JSON value shapes.
      required:
      - colorPsychology
      - colorPalette
      - dominantColor
      - vibrantColor
      - complementaryColors
      - affect
      properties:
        colorCategory:
          type:
          - string
          - 'null'
        colorPsychology:
          type: object
          required:
          - impactLevel
          - primaryTrait
          properties:
            impactLevel:
              type:
              - string
              - 'null'
            primaryTrait:
              type:
              - string
              - 'null'
        recommendedRoom:
          type:
          - string
          - 'null'
        colorPalette:
          type: array
          items: {}
        dominantColor:
          type: array
          items: {}
        vibrantColor:
          type: array
          items: {}
        complementaryColors:
          type: array
          items: {}
        affect:
          oneOf:
          - $ref: '#/components/schemas/ColorAffect'
          - type: 'null'
    ArtworkListItem:
      type: object
      required:
      - jobId
      - status
      - purchasable
      - imagePrivate
      - createdAt
      properties:
        jobId:
          type: string
          format: uuid
        status:
          type: string
          enum:
          - processing
          - failed
          - complete
          - unknown
        purchasable:
          type: boolean
        title:
          type:
          - string
          - 'null'
        imagePaths:
          type:
          - array
          - 'null'
          items:
            type: string
        imagePrivate:
          type: boolean
        createdAt:
          type: string
          format: date-time
    ArtworkCheck:
      type: object
      description: Standalone-artwork classifier result; fields may expand.
      properties:
        status:
          type: string
        warningCodes:
          type: array
          items:
            type: string
        error:
          type:
          - string
          - 'null'
      additionalProperties: true
    ArtworkStatus:
      type: object
      required:
      - jobId
      - id
      - status
      - statusCode
      - creditsRemaining
      - imageUploaded
      - imagePrivate
      - purchasable
      - aspect
      - imageModelSize
      - colorScheme
      properties:
        jobId:
          type: string
          format: uuid
        id:
          type: string
          format: uuid
          description: Legacy alias of `jobId`.
        status:
          type: string
          enum:
          - processing
          - failed
          - complete
          - unknown
        statusCode:
          type: integer
          enum:
          - 1
          - 2
          - 3
        creditsRemaining:
          type: integer
          minimum: 0
        imageUploaded:
          type: boolean
        imagePaths:
          type:
          - array
          - 'null'
          items:
            type: string
        image_paths:
          type:
          - array
          - 'null'
          items:
            type: string
        imagePrivate:
          type: boolean
        visibility:
          type:
          - string
          - 'null'
        source:
          type:
          - string
          - 'null'
        purchasable:
          type: boolean
        aspect:
          $ref: '#/components/schemas/Aspect'
        imageModelSize:
          type: string
        promptSize:
          type:
          - integer
          - 'null'
        title:
          type:
          - string
          - 'null'
        description:
          type:
          - string
          - 'null'
        originalPrompt:
          type:
          - string
          - 'null'
        revisedPrompt:
          type:
          - string
          - 'null'
        keywords:
          type:
          - array
          - 'null'
          items:
            type: string
        warnings:
          type: array
          items:
            $ref: '#/components/schemas/ImportWarning'
        artworkCheck:
          $ref: '#/components/schemas/ArtworkCheck'
        colorScheme:
          $ref: '#/components/schemas/ColorScheme'
      additionalProperties: true
    ArtworkList:
      type: object
      required:
      - jobs
      - cursor
      properties:
        jobs:
          type: array
          items:
            $ref: '#/components/schemas/ArtworkListItem'
        cursor:
          type:
          - string
          - 'null'
          format: date-time
    ImportWarning:
      type: object
      required:
      - code
      - severity
      - message
      properties:
        code:
          type: string
        severity:
          type: string
          const: warning
        message:
          type: string
    CreateArtworkMultipart:
      type: object
      required:
      - inputType
      - size
      properties:
        inputType:
          type: string
          enum:
          - describe
          - printPhoto
          - interiorPhoto
        size:
          type: string
          examples:
          - 1536x1536
          - 1024x1536
          - 1536x1024
        prompt:
          type: string
          description: Required for `describe` unless an image is supplied.
        image:
          type: string
          format: binary
          description: Required for photo inputs; optional for `describe`.
        keywords:
          type: string
          description: Comma-separated values or a JSON array encoded as a form field.
        colors:
          type: string
          description: Comma-separated values or a JSON array encoded as a form field.
        styleId:
          type: string
        seedId:
          type: string
        creativeDirection:
          type: string
        forceOriginalPrompt:
          type: string
          enum:
          - 'true'
          - 'false'
          default: 'false'
        revision:
          type: string
          enum:
          - 'true'
          - 'false'
          default: 'false'
    Error:
      type: object
      description: Errors use `error`; some endpoints also return a stable `code`, validation `details`, or `retryable` hint.
      properties:
        error:
          type: string
        code:
          type: string
        details:
          type: array
          items:
            type: string
        retryable:
          type: boolean
      additionalProperties: true
    ColorAffect:
      type: object
      description: Continuous mood and colour analysis generated from the artwork palette.
      required:
      - arousal
      - valence
      - warmth
      - complexity
      - emotions
      - primaryTrait
      - temperature
      - energyLevel
      - impactLevel
      - harmony
      - rooms
      - recommendedRooms
      - rationale
      properties:
        arousal:
          type: number
          minimum: 0
          maximum: 1
        valence:
          type: number
          minimum: 0
          maximum: 1
        warmth:
          type: number
          minimum: 0
          maximum: 1
        complexity:
          type:
          - number
          - 'null'
          minimum: 0
          maximum: 1
        emotions:
          type: array
          maxItems: 4
          items:
            type: string
        primaryTrait:
          type: string
        temperature:
          type: string
        energyLevel:
          type: string
        impactLevel:
          type: string
        harmony:
          type: object
          required:
          - type
          - hueClusters
          properties:
            type:
              type: string
            hueClusters:
              type: integer
              minimum: 0
        rooms:
          type: array
          maxItems: 5
          items:
            type: object
            required:
            - room
            - score
            properties:
              room:
                type: string
              score:
                type: number
                minimum: 0
                maximum: 1
        recommendedRooms:
          type: array
          maxItems: 3
          items:
            type: string
        rationale:
          type: string
      additionalProperties: true
    Aspect:
      type: string
      enum:
      - square
      - portrait
      - landscape
    AcceptedImport:
      type: object
      required:
      - jobId
      - status
      - purchasable
      - imageUploaded
      - retained
      - imagePrivate
      - aspect
      - width
      - height
      - warnings
      properties:
        jobId:
          type: string
          format: uuid
        status:
          type: string
          const: complete
        purchasable:
          type: boolean
          const: true
        imageUploaded:
          type: boolean
          const: true
        retained:
          type: boolean
          const: true
        imagePrivate:
          type: boolean
          const: true
        aspect:
          $ref: '#/components/schemas/Aspect'
        width:
          type: integer
          minimum: 1
        height:
          type: integer
          minimum: 1
        warnings:
          type: array
          items:
            $ref: '#/components/schemas/ImportWarning'
        artworkCheck:
          $ref: '#/components/schemas/ArtworkCheck'
    CreateArtworkJson:
      type: object
      required:
      - prompt
      - size
      properties:
        inputType:
          type: string
          enum:
          - describe
          - printPhoto
          - interiorPhoto
          default: describe
        prompt:
          type: string
          minLength: 1
          description: Artwork description; required for JSON.
        size:
          type: string
          pattern: ^[0-9]+x[0-9]+$
          description: Width and height must be multiples of 16; longest side ≤3840 px; aspect ≤3:1; 655,360–8,294,400 total pixels. Prefer the selected variant's `generation.imageModelSize`.
          examples:
          - 1536x1536
          - 1024x1536
          - 1536x1024
        keywords:
          type: array
          items:
            type: string
        colors:
          type: array
          items:
            type: string
        styleId:
          type:
          - string
          - integer
          - 'null'
        seedId:
          type:
          - string
          - 'null'
        forceOriginalPrompt:
          type: boolean
          default: false
        referenceImageUrl:
          type:
          - string
          - 'null'
          format: uri
        revision:
          type: boolean
          default: false
      additionalProperties: true
    ArtworkJobRequest:
      type: object
      required:
      - jobId
      properties:
        jobId:
          type: string
          format: uuid
      additionalProperties: false
    RejectedImport:
      type: object
      required:
      - status
      - purchasable
      - imageUploaded
      - retained
      - aspect
      - width
      - height
      - warnings
      - artworkCheck
      properties:
        status:
          type: string
          const: rejected
        purchasable:
          type: boolean
          const: false
        imageUploaded:
          type: boolean
          const: false
        retained:
          type: boolean
          const: false
        aspect:
          $ref: '#/components/schemas/Aspect'
        width:
          type: integer
          minimum: 1
        height:
          type: integer
          minimum: 1
        warnings:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/ImportWarning'
        artworkCheck:
          $ref: '#/components/schemas/ArtworkCheck'
    RequeuedArtwork:
      type: object
      required:
      - code
      - jobId
      - status
      properties:
        code:
          type: string
          const: ok
        jobId:
          type: string
          format: uuid
        status:
          type: string
          const: requeued
  parameters:
    ArtworkJobId:
      name: id
      in: query
      required: true
      description: Account-owned artwork job ID.
      schema:
        type: string
        format: uuid
  securitySchemes:
    agentApiKey:
      type: apiKey
      in: header
      name: X-API-Key
      description: Create Prints account API key beginning with `cp_`. Required scopes vary by operation.
    agentBearer:
      type: http
      scheme: bearer
      description: Account API key (`cp_…`) or MCP OAuth token (`cp_mcp_access_…`) in Authorization.
    userSessionBearer:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Signed-in Create Prints user-session token; supported only where this scheme is listed.
    oauth2:
      type: oauth2
      description: Create Prints OAuth 2.0 authorization-code flow with PKCE for MCP and agent clients.
      flows:
        authorizationCode:
          authorizationUrl: https://api.createprints.ai/api/oauth/authorize
          tokenUrl: https://api.createprints.ai/api/oauth/token
          scopes:
            artwork:create: Create, import, and retry artwork jobs.
            artwork:read: Read and list artwork jobs.
            print_options:read: Read print variants, frames, prices, and postage estimates.
            checkout:create: Create checkout sessions and retry production submission.
            checkout:read: Read checkout, fulfilment, and shipment status.
            orders:read: Read orders and, on the current credit endpoint, generation credits.
externalDocs:
  description: Create Prints developer resources
  url: https://www.createprints.ai/developers
x-refined-from:
- createprints-ai-openapi.json
- createprints-ai-openapi.yml