Controls & Limitations

These endpoints provide standard functionality for submitting jobs and retrieving the output from job requests. In this document, we'll cover the following key endpoints:

/run
/runsync
/status/{jobid}
/cancel/{jobid}

We will also discuss the job payload capacity limitations for each endpoint.

/run

The /run endpoint is used to submit job requests. A unique Job ID is returned upon submitting a job to this endpoint. The Job ID can be used to check the status of a job and retrieve the output upon completion.

Payload Capacity: 10MB.

Rate limit: 1000 per second.

/run | Response Example

{'id': 'eaebd6e7-6a92-4bb8-a911-f996ac5ea99d', 'status': 'IN_QUEUE'}

/runsync

The /runsync endpoint is used for shorter running jobs. When a job is submitted to this endpoint, if the job completes within 30 seconds, the job output is returned in the same request. If the job does not complete within this time frame, a Job ID is returned instead, which can be used to check the job status and retrieve the output upon completion.

Payload Capacity: 20MB.

Rate limit: 2000 per second.

Job Availability: Successful job results only maintained for 60 seconds after completion.

/runsync | Response Example

{
  'delayTime': 824,
 'executionTime': 3391,
 'id': 'sync-79164ff4-d212-44bc-9fe3-389e199a5c15',
 'output': [
   {
     'image': 'https://14068d66ba387efac9ce5e4b1741bcf2.r2.cloudflarestorage.com/ai-api/06-23/sync-79164ff4-d212-44bc-9fe3-389e199a5c15_0.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=16b502c87564788383d52ec498a61a24%2F20230613%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20230613T101718Z&X-Amz-Expires=604800&X-Amz-SignedHeaders=host&X-Amz-Signature=8e810e9593c56523a77107875f2aa14a997ba64115fbc04856e68bf67da296a1',
   		'seed': 46578
   }
 ],
 'status': 'COMPLETED'
}

/runsync | Response Example after 30 seconds

{'id': '5a65c668-e99e-4e4c-81fd-0d106a843ee8', 'status': 'IN_QUEUE'}

/stream/{jobid}

The /stream/{jobid} endpoint is to be used in conjunction with generator-type handlers. As generator-type handlers yield results, these results will become available at the streaming endpoint.

{"output": "your yeilded result"}

/status/{jobid}

The /status/{jobid} endpoint is used to check the status of a job. Replace {jobid} with the unique Job ID returned when the job was submitted. The output is returned at this endpoint if the job is completed; otherwise, you will receive the current status of the job.

/status/ | Example Response | IN_QUEUE

{'id': '5a65c668-e99e-4e4c-81fd-0d106a843ee8', 'status': 'IN_QUEUE'}

/status/ | Eample Response | COMPLETED

{'delayTime': 609,
 'executionTime': 3050,
 'id': '525b1754-4cf4-4983-a0c0-7ba9799f3e74',
 'output': [{'image': 'https://14068d66ba387efac9ce5e4b1741bcf2.r2.cloudflarestorage.com/ai-api/06-23/525b1754-4cf4-4983-a0c0-7ba9799f3e74_0.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=16b502c87564788383d52ec498a61a24%2F20230613%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20230613T180351Z&X-Amz-Expires=604800&X-Amz-SignedHeaders=host&X-Amz-Signature=5becc83c7ccbf55d36085de1ab22e0a13ef336b1699f8acf50ff1a676bfd53c8',
   'seed': 46578}],
 'status': 'COMPLETED'}

/cancel/{jobid}

The /cancel/{jobid} endpoint is used to cancel a job early. Replace {jobid} with the unique Job ID of the job you wish to cancel.

/cancel/ | Example Response

{'id': 'e8d30bc5-9e9c-4bed-a3a2-0daaddda77ea', 'status': 'CANCELLED'}

/purge-queue

The /purge-queue endpoint clears all jobs in the queue; it will not cancel jobs in progress.

/purge-queue | ExampleResponse

{
    "removed": 0,
    "status": "completed"
}

/health

The /health/ endpoint is used to receive worker numbers and additional statistics on a particular endpoint.

a GET request must be sent to this endpoint

/health | Example Response

{
  'jobs': {
    'completed': 1,
  	'failed': 5,
  	'inProgress': 0,
  	'inQueue': 2,
  	'retried': 0
  },
  	'workers': {
      'idle': 0, 
      'running': 0
    }
}