Request

Response

    Add files
    POST

    file

    Adds one or more files to a photoscene.

    Files can be added to photoscene either by uploading them directly or by providing public HTTP/HTTPS links. Although uploading multiple files at the same time might be more efficient, you should limit the number of files per request depending on your available bandwidth to avoid timeouts.

    Note: Uploaded files will be deleted after 30 days.

    Limitations

    • Only JPEG images are supported.
    • Maximum number of files in a single request: 20
    • Maximum size of a single file: 128 MB
    • Maximum uncompressed size of image in memory: 512 MB

    Resource Information

    Method and URI
    POST
    https://developer.api.autodesk.com/photo-to-3d/v1/file
    Authentication Context
    user context optional
    Required OAuth Scopes
    data:write
    Data Format
    JSON

    Request

    Headers

    Authorization*
    string
    Must be Bearer <token>, where <token> is obtained via either a two-legged or three-legged OAuth flow.
    Content-Type*
    string
    Must be application/x-www-form-urlencoded
    * Required

    Request

    Body Structure

    Image File

    For image files, this method does not have a request body structure.

    Survey File

    To specify GCPs (Ground Control Points) in a reconstruction, add an XML-formatted GCP definition file to the photoscene.

    • The coordinatesystem string attribute is required, and must be an id from the Autodesk supported library of coordinate systems.
    • Use LL84 for LLA.
    • Important: only LL84 is supported for now.
    • Marker id values must be unique.
    • In the gcp node, use long, lat & alt attribute names for degree based coordinate systems.
    • Units are inferred from the coordinate system definition. For example, AZ83-WIF implies that all coordinates specified in the xml are in US feet.
    <?xml version="1.0" encoding="UTF-8"?>
    <surveydata coordinatesystem="string" epsgcode="int" description="string (optional)">
      <markers>
        <marker id="id1 (int)" name="marker1 (string)">
          <images>
            <image name="image1 (string)" xpixel="int" ypixel="int"/>
            <image name="image2 (string)" xpixel="int" ypixel="int"/>
          </images>
          <!-- marker treated as a tie point if no gcp node specified -->
          <gcp long="double" lat="double" alt="double" checkpoint="bool (default=false)"/>
        </marker>
        <marker id="id2 (int)" name="marker2 (string)">
          <images>
            <image name="image1 (string)" xpixel="int" ypixel="int"/>
            <image name="image2 (string)" xpixel="int" ypixel="int"/>
          </images>
          <!-- marker treated as a tie point if no gcp node specified -->
          <gcp long="double" lat="double" alt="double" checkpoint="bool (default=false)"/>
        </marker>
      </markers>
    </surveydata>
    
    Show More

    Survey File Example

    <?xml version="1.0" encoding="UTF-8"?>
    <surveydata coordinatesystem="LL84" description="WGS84 datum, Latitude-Longitude; Degrees" epsgcode="4326">
      <markers>
        <marker id="0" name="10">
          <images>
            <image name="IMG_0001.JPG" xpixel="2831" ypixel="396"/>
          </images>
          <gcp long="38.005412" lat="-122.530565" alt="2000.100000" checkpoint="false"/>
        </marker>
        <marker id="1" name="11">
          <images>
            <image name="IMG_0002.JPG" xpixel="3941" ypixel="695"/>
            <image name="IMG_0003.JPG" xpixel="3472" ypixel="1026"/>
            <image name="IMG_0004.JPG" xpixel="3351" ypixel="875"/>
          </images>
          <gcp long="38.014125" lat="-122.540530" alt="2010.200000" checkpoint="false"/>
        </marker>
        <marker id="2" name="12">
          <images>
            <image name="IMG_0002.JPG" xpixel="2616" ypixel="2702"/>
            <image name="IMG_0005.JPG" xpixel="2910" ypixel="2505"/>
          </images>
          <gcp long="38.021250" lat="-122.510412" alt="2015.000000" checkpoint="true"/>
        </marker>
      </markers>
    </surveydata>
    
    Show More
    photosceneid*
    string
    Specifies the ID of the photoscene to add the files to
    type
    enum:string
    Specifies the type of file being uploaded Possible values: image, survey
    file[0]
    string
    Specifies the files to be uploaded - these may be URLs (i.e. http://, https://) or local files

    For externally stored files, please verify that the URLs are publically accessible

    * Required

    Response

    HTTP Status Code Summary

    200
    OK
    File was successfully uploaded
    403
    Forbidden
    Unauthorized

    Response

    Body Structure (200)

    Expand all
    photosceneid
    string
    ID of the photoscene.
    Files
    object
    An array of objects, where each element contains a file object.
    file
    object
    An object that represents an uploaded file.
    fileid
    string
    Internal ID assigned to the image file upon upload
    filename
    string
    Name of the file uploaded
    filesize
    string
    Size of the image file, in kilobytes; can be used to verify upload integrity
    msg
    string
    Message indicating the status of the file, can be empty
    Error
    object
    Even though the the service returns a HTTP Status Code of 200, it may return an error payload, which provides details on why the operation failed.
    code
    int
    A code that identifies the error type. See Error List for possible values
    msg
    string
    A short, human readable explanation of the error

    Example 1

    This example demonstrates sucessfully uploading of two image files from a remote server.

    Request

    curl -v 'https://developer.api.autodesk.com/photo-to-3d/v1/file' \
      -X 'POST' \
      -H 'Authorization: Bearer eyjhbGCIOIjIuzI1NiISimtpZCI6...' \
      -d "photosceneid=HCyjCRNHUsNsPII9GlhvE8LrF6LFxS4NHzgQj3ZDWmU" \
      -d "type=image" \
      -d "file[0]=http://www.autodesk.com/_MG_9026.jpg" \
      -d "file[1]=http://www.autodesk.com/_MG_9027.jpg"
    

    Response

    {
      "photosceneid": "AtAuFsedTdqWdhF9VzHepp5oM9PITiuizI4xdMbz",
      "Files": {
        "file": [{
          "filename": "_MG_9026.jpg",
          "filesize": "364436",
          "msg": "No error"
        }, {
          "filename": "_MG_9027.jpg",
          "filesize": "332689",
          "msg": "No error"
        }]
      }
    }
    
    Show More

    Example 2

    This example demonstrates sucessfully uploading of two image files from a local drive.

    Request

    curl -v 'https://developer.api.autodesk.com/photo-to-3d/v1/file' \
      -X 'POST' \
      -H 'Authorization: Bearer eyjhbGCIOIjIuzI1NiISimtpZCI6...' \
      -F "photosceneid=hcYJcrnHUsNSPII9glhVe8lRF6lFXs4NHzGqJ3zdWMU" \
      -F "type=image" \
      -F "file[0]=@c:/sample_data/_MG_9026.jpg" \
      -F "file[1]=@c:/sample_data/_MG_9027.jpg"
    

    Note: It is recommended that large file uploads be sent in separate requests to prevent API timeouts.

    Response

    {
      "photosceneid": "AtAuFsedTdqWdhF9VzHepp5oM9PITiuizI4xdMbz",
      "Files": {
        "file": [{
          "filename": "_MG_9026.jpg",
          "filesize": "364436",
          "msg": "No error"
        }, {
          "filename": "_MG_9027.jpg",
          "filesize": "332689",
          "msg": "No error"
        }]
      }
    }
    
    Show More

    Example 3

    This example demonstrates an unsucessfull attempt at uploading two image files to a non-existent photoscene.

    Request

    curl -v 'https://developer.api.autodesk.com/photo-to-3d/v1/file' \
      -X 'POST' \
      -H 'Authorization: Bearer eyjhbGCIOIjIuzI1NiISimtpZCI6...' \
      -F "photosceneid=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
      -F "type=image" \
      -F "file[0]=@c:/sample_data/_MG_9026.jpg" \
      -F "file[1]=@c:/sample_data/_MG_9027.jpg"
    

    Response

    {
      "Error": {
        "code": "19",
        "msg": "Specified Photoscene ID doesn't exist in the database"
      }
    }