New THETA API version 2.1

codetricity · August 18, 2016, 10:39pm

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:

API v2.0
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)
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

Deprecated sessionId and deprecated/modified related commands. API level 2 is designed for one client connection and camera manufacturer should make sure that only one client at any time is connected (for example via limiting only one wifi connection).
- Deprecated commands startSession / updateSession / closeSession.
- Deprecated sessionId from input of commands takePicture / getOptions / setOptions.
Deprecated commands getImage / getMetadata.
- The absolute URL of a file is used to download directly from the HTTP server of the camera.
Added/modified commands and options for video capture, interval image capture and live preview.
- Added commands startCapture / stopCapture / getLivePreview / reset.
- Renamed listImages to listFiles and modified inputs/outputs to handle video type as well as image type.
- Added options previewFormat, captureInterval, captureNumber, remainingVideoSeconds, clientVersion.
Added 360 video XMP specification
Added apiLevel field to /osc/info output.
- apiLevel: Field was added in API level 2. It is considered to be API level 1 by default when this field is missing. It is developers’ responsibility to retrieve this information and implement differently based on the value.

Result of GET to http://192.168.1.1/osc/info

Result of POST to 192.168.1.1/osc/state

peggy · September 29, 2016, 12:45pm

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

peggy · September 29, 2016, 1:19pm

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

jcasman · September 29, 2016, 2:56pm

Yay, I love it when things work themselves out.

jcasman · September 29, 2016, 3:02pm

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

jasondaywalker · October 4, 2018, 7:44pm

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 ='http://192.168.1.1/osc/'
    #"http://192.168.1.1/osc/"
    url = url_base + url_request
    return url
def takePicture():
    pdb.set_trace()
    url = request("commands/execute")
    print (url)
    url1 = request("state")
    body = json.dumps({"name": "camera.takePicture","parameters": {}})
    req = requests.post(url, body)
    response = req.json()
    req1 = requests.post(url1, data=body)
    #*********************************************************
    #req excute picture to take
    #req1 find url of the pic just taken
    response1=req1.json()
    fileUrl = response1["state"]["_latestFileUrl"]
    print(fileUrl)
takePicture()

codetricity · October 4, 2018, 7:54pm

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": "http://192.168.1.1/files/abcde/", 
        "_captureStatus": "idle", 
        "_recordedTime": 0, 
        "_recordableTime": 0, 
        "_latestFileUrl": "http://192.168.1.1/files/abcde/100RICOH/R0010004.MP4", 
        "_batteryState": "disconnect", 
        "_apiVersion": 2 
    }     
}

Set the API version with clientVersion

https://developers.theta360.com/en/docs/v2.0/api_reference/options/client_version.html

jasondaywalker · October 4, 2018, 8:34pm

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/

codetricity · October 4, 2018, 9:22pm

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.

gist.github.com

https://gist.github.com/codetricity/cf4166b7000e652718ddb58f1033a121

theta_client_mode.py

"""
Test for THETA V client mode. Your workstation and the THETA V need to be 
connected to the same WiFi router.
This test script uses Python modules requests and pprint.
To install requests and pprint
  
      $ pip install requests
      $ pip install pprint

Once connected with WiFi, use the API here:

This file has been truncated. show original

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.

codetricity · October 5, 2018, 3:16am

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

github.com

codetricity/theta-s-api-tests/blob/theta-v/thetav-test.py

import requests
import pprint


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


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


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

This file has been truncated. show original

code listing

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

import requests
import pprint


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


def state(url, header):
    url = url + "state"
    req = requests.post(url, 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 = requests.post(
        url, json=payload)
    response = req.json()
    return response


pprint.pprint(info(url))

pprint.pprint(state(url, header))

pprint.pprint(takePicture(url, header))

jasondaywalker · October 5, 2018, 3:10pm

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

codetricity · October 5, 2018, 3:53pm

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.

DriverEye

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.

jcasman · October 6, 2018, 12:14am

@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.

khatnuoc994 · November 24, 2020, 7:25pm

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.

craig · November 24, 2020, 7:39pm

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.

https://api.ricoh/docs/theta-web-api-v2.1/getting_started/

https://api.ricoh/docs/theta-web-api-v2/options/client_version/

amby777 · May 18, 2021, 3:15pm

What is difference between THETA Web API v2 and v2.1 ??
Any (changes log or additional/deprecated features) documents available ?

amby777 · May 18, 2021, 3:15pm

Any (changes log or additional/deprecated features) documents available ?

https://api.ricoh/docs/theta-web-api-v2/

https://api.ricoh/docs/theta-web-api-v2.1/

craig · May 18, 2021, 3:19pm

If you want to support the v2 API cameras (S, SC), then you need to check for sessionId. The v2 is for S and SC, which are older cameras. You do not need to actually implement the v2 since you can set the default to the S and SC to v 2.1 using the technique below.

Getting_started

That is likely the main check you need.

For the specific options, this can help.

Index

POST /osc/commands/execute
{
    "name": "camera.setOptions",
    "parameters": {
        "sessionId": "SID_0001",
        "options": {
            "clientVersion": 2
        }
    }
}

To get the “sessionId”, you need to start a session.

POST /osc/commands/execute
    {
        "name": "camera.startSession",
        "parameters": {}
    }

State will show the _apiVersion that is currently in use.
https://api.ricoh/docs/theta-web-api-v2.1/protocols/state/