Using Your API

Once everything above is configured, you will be able to invoke your API using the "run" endpoint on your API dashboard. Our services are currently asynchronous, so you must use the "status" endpoint to get the status/results of each run using the ID present in the run response payload. You can also pass in a webhook URL when invoking "run" within the JSON body.

Our own APIs are built using the same tools, so you can take a look at the RunPod API overview. The only difference is that your custom API endpoint only accepts requests using your own account's API key, not any RunPod API key.

We offer two different kinds of run mechanisms: synchronous responses and asynchronous responses.

Running your API

/runsync

curl -X POST https://api.runpod.ai/v2/<your-api-id>/run \
-H 'Content-Type: application/json'                             \
-H 'Authorization: Bearer xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'    \
-d '{"input": {<your-input-json}}'

# this requires the installation of runpod-python
# with `pip install runpod-python` beforehand

import runpod

runpod.api_key = "xxxxxxxxxxxxxxxxxxxxxx" # you can find this in settings

endpoint = runpod.Endpoint("ENDPOINT_ID")

run_request = endpoint.run_sync(
    {"your_model_input_key": "your_model_input_value"}
)

here's a possible example request (taken from our stable diffusion image)

curl -X POST https://api.runpod.ai/v2/<your-api-id>/run \
-H 'Content-Type: application/json'                             \
-H 'Authorization: Bearer xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'    \
-d '{"input": {"prompt": "a cute magical flying dog, fantasy art drawn by disney concept artists"}}'

# this requires the installation of runpod-python
# with `pip install runpod-python` beforehand

import runpod

runpod.api_key = "xxxxxxxxxxxxxxxxxxxxxx" # you can find this in settings

endpoint = runpod.Endpoint("ENDPOINT_ID")

run_request = endpoint.run_sync(
    {"prompt": "a cute magical flying dog, fantasy art drawn by disney concept artists"}
)

print(run_request)

this should give a direct response if the code runs for < 90 seconds, or else it'll give a status response (which you can see below)

Sample response

{
  "delayTime": 123456, // (milliseconds) time in queue
  "executionTime": 1234, // (milliseconds) time it took to complete the job
  "gpu": "24", // gpu type used to run the job
  "id": "c80ffee4-f315-4e25-a146-0f3d98cf024b",
  "input": {
    "prompt": "a cute magical flying dog, fantasy art drawn by disney concept artists"
  },
  "output": [
    {
      "image": "https://job.results1",
      "seed": 1
    },
    {
      "image": "https://job.results2",
      "seed": 2
    }
  ],
  "status": "COMPLETED"
}

/run

curl -X POST https://api.runpod.ai/v2/<your-api-id>/run \
-H 'Content-Type: application/json'                             \
-H 'Authorization: Bearer xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'    \
-d '{"input": {<your-input-json}}'

# this requires the installation of runpod-python
# with `pip install runpod-python` beforehand

import runpod

runpod.api_key = "xxxxxxxxxxxxxxxxxxxxxx" # you can find this in settings

endpoint = runpod.Endpoint("ENDPOINT_ID")

run_request = endpoint.run(
   {"your_model_input_key": "your_model_input_value"}
)

print(run_request.status())

here's a possible example request

curl -X POST https://api.runpod.ai/v2/<your-api-id>/run \
-H 'Content-Type: application/json'                             \
-H 'Authorization: Bearer xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'    \
-d '{"input": {"prompt": "a cute magical flying dog, fantasy art drawn by disney concept artists"}}'

# this requires the installation of runpod-python
# with `pip install runpod-python` beforehand

import runpod

runpod.api_key = "xxxxxxxxxxxxxxxxxxxxxx" # you can find this in settings

endpoint = runpod.Endpoint("ENDPOINT_ID")

run_request = endpoint.run(
    {"prompt": "a cute magical flying dog, fantasy art drawn by disney concept artists"}
)

print(run_request.status())

running your api via /run runs the code asynchronously, here's a sample response

sample response (for curl)

{
    "id": "c80ffee4-f315-4e25-a146-0f3d98cf024b",
    "status": "IN_QUEUE"
}

/status

Sample request

curl https://api.runpod.ai/v2/<your-api-id>/status/<your-status-id>

# this requires the installation of runpod-python
# with `pip install runpod-python` beforehand

import runpod

runpod.api_key = "xxxxxxxxxxxxxxxxxxxxxx" # you can find this in settings

endpoint = runpod.Endpoint("ENDPOINT_ID")

run_request = endpoint.run(
    {"prompt": "a cute magical flying dog, fantasy art drawn by disney concept artists"}
)

print(run_request.status())

sample response (for job in progress)

{
    "delayTime": 2624,
    "id": "c80ffee4-f315-4e25-a146-0f3d98cf024b",
    "input": {
        "prompt": "a cute magical flying dog, fantasy art drawn by disney concept artists"
    },
    "status": "IN_PROGRESS"
}

sample response (for completed job)

{
  "delayTime": 123456, // (milliseconds) time in queue
  "executionTime": 1234, // (milliseconds) time it took to complete the job
  "gpu": "24", // gpu type used to run the job
  "id": "c80ffee4-f315-4e25-a146-0f3d98cf024b",
  "input": {
    "prompt": "a cute magical flying dog, fantasy art drawn by disney concept artists"
  },
  "output": [
    {
      "image": "https://job.results1",
      "seed": 1
    },
    {
      "image": "https://job.results2",
      "seed": 2
    }
  ],
  "status": "COMPLETED"
}