Skip to main content
GET
/
pictoryapis
/
v1
/
jobs
/
{jobid}
Get Image Generation Job
curl --request GET \
  --url https://api.pictory.ai/pictoryapis/v1/jobs/{jobid} \
  --header 'Authorization: <authorization>'
{
    "job_id": "4d82d040-4394-4371-867d-72ae1dd62b6d",
    "success": true,
    "data": {
        "status": "in-progress"
    }
}

​
Overview

This endpoint retrieves the current status and output of an AI image generation job using its unique job ID. While the generation is in progress, it returns the job status. Once the image generation completes, it returns the output including the image URL, dimensions, and AI credits consumed.
A valid API key is required to use this endpoint. Obtain your API key from the API Access page in your Pictory dashboard.

​
API Endpoint

GET https://api.pictory.ai/pictoryapis/v1/jobs/{jobid}

​
Request Parameters

​
Path Parameters

​
jobid
uuid
required
The unique identifier (UUID) of the image generation job. This is the jobId returned by the Generate Image endpoint.Example: "4d82d040-4394-4371-867d-72ae1dd62b6d"

​
Headers

​
Authorization
string
required
API key for authentication (starts with pictai_)
Authorization: YOUR_API_KEY

​
Response

​
In-Progress Response

Returned while the image is being generated:
​
job_id
string
The unique identifier of the image generation job
​
success
boolean
true while the job is processing
​
data
object
​
status
string
"in-progress" while the image is still being generated

​
Completed Response

Returned when the image has been generated successfully:
​
job_id
string
The unique identifier of the image generation job
​
success
boolean
true when the job has completed successfully
​
data
object
Contains the image generation output.
​
status
string
"completed" when the image has been generated successfully
​
url
string
Direct download URL for the generated image file (PNG)
​
width
number
Width of the generated image in pixels
​
height
number
Height of the generated image in pixels
​
aiCreditsUsed
number
Number of AI credits consumed for this image generation

​
Failed Response

Returned when the image generation job has failed:
​
job_id
string
The unique identifier of the image generation job
​
success
boolean
false when the job has failed
​
data
object
​
status
string
"failed" when the image generation has failed
​
error_code
string
Error code identifying the failure type (e.g., "5001")
​
error_message
string
Descriptive message explaining the cause of the failure

​
Response Examples

{
    "job_id": "4d82d040-4394-4371-867d-72ae1dd62b6d",
    "success": true,
    "data": {
        "status": "in-progress"
    }
}

​
Status Codes

Status CodeDescription
200Request processed successfully. Check the status field in data to determine the job state (in-progress, completed, or failed).
401Unauthorized. The API key in the Authorization header is missing or invalid.
404Job not found. The provided jobid does not match any existing job.
500Internal server error. Retry the request after a brief delay.

​
Completed Response Fields

FieldDescription
urlDirect download link for the generated PNG image file
widthWidth of the generated image in pixels
heightHeight of the generated image in pixels
aiCreditsUsedNumber of AI credits consumed for this generation

​
Code Examples

Replace YOUR_API_KEY with your actual API key and use the jobId returned from the Generate Image endpoint.
curl --request GET \
  --url 'https://api.pictory.ai/pictoryapis/v1/jobs/4d82d040-4394-4371-867d-72ae1dd62b6d' \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'accept: application/json' | python -m json.tool

​
Polling Best Practices

Use a polling interval of 10–30 seconds when checking job status. Polling too frequently may result in rate limiting.
  1. Use webhooks when possible. Configure a webhook URL in the original generate image request to receive automatic notification when the job completes, rather than polling.
  2. Implement timeouts. Set a reasonable maximum wait time. Image generation typically completes within a few minutes.
  3. Handle failures gracefully. Inspect error_code and error_message in failed responses to determine the cause and whether the request can be retried.