Skip to main content
POST
/
v1
/
images
/
edits
cURL
curl -s 'https://api.deerapi.com/v1/images/edits' \
  -H "Authorization: Bearer $DEERAPI_KEY" \
  -F 'prompt=Add a small red ribbon to the paper boat.' \
  -F 'model=gpt-image-2' \
  -F 'response_format=json' \
  -F 'image=@/path/to/image.png'
{
  "created": 1776836647,
  "usage": {
    "prompt_tokens": 0,
    "completion_tokens": 0,
    "total_tokens": 981,
    "prompt_tokens_details": {
      "cached_tokens_details": {}
    },
    "completion_tokens_details": {},
    "input_tokens": 785,
    "output_tokens": 196,
    "input_tokens_details": {
      "image_tokens": 768,
      "text_tokens": 17,
      "cached_tokens_details": {}
    },
    "claude_cache_creation_5_m_tokens": 0,
    "claude_cache_creation_1_h_tokens": 0
  },
  "data": [
    {
      "b64_json": "<base64-image-data>"
    }
  ]
}

​
Overview

Use this endpoint to call the Edit workflow through DeerAPI. The API reference on this page shows the request schema, response schema, authentication requirements, and runnable examples for the configured endpoint.

​
Before you start

Use the DeerAPI base URL and pass your API Key in the Authorization header: 
https://api.deerapi.com

Authorization: Bearer $DEERAPI_KEY

​
Model selection

Choose a current model ID from the live pricing page. Model availability changes over time, so avoid copying a model ID from an old project without checking the live list first.

​
Implementation notes

  • Use the OpenAPI playground for the exact request fields accepted by this endpoint.
  • Keep API Keys on the server side when you build production applications.
  • Log the request ID from failed calls so support can investigate the request.
  • Retry 429, 500, and 503 responses with exponential backoff.

Authorizations

​
Authorization
string
header
required

Use a DeerAPI API Key as a Bearer token.

Body

multipart/form-data
​
image
file
required

Source image file. Start with one PNG or JPG input for the simplest flow.

​
prompt
string
required

Edit instruction describing the change you want.

Example:

"Add a small red ribbon to the paper boat."

​
model
string
default:gpt-image-2

The image editing model to use. Choose a supported model from the Models page.

​
mask
file

Optional PNG mask. Transparent areas indicate regions that should be edited.

​
n
string
default:1

Number of edited images to return.

​
quality
enum<string>

Quality setting for models that support it.

Available options:
high,
medium,
low
​
response_format
enum<string>

Requested response container when supported by the selected model. GPT image edit models return data[].b64_json; use output_format to choose the encoded image type.

Available options:
url,
b64_json
​
output_format
string

Encoded image type for GPT image edit results returned in data[].b64_json. For example, use jpeg for a JPEG payload.

Example:

"jpeg"

​
size
string

Requested output size when supported by the selected model.

Response

200 - application/json

Edited image result.

​
created
integer
required
​
usage
object
required
​
data
object[]
required