OCS Text-To-Image API

Added in version 28.

The OCS Text-To-Image API allows you to run image generation tasks implemented by apps using the backend Text-To-Image API.

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

Added in version 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

Added in version 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 the backend Text-To-Image API

    • 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

Added in version 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 the backend Text-To-Image API

    • 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

Added in version 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

Added in version 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 the backend Text-To-Image API

    • 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

Added in version 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 the backend Text-To-Image API

      • 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