# Create context image

`POST https://api.lingohub.com/v1/{workspaceUrl}/projects/{projectUrl}/contextImages`

LingoHub API V1 · [Context Images](https://developers.lingohub.com/reference/v1/operations/tags/context-images.md) · operation `v1ContextImagesCreateContextImage`

Creates and optionally connects context images to text segments.

## Parameters

| Parameter | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `workspaceUrl` | path | yes | string | workspaceUrl |
| `projectUrl` | path | yes | string | projectUrl |

## Example request

```sh
curl --request POST \
  --url https://api.lingohub.com/v1/WORKSPACE_URL/projects/PROJECT_URL/contextImages \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: multipart/form-data' \
  --form file=@translations.json
```

## Responses

- `200`: OK

## OpenAPI definition

The complete definition of this operation, with every schema it references:

````json
{
  "openapi": "3.1.0",
  "info": {
    "title": "LingoHub API V1",
    "version": "1"
  },
  "servers": [
    {
      "url": "https://api.lingohub.com",
      "description": "Generated server url"
    }
  ],
  "tags": [
    {
      "name": "Context Images",
      "description": "Endpoints for the operations that can be performed on the context images"
    }
  ],
  "paths": {
    "/v1/{workspaceUrl}/projects/{projectUrl}/contextImages": {
      "post": {
        "tags": [
          "Context Images"
        ],
        "summary": "Create context image",
        "description": "Creates and optionally connects context images to text segments.",
        "operationId": "v1ContextImagesCreateContextImage",
        "parameters": [
          {
            "name": "workspaceUrl",
            "in": "path",
            "description": "workspaceUrl",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "projectUrl",
            "in": "path",
            "description": "projectUrl",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "properties": {
                  "request": {
                    "$ref": "#/components/schemas/V1CreateContextImageRequest"
                  },
                  "file": {
                    "type": "string",
                    "format": "binary"
                  }
                },
                "required": [
                  "file",
                  "request"
                ]
              },
              "encoding": {
                "request": {
                  "contentType": "application/json"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "*/*": {
                "schema": {
                  "$ref": "#/components/schemas/V1ContextImageResponse"
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    }
  },
  "components": {
    "schemas": {
      "V1CreateContextImageRequest": {
        "type": "object",
        "description": "Defines how to create and connect the context image",
        "properties": {
          "connectType": {
            "$ref": "#/components/schemas/V1ConnectType",
            "description": "Determines how the context image will be connected to text segments:\n- **KEY_BASED**: Explicitly connect to segments identified by their file path and key\n- **TEXT_BASED**: Connect to segments by matching the exact text content\n- **IMAGE_BASED**: Use OCR text detection to automatically find and connect matching text on the image"
          },
          "description": {
            "type": [
              "string",
              "null"
            ],
            "description": "Optional description providing context about what the image shows",
            "example": "Screenshot of the settings page showing the language dropdown"
          },
          "languageCode": {
            "type": "string",
            "description": "The ISO 639-1 language code (with optional regional variant) of the text segments this image relates to",
            "example": "de"
          },
          "autoConnectSuggestions": {
            "type": "boolean",
            "description": "When true, automatically accepts and connects OCR-detected text suggestions.\nOnly applicable when connectType is IMAGE_BASED.\nWhen false, suggestions are created but require manual review."
          },
          "segments": {
            "type": [
              "array",
              "null"
            ],
            "description": "List of text segments to connect with their corresponding highlight box positions on the image.\nRequired with at least one entry for KEY_BASED and TEXT_BASED connection types.\nCan be omitted or null for IMAGE_BASED when auto-connecting via OCR.",
            "items": {
              "$ref": "#/components/schemas/V1ConnectSegment"
            }
          }
        },
        "required": [
          "autoConnectSuggestions",
          "connectType",
          "description",
          "languageCode",
          "segments"
        ]
      },
      "V1ConnectType": {
        "type": "string",
        "description": "Enumeration of connection types for linking context images to text segments",
        "enum": [
          "KEY_BASED",
          "TEXT_BASED",
          "IMAGE_BASED"
        ]
      },
      "V1ConnectSegment": {
        "type": "object",
        "description": "Represents a single text segment connection to a context image with its location on the image",
        "properties": {
          "filePathAndKey": {
            "description": "The file path and key identifying the source text segment.\nRequired for KEY_BASED connections.\nFor TEXT_BASED connections, use the 'text' field instead.",
            "oneOf": [
              {
                "$ref": "#/components/schemas/V1FilePathAndKey"
              },
              {
                "type": "null"
              }
            ]
          },
          "text": {
            "type": [
              "string",
              "null"
            ],
            "description": "The actual text content of the segment to match.\nUsed for TEXT_BASED connections or as a reference for KEY_BASED connections.\nThis text helps translators understand the context of the segment.",
            "example": "Hello, welcome to our application!"
          },
          "highlightBox": {
            "description": "The rectangular region on the image that highlights where the text appears.\nUsed to visually indicate which part of the image the text relates to.\nCoordinates are in pixels, with (0,0) being the top-left corner of the image.",
            "oneOf": [
              {
                "$ref": "#/components/schemas/V1HighlightBoxTransfer"
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [
          "filePathAndKey",
          "highlightBox",
          "text"
        ]
      },
      "V1FilePathAndKey": {
        "type": "object",
        "description": "Identifies a text segment by its source file location and unique key",
        "properties": {
          "filePath": {
            "type": "string",
            "description": "The relative file path from the project root to the resource file containing the text.\nExample: 'res/values/strings.xml' or 'i18n/en.json'",
            "example": "resources/translations.json",
            "minLength": 1
          },
          "key": {
            "type": "string",
            "description": "The unique key identifier for the text within the resource file",
            "example": "home.welcome_message",
            "minLength": 1
          }
        },
        "required": [
          "filePath",
          "key"
        ]
      },
      "V1HighlightBoxTransfer": {
        "type": "object",
        "description": "Defines a rectangular highlight box on the context image.\nUsed to visually indicate where specific text appears on the image.\nAll coordinates are in pixels relative to the top-left corner (0,0) of the image.",
        "properties": {
          "left": {
            "type": "number",
            "description": "The horizontal pixel coordinate of the left edge of the highlight box",
            "example": 150
          },
          "top": {
            "type": "number",
            "description": "The vertical pixel coordinate of the top edge of the highlight box",
            "example": 200
          },
          "width": {
            "type": "number",
            "description": "The width in pixels of the highlight box",
            "example": 120
          },
          "height": {
            "type": "number",
            "description": "The height in pixels of the highlight box",
            "example": 40
          }
        },
        "required": [
          "height",
          "left",
          "top",
          "width"
        ]
      },
      "V1ContextImageResponse": {
        "type": "object",
        "description": "Response object containing details of a context image including its connection status and metadata",
        "properties": {
          "id": {
            "type": "string",
            "description": "The unique identifier of the context image in the format 'ci_<encrypted_id>'",
            "example": "ci_18USq6822XIv-19847171"
          },
          "name": {
            "type": "string",
            "description": "The original filename of the uploaded context image"
          },
          "description": {
            "type": [
              "string",
              "null"
            ],
            "description": "Optional user-provided description of the context image",
            "example": "Screenshot of the main dashboard showing the navigation menu"
          },
          "imageUrl": {
            "type": "string",
            "description": "The full URL to view the context image via Cloudflare Images CDN"
          },
          "projectTitle": {
            "type": "string",
            "description": "The title of the project this context image belongs to"
          },
          "languageCode": {
            "type": "string",
            "description": "The ISO 639-1 language code (with optional regional variant) this context image is associated with",
            "example": "en"
          },
          "connectedSegmentLanguagesCount": {
            "type": "integer",
            "format": "int64",
            "description": "The count of text segments that are definitively connected to this context image"
          },
          "segmentLanguagesSuggestionsCount": {
            "type": "integer",
            "format": "int64",
            "description": "The count of text segment connection suggestions pending review"
          },
          "source": {
            "$ref": "#/components/schemas/ContextSource",
            "description": "The source channel through which the context image was uploaded"
          },
          "uploadStatus": {
            "$ref": "#/components/schemas/UploadStatus",
            "description": "The current upload processing status of the image"
          },
          "textDetectionStatus": {
            "$ref": "#/components/schemas/TextDetectionStatus",
            "description": "The current status of the OCR text detection process"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "description": "The timestamp when the context image was originally uploaded"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time",
            "description": "The timestamp when the context image was last updated"
          }
        },
        "required": [
          "connectedSegmentLanguagesCount",
          "createdAt",
          "description",
          "id",
          "imageUrl",
          "languageCode",
          "name",
          "projectTitle",
          "segmentLanguagesSuggestionsCount",
          "source",
          "textDetectionStatus",
          "updatedAt",
          "uploadStatus"
        ]
      },
      "ContextSource": {
        "type": "string",
        "enum": [
          "WEB",
          "API",
          "FIGMA",
          "SDK"
        ]
      },
      "UploadStatus": {
        "type": "string",
        "enum": [
          "PROCESSING",
          "DONE",
          "ERROR"
        ]
      },
      "TextDetectionStatus": {
        "type": "string",
        "enum": [
          "SCHEDULED",
          "PROCESSING",
          "DONE",
          "ERROR"
        ]
      }
    },
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "description": "API key authentication. Create API keys in your LingoHub workspace settings. Keys use the `lh-api_` prefix. Pass the full key as the Bearer token.",
        "scheme": "bearer"
      }
    }
  }
}
````
