# Upload API Reference

## Uploading an image for editing via API

Image upload endpoint allows you to upload an image directly from your computer or server for editing, instead of providing an image URL.

To upload an image, attach an image file as body part of <mark style="color:purple;">`multipart/form-data`</mark>. The other body part of <mark style="color:purple;">`multipart/form-data`</mark> should be the same as JSON for a regular image editing request, except there is no <mark style="color:purple;">`input`</mark> image URL option there. See [Image edit contract](https://docs.claid.ai/api-reference#image-edit-contract) for more info.

## Image Edit Upload

> Specifies: \
> \- how the image will be processed (\`operations\`)\
> \- where it will be stored (\`output\`)

```json
{"openapi":"3.1.0","info":{"title":"Claid REST API","version":"v1"},"tags":[{"name":"Image","description":"Encompasses operations with images."}],"security":[{"OAuth2PasswordBearer":[]},{"OAuth2PasswordBearer":["image_editing"]}],"components":{"securitySchemes":{"OAuth2PasswordBearer":{"type":"oauth2","flows":{"password":{"scopes":{},"tokenUrl":"token"}},"description":"To work with the Claid API, send requests over HTTPS and authenticate using the `Authorization` header in the following format:`Authorization: Bearer <YOUR_API_KEY>`. You do not need to provide a password.\n\nTo get your API key, [sign in to your Claid account](https://claid.ai/login) and click ***Create API key*** button from the ***Overview*** or ***API keys*** pages.\n\nClaid API’s base URL is `https://api.claid.ai/v1/`. All available endpoints are listed in the [Storage](#tag/Storage) and [Image](#tag/Image) sections. \n\n## Bearer\n\nThis API uses OAuth 2.0 [bearer token](https://datatracker.ietf.org/doc/html/rfc6750) (API key) to authorize requests."}},"schemas":{"Body_image_edit_upload_v1_image_edit_upload_post":{"title":"Body_image_edit_upload_v1_image_edit_upload_post","required":["file","data"],"type":"object","properties":{"file":{"title":"File","type":"string","format":"binary"},"data":{"title":"Data","type":"string"}}},"Response_EditResponse_":{"title":"Response[EditResponse]","type":"object","properties":{"data":{"$ref":"#/components/schemas/EditResponse"}},"description":"Wrapper for responses"},"EditResponse":{"title":"EditResponse","required":["input","output"],"type":"object","properties":{"input":{"$ref":"#/components/schemas/PipelineInputObject"},"output":{"$ref":"#/components/schemas/PipelineOutputObject"},"profiling":{"title":"Profiling","type":"object"}}},"PipelineInputObject":{"title":"PipelineInputObject","required":["ext","mps","mime","format","width","height"],"type":"object","properties":{"ext":{"title":"Ext","type":"string","description":"File extension. Can have values: `\"jpg\"`, `\"png\"`, `\"avif\"`"},"mps":{"title":"Mps","type":"number","description":"Megapixel count"},"mime":{"title":"Mime","type":"string","description":"MIME type (also known as ‘media type’)"},"format":{"title":"Format","type":"string","description":"File format. Can have values: `\"jpeg\"`, `\"png\"`, `\"avif\"`"},"width":{"title":"Width","type":"integer","description":"Image width in pixels"},"height":{"title":"Height","type":"integer","description":"Image height in pixels"}}},"PipelineOutputObject":{"title":"PipelineOutputObject","required":["ext","mps","mime","format","width","height"],"type":"object","properties":{"ext":{"title":"Ext","type":"string","description":"File extension. Can have values: `\"jpg\"`, `\"png\"`, `\"avif\"`"},"mps":{"title":"Mps","type":"number","description":"Megapixel count"},"mime":{"title":"Mime","type":"string","description":"MIME type (also known as ‘media type’)"},"format":{"title":"Format","type":"string","description":"File format. Can have values: `\"jpeg\"`, `\"png\"`, `\"avif\"`"},"width":{"title":"Width","type":"integer","description":"Image width in pixels"},"height":{"title":"Height","type":"integer","description":"Image height in pixels"},"tmp_url":{"title":"Tmp Url","type":"string","description":"Temporal URL of a processed image"},"object_key":{"title":"Object Key","type":"string","description":"Path to a processed image in a bucket"},"object_bucket":{"title":"Object Bucket","type":"string","description":"Bucket name"},"object_uri":{"title":"Object Uri","type":"string","description":"URI of a processed image in a bucket"},"claid_storage_uri":{"title":"Claid Storage Uri","type":"string","description":"URI of a processed image in a storage"}}},"HttpErrorDetails":{"title":"HttpErrorDetails","required":["error_code","error_type","error_message"],"type":"object","properties":{"error_code":{"title":"Error Code","type":"string"},"error_type":{"$ref":"#/components/schemas/ErrorType"},"error_message":{"title":"Error Message","type":"string"},"error_details":{"title":"Error Details","type":"object","default":{}}}},"ErrorType":{"title":"ErrorType","enum":["auth","dlvr","general","le","survey","storage","image","user_settings","user","validation","analytics","scene","billing","web","runtime_settings","animation","custom_models"],"type":"string","description":"An enumeration."}}},"paths":{"/v1/image/edit/upload":{"post":{"tags":["Image"],"summary":"Image Edit Upload","description":"Specifies: \n- how the image will be processed (`operations`)\n- where it will be stored (`output`)","operationId":"image_edit_upload_v1_image_edit_upload_post","requestBody":{"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_image_edit_upload_v1_image_edit_upload_post"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Response_EditResponse_"}}}},"401":{"description":"Authorization is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpErrorDetails"}}}},"402":{"description":"No API calls left.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpErrorDetails"}}}},"403":{"description":"Not enough permissions.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpErrorDetails"}}}},"422":{"description":"Unprocessable Entity.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpErrorDetails"}}}},"429":{"description":"Too many requests.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpErrorDetails"}}}}}}}}}
```

#### **Request**

{% tabs %}
{% tab title="HTTP" %}

```http
POST /v1/image/edit/upload HTTP/1.1
Host: api.claid.ai
Authorization: Bearer {YOUR_API_KEY}
Content-Type: multipart/form-data; boundary="boundary"

--boundary
Content-Disposition: form-data; name="file"; filename="the_image"

< ./the_image.jpg

--boundary
Content-Disposition: form-data; name="data"
Content-Type: application/json

{
  "operations": {
    "resizing": {
      "width": 1000
    },
    "background": {
      "remove": false
    }
  }
}

--boundary--
```

{% endtab %}

{% tab title="cURL" %}

<pre class="language-shell"><code class="lang-shell"><strong>curl -X POST --location "https://api.claid.ai/v1/image/edit/upload" --http1.1 \
</strong>    -H "Host: api.claid.ai" \
    -H "Authorization: Bearer {YOUR_API_KEY}" \
    -H "Content-Type:multipart/form-data" \
    -F "file=@./the_image.jpg;filename=the_image.jpg" \
    -F "data={\"operations\":{\"resizing\":{\"width\":1000},\"background\":{\"remove\":false}}};type=application/json"
</code></pre>

{% endtab %}
{% endtabs %}

#### Request headers

```http
Content-Type: multipart/form-data; boundary="boundary"
Authorization: Bearer {YOUR_API_KEY}
```

In order to send a request, you should set a <mark style="color:purple;">`Content-Type`</mark> header to let our system know that you are providing a valid form data payload and an <mark style="color:purple;">`Authorization`</mark> header with a generated API key to [identify yourself](https://docs.claid.ai/authentication) as a Claid user.

The form data payload should have two blocks of data (body parts), with a delimiter (boundary) separating each block.

The block with an image file should have a <mark style="color:purple;">`Content-Disposition`</mark> header equal to <mark style="color:purple;">`form-data`</mark> with two required keys: a <mark style="color:purple;">`name`</mark> key with a value equal to <mark style="color:purple;">`file`</mark> and a <mark style="color:purple;">`filename`</mark> key that will be assigned to an output result image (it is better not to include the extension in a <mark style="color:purple;">`filename`</mark>, as it can be overwritten by [Output options](https://docs.claid.ai/image-i-o#output-image-file-types)).

```http
Content-Disposition: form-data; name="file"; filename="the_image"
```

The block with edit operations should have two headers: a <mark style="color:purple;">`Content-Disposition`</mark> header equal to <mark style="color:purple;">`form-data`</mark> with a <mark style="color:purple;">`name`</mark> key with a value equal to <mark style="color:purple;">`data`</mark> and a <mark style="color:purple;">`Content-Type`</mark> header to let our system know that you are providing a valid JSON payload.

```http
Content-Disposition: form-data; name="data"
Content-Type: application/json
```

#### **Response body and headers**

The response body and headers is equal to response body and headers of regular image edit request. See the [Read a response](https://docs.claid.ai/api-reference#read-a-response) and [Response Headers](https://docs.claid.ai/api-reference#response-headers) to learn more.