> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.amniscient.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.amniscient.com/_mcp/server.

# Upload a Background

POST https://api.amniscient.com/upload/background-image
Content-Type: multipart/form-data

Uploads a single background image file to your organization's library.

Reference: https://docs.amniscient.com/api/api-reference/background-image

## Request

### Headers

- `x-api-key` (string, required) — Your organization's active API Key.

### Body (multipart/form-data)

This endpoint expects a multipart form containing a file.

- `organization_id` (string, required) — Your organization's unique identifier.
- `file` (file, required) — The path to the single background image file you'd like to upload. Image files must be in JPEG, PNG, or JPG format. The image files must also have a resolution of at least 1080p and have a landscape orientation.
- `label` (string, required) — A descriptive title for the background image file you'd like to upload.
- `frames_folder_id` (string, optional) — The unique identifier for the folder within your library where this background image file should be uploaded. If left empty, the background image file will be uploaded to the Unclassified folder.
- `inference_point_id` (string, optional) — The unique identifier for an existing inference point within your organization associated with the background image location. If an invalid inference point id value is provided, the background image upload will fail.

## Response

### 201

201 - Upload successful

- `savedFile` (string, optional) — The user input label of the successfully uploaded background image file.

## Errors

### 400 Bad Request Error

Invalid label or request

- `status` (string, optional) — A status code denoting success or failure.
- `message` (string, optional) — A message describing the successful action or error state.

### 401 Unauthorized Error

Unauthorized

- `status` (string, optional) — A status code denoting success or failure.
- `message` (string, optional) — A message describing the successful action or error state.

### 404 Not Found Error

Folder not found

- `status` (string, optional) — A status code denoting success or failure.
- `message` (string, optional) — A message describing the successful action or error state.

## Examples

**Request**

```json
{
  "file": "<file: string>",
  "label": "string",
  "organization_id": "string"
}
```

**Response**

```json
{
  "savedFile": "new-background.jpg"
}
```

**SDK Code**

```python SuccessExample
import requests

url = "https://api.amniscient.com/upload/background-image"

files = { "file": "open('string', 'rb')" }
payload = {
    "frames_folder_id": ,
    "inference_point_id": ,
    "label": "string",
    "organization_id": "string"
}
headers = {"x-api-key": "x-api-key"}

response = requests.post(url, data=payload, files=files, headers=headers)

print(response.json())
```

```javascript SuccessExample
const url = 'https://api.amniscient.com/upload/background-image';
const form = new FormData();
form.append('file', 'string');
form.append('frames_folder_id', '');
form.append('inference_point_id', '');
form.append('label', 'string');
form.append('organization_id', 'string');

const options = {method: 'POST', headers: {'x-api-key': 'x-api-key'}};

options.body = form;

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go SuccessExample
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.amniscient.com/upload/background-image"

	payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"string\"\r\nContent-Type: application/octet-stream\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"frames_folder_id\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"inference_point_id\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"label\"\r\n\r\nstring\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"organization_id\"\r\n\r\nstring\r\n-----011000010111000001101001--\r\n")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "x-api-key")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby SuccessExample
require 'uri'
require 'net/http'

url = URI("https://api.amniscient.com/upload/background-image")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = 'x-api-key'
request.body = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"string\"\r\nContent-Type: application/octet-stream\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"frames_folder_id\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"inference_point_id\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"label\"\r\n\r\nstring\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"organization_id\"\r\n\r\nstring\r\n-----011000010111000001101001--\r\n"

response = http.request(request)
puts response.read_body
```

```java SuccessExample
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.amniscient.com/upload/background-image")
  .header("x-api-key", "x-api-key")
  .body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"string\"\r\nContent-Type: application/octet-stream\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"frames_folder_id\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"inference_point_id\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"label\"\r\n\r\nstring\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"organization_id\"\r\n\r\nstring\r\n-----011000010111000001101001--\r\n")
  .asString();
```

```php SuccessExample
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.amniscient.com/upload/background-image', [
  'multipart' => [
    [
        'name' => 'file',
        'filename' => 'string',
        'contents' => null
    ],
    [
        'name' => 'label',
        'contents' => 'string'
    ],
    [
        'name' => 'organization_id',
        'contents' => 'string'
    ]
  ]
  'headers' => [
    'x-api-key' => 'x-api-key',
  ],
]);

echo $response->getBody();
```

```csharp SuccessExample
using RestSharp;

var client = new RestClient("https://api.amniscient.com/upload/background-image");
var request = new RestRequest(Method.POST);
request.AddHeader("x-api-key", "x-api-key");
request.AddParameter("undefined", "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"string\"\r\nContent-Type: application/octet-stream\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"frames_folder_id\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"inference_point_id\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"label\"\r\n\r\nstring\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"organization_id\"\r\n\r\nstring\r\n-----011000010111000001101001--\r\n", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift SuccessExample
import Foundation

let headers = ["x-api-key": "x-api-key"]
let parameters = [
  [
    "name": "file",
    "fileName": "string"
  ],
  [
    "name": "frames_folder_id",
    "value": 
  ],
  [
    "name": "inference_point_id",
    "value": 
  ],
  [
    "name": "label",
    "value": "string"
  ],
  [
    "name": "organization_id",
    "value": "string"
  ]
]

let boundary = "---011000010111000001101001"

var body = ""
var error: NSError? = nil
for param in parameters {
  let paramName = param["name"]!
  body += "--\(boundary)\r\n"
  body += "Content-Disposition:form-data; name=\"\(paramName)\""
  if let filename = param["fileName"] {
    let contentType = param["content-type"]!
    let fileContent = String(contentsOfFile: filename, encoding: String.Encoding.utf8)
    if (error != nil) {
      print(error as Any)
    }
    body += "; filename=\"\(filename)\"\r\n"
    body += "Content-Type: \(contentType)\r\n\r\n"
    body += fileContent
  } else if let paramValue = param["value"] {
    body += "\r\n\r\n\(paramValue)"
  }
}

let request = NSMutableURLRequest(url: NSURL(string: "https://api.amniscient.com/upload/background-image")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```