Skip to content

Latest commit

 

History

History
176 lines (135 loc) · 9.07 KB

ocs-text2image-api.rst

File metadata and controls

176 lines (135 loc) · 9.07 KB

OCS Text-To-Image API

.. versionadded:: 28

The OCS Text-To-Image API allows you to run image generation tasks implemented by apps using :ref:`the backend Text-To-Image API<text2image>`.

The base URL for all calls to this API is: <nextcloud_base_url>/ocs/v2.php/text2image/

All calls to OCS endpoints require the OCS-APIRequest header to be set to true.

Check availability

.. versionadded:: 28
  • Method: GET
  • Endpoint: /is_available
  • Response:
    • Status code:
      • 200 OK
    • Data:
field type Description
isAvailable bool Boolean indicating whether any Text-To-Image providers are installed

Schedule a task

.. versionadded:: 28

Note

The endpoint is rate limited as it can be quite resource intensive. Users can make 20 requests in 2 minutes, guests only 5

  • Method: POST
  • Endpoint: /schedule
  • Data:
field type Description
input string The input text for the task
numberOfImages int The number of images to generate (optional; default: 8)
appId string The id of the requesting app
identifier string An app-defined identifier for the task (optional)

If possible the task will be executed while the request is processed on the server, otherwise it is scheduled as a background job.

  • Response:
    • Status code:
      • 200 OK
      • 412 Precondition Failed - When the task type is not available currently
      • 429 Too Many Requests - When the rate limiting was exceeded
    • Data:
      • id - Only provided in case of 200 OK, the assigned task id, int
      • input - Only provided in case of 200 OK, the task input, string
      • status - Only provided in case of 200 OK, the current task status, int, see :ref:`the backend Text-To-Image API<text2image_statuses>`
      • userId - Only provided in case of 200 OK, the originating userId of the task, string
      • appId - Only provided in case of 200 OK, the originating appId of the task, string
      • identifier - Only provided in case of 200 OK, the originating appId of the task, string
      • numberOfImages - Only provided in case of 200 OK, the number of generated images, int
      • completionExpectedAt - Only provided in case of 200 OK, the date and time when the result is expected to be completed as a UNIX timestamp, int
      • message - Only provided when not 200 OK, an error message in the user's language, ready to be displayed

Fetch a task by ID

.. versionadded:: 28

Note

The endpoint is rate limited as it can be quite resource intensive. Users can make 20 requests in 2 minutes, guests only 5

  • Method: POST
  • Endpoint: /task/{id}
  • Response:
    • Status code:
      • 200 OK
      • 404 Not Found - When the task could not be found
    • Data:
      • id - Only provided in case of 200 OK, the assigned task id, int
      • input - Only provided in case of 200 OK, the task input, string
      • status - Only provided in case of 200 OK, the current task status, int, see :ref:`the backend Text-To-Image API<text2image_statuses>`
      • userId - Only provided in case of 200 OK, the originating userId of the task, string
      • appId - Only provided in case of 200 OK, the originating appId of the task, string
      • identifier - Only provided in case of 200 OK, the originating appId of the task, string
      • numberOfImages - Only provided in case of 200 OK, the number of generated images, int
      • completionExpectedAt - Only provided in case of 200 OK, the date and time when the result is expected to be completed as a UNIX timestamp, int
      • message - Only provided when not 200 OK, an error message in the user's language, ready to be displayed

Fetch a result image

.. versionadded:: 28
  • Method: POST
  • Endpoint: /task/{id}/image/{index} * index: The index of the image, starting at 0
  • Response:
    • Status code:
      • 200 OK
      • 404 Not Found - When the task could not be found, isn't successful, isn't completed yet, or the index is out of bounds
    • Data: The raw image data

Delete a task

.. versionadded:: 28
  • Method: DELETE
  • Endpoint: /task/{id}
  • Response:
    • Status code:
      • 200 OK
      • 404 Not Found - When the task could not be found
    • Data:
      • id - Only provided in case of 200 OK, the assigned task id, int
      • input - Only provided in case of 200 OK, the task input, string
      • status - Only provided in case of 200 OK, the current task status, int, see :ref:`the backend Text-To-Image API<text2image_statuses>`
      • userId - Only provided in case of 200 OK, the originating userId of the task, string
      • appId - Only provided in case of 200 OK, the originating appId of the task, string
      • identifier - Only provided in case of 200 OK, the originating appId of the task, string
      • numberOfImages - Only provided in case of 200 OK, the number of generated images, int
      • completionExpectedAt - Only provided in case of 200 OK, the date and time when the result is expected to be completed as a UNIX timestamp, int
      • message - Only provided when not 200 OK, an error message in the user's language, ready to be displayed

List tasks by App

.. versionadded:: 28

Note

The endpoint is rate limited as it can be quite resource intensive. Guests can only do 5 requests within 2 minutes

  • Method: DELETE
  • Endpoint: /tasks/app/{appId}
  • Data:
field type Description
appId string The id of the requesting app
identifier string An app-defined identifier for the task (optional)
  • Response:
    • Status code:
      • 200 OK
      • 404 Not Found - When the task could not be found
    • Data:
      • Only provided in case of 200 OK, an array of objects:
        • id - the assigned task id, int
        • input - the task input, string
        • status - the current task status, int, see :ref:`the backend Text-To-Image API<text2image_statuses>`
        • userId - the originating userId of the task, string
        • appId - the originating appId of the task, string
        • identifier - the originating appId of the task, string
        • numberOfImages - the number of generated images, int
        • completionExpectedAt - the date and time when the result is expected to be completed as a UNIX timestamp, int
      • message - Only provided when not 200 OK, an error message in the user's language, ready to be displayed