New THETA API version 2.1

There is a new THETA API version 2.1. The version 2.0 API still works for now, but it is recommended that you update your apps to ensure future compatibility.

App developers: Be aware these changes may affect your previously-published app in the future and it is your responsibility to make corresponding changes to either handle both versions or remind camera owners to update their firmware.

If you want to compare the different documentation versions, you can toggle between the two different versions using the green rectangle on the main API reference page.

In your program, you can set the API version with camera.setOptions.

    "name": "camera.setOptions",
    "parameters": {
        "sessionId": "SID_0001",
        "options": {
            "clientVersion": 2

One of the major changes is that you do not have to specify the sessionId for command execution.

version 2.0

    "name": "camera.takePicture",
    "parameters": {
    	"sessionId": "SID_0001"

version 2.1

    "name": "camera.takePicture",
    "parameters": {

The _listAll command of version 2.0 has been replaced with listFiles

Example (version 2.1)

    "name": "camera.listFiles",
    "parameters": {
    	"fileType": "all",
    	"entryCount": 3,
        "maxThumbSize": 640

This means that that there are now four API versions in current use for the THETA, 3 for the THETA S and one for the THETA m15.

For the THETA S, the three APIs are:

  1. API v2.0
  2. API v2.1 - which is often referred to as API v2 reference (there doesn’t appear to be a clear difference between v2.0 and v2.1 in some of the reference documentation)
  3. v2 USB API - this is based off of the MTP 1.1 specification not the OSC specification

You should use the API v2.1 (the WiFi) one for your applications. There is no reason to use v2.0. v2 USB API can be used if you application works better with a USB connection, which is probably only the case for an application with specialized hardware like a Raspberry Pi Zero controller.

THETA API v2.1 is compliant with Open Spherical Camera (OSC) API level 2. Here are the differences between OSC API level 1 and OSC API level 2

API level 2 key changes

Result of GET to

Result of POST to

1 Like

Can you tell me how to go about updating to 2.1?

Nevr mind - I got a pop-up with install option. All good


Yay, I love it when things work themselves out. :astonished:

…though actually, what do you mean by “got a pop-up”? Can you describe this install option you’re talking about?

Thank you all for the help!
I am beginning to develop in python for ThetaV in Api2.1 and I tried the same command to take pictures in restlet and it worked but it kept giving me 400 in python3, can anyone help look for the problem,Much appreciated!

def request(url_request):
    url_base =''
    url = url_base + url_request
    return url
def takePicture():
    url = request("commands/execute")
    print (url)
    url1 = request("state")
    body = json.dumps({"name": "camera.takePicture","parameters": {}})
    req =, body)
    response = req.json()
    req1 =, data=body)
    #req excute picture to take
    #req1 find url of the pic just taken
    fileUrl = response1["state"]["_latestFileUrl"]

Thanks for taking a look at the API.

You may need to set the API version to 2 prior to taking a picture.

POST /osc/state

    "fingerprint": "FIG_0003", 
    "state": { 
        "batteryLevel": 1.0, 
        "storageUri": "", 
        "_captureStatus": "idle", 
        "_recordedTime": 0, 
        "_recordableTime": 0, 
        "_latestFileUrl": "", 
        "_batteryState": "disconnect", 
        "_apiVersion": 2 

Set the API version with clientVersion

thank you for reply, I am confused by the APII version,
according to /state/, I am getting api 2.0, but I found all session id start session etc all gone, so I assume it is in the newest version and using the same api, I can get 200 for /state/

Did you specify the content-type header in the request?

I haven’t looked at the Python code in a while and don’t immediately know how to specify the content-type header with requests. Though, I think you need to do this.

I did a test with client mode that worked.

You can also use curl as an intermediary step and then move to Python once you have the prototype working.

I suspect you need to set the content-type header with Python requests. If you get it working, please post an example.

Just tested the code below with python3. works fine. I think that if you add the header, your code will work.

Remember that the THETA V can’t be plugged into your computer USB when you are using the Wi-Fi API.

Also uploaded to github

code listing

Here’s the exact same code you can just copy and past into your text editor.

import requests
import pprint

url = ""
header = {'Content-Type': 'application/json'}

def state(url, header):
    url = url + "state"
    req =, headers=header)
    response = req.json()
    return response

def info(url):
    url = url + "info"
    req = requests.get(url)
    response = req.json()
    return response

def takePicture(url, header):
    url = url + "commands/execute"
    payload = {"name": "camera.takePicture"}
    req =
        url, json=payload)
    response = req.json()
    return response


pprint.pprint(state(url, header))

pprint.pprint(takePicture(url, header))

thanks , I found the problem is due to json.dumps() instead of using it I took json=thetacommand and it will work.

1 Like

First, congratulations! Second, thanks for letting us know what the problem was. It helps other people.

Please post updates of your project and adventure with coding.

I also would like to build a Python project, but instead of building a Python project, I’ve been spending time with Android Studio and the plug-in. This is cool, but I love the elegance and friendliness of Python.

If you want to share what your project vision is, please post. It may inspire me and others to build something in Python as well.

My Unfinished Python Projects

theta pytester

Project Status Description
theta tester Not Started Desktop tester for THETA V settings and API

I built a lesson for my daughter using the Python GUI toolkit called kivy to test more of the API functions of the THETA camera.


Project Status Description
DriverEye Finished concept for online hackathon Used car 360 picture taking and display system

Previously, I worked with my son to build a used-car 360 picture taking system with Python and Pygame. In the screenshot below, the thing that looks like a tablet is actually a Raspberry Pi with touchscreen.



THETA Real Estate

Project Status Description
THETA Real Estate Finished prototype for hackathon take pictures of inside of car and show on web

In the example below, I built a mobile app with Python to take take pictures for a prototype real estate site that was powered by A-Frame for the web-browser interface. I’m using Python to control the camera. The GUI Pygame. You can use RAPT to get the Pygrame app onto Android.

Pygame GUI

My early projects used Pygame simply because my son and I were familiar with it. I don’t think it’s a good choice for a GUI. Though, I used it and it was easy to use. If I were to start a new project, I would use kivy.

@jasondaywalker, thanks a ton for posting, this looks like useful info. If you have a chance to share more details about your project and what you’re trying accomplish, I’d love to hear more.

Hi. I’ve got problem when the sample using v2.0 app just identity TheTA M15 without preview. I have to download sample using api v2.1 to open TheTa V. How can i combine both of them in only one app? My idea is identify appversion but still can’t find the difference in code in 2 ver of example.

The m15 uses ptp API, which is completely different from the THETA S and above.

You can try GetDeviceInfo with the m15 and see if it responds. If not, then use state with the Wi-Fi API to get the _apiVersion.