Skip to content

API V1 · Context Images

Create context image

POST
/v1/{workspaceUrl}/projects/{projectUrl}/contextImages
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

Creates and optionally connects context images to text segments.

workspaceUrl
required
string

WorkspaceUrl

projectUrl
required
string

ProjectUrl

Media typemultipart/form-data
object
request
required

Defines how to create and connect the context image

object
connectType
required

Determines how the context image will be connected to text segments:

  • KEY_BASED: Explicitly connect to segments identified by their file path and key
  • TEXT_BASED: Connect to segments by matching the exact text content
  • IMAGE_BASED: Use OCR text detection to automatically find and connect matching text on the image
string
Allowed values: KEY_BASED TEXT_BASED IMAGE_BASED
description
required

Optional description providing context about what the image shows

string | null

Example

Screenshot of the settings page showing the language dropdown
languageCode
required

The ISO 639-1 language code (with optional regional variant) of the text segments this image relates to

string

Example

de
autoConnectSuggestions
required

When true, automatically accepts and connects OCR-detected text suggestions. Only applicable when connectType is IMAGE_BASED. When false, suggestions are created but require manual review.

boolean
segments
required

List of text segments to connect with their corresponding highlight box positions on the image. Required with at least one entry for KEY_BASED and TEXT_BASED connection types. Can be omitted or null for IMAGE_BASED when auto-connecting via OCR.

Array<object> | null

Represents a single text segment connection to a context image with its location on the image

object
filePathAndKey
required

The file path and key identifying the source text segment. Required for KEY_BASED connections. For TEXT_BASED connections, use the ‘text’ field instead.

One of:

Identifies a text segment by its source file location and unique key

object
filePath
required

The relative file path from the project root to the resource file containing the text. Example: ‘res/values/strings.xml’ or ‘i18n/en.json’

string
>= 1 characters

Example

resources/translations.json
key
required

The unique key identifier for the text within the resource file

string
>= 1 characters

Example

home.welcome_message
text
required

The actual text content of the segment to match. Used for TEXT_BASED connections or as a reference for KEY_BASED connections. This text helps translators understand the context of the segment.

string | null

Example

Hello, welcome to our application!
highlightBox
required

The rectangular region on the image that highlights where the text appears. Used to visually indicate which part of the image the text relates to. Coordinates are in pixels, with (0,0) being the top-left corner of the image.

One of:

Defines a rectangular highlight box on the context image. Used to visually indicate where specific text appears on the image. All coordinates are in pixels relative to the top-left corner (0,0) of the image.

object
left
required

The horizontal pixel coordinate of the left edge of the highlight box

number

Example

150
top
required

The vertical pixel coordinate of the top edge of the highlight box

number

Example

200
width
required

The width in pixels of the highlight box

number

Example

120
height
required

The height in pixels of the highlight box

number

Example

40
file
required
string format: binary

OK

Media type*/*

Response object containing details of a context image including its connection status and metadata

object
id
required

The unique identifier of the context image in the format ‘ci_<encrypted_id>’

string

Example

ci_18USq6822XIv-19847171
name
required

The original filename of the uploaded context image

string
description
required

Optional user-provided description of the context image

string | null

Example

Screenshot of the main dashboard showing the navigation menu
imageUrl
required

The full URL to view the context image via Cloudflare Images CDN

string
projectTitle
required

The title of the project this context image belongs to

string
languageCode
required

The ISO 639-1 language code (with optional regional variant) this context image is associated with

string

Example

en
connectedSegmentLanguagesCount
required

The count of text segments that are definitively connected to this context image

integer format: int64
segmentLanguagesSuggestionsCount
required

The count of text segment connection suggestions pending review

integer format: int64
source
required

The source channel through which the context image was uploaded

string
Allowed values: WEB API FIGMA SDK
uploadStatus
required

The current upload processing status of the image

string
Allowed values: PROCESSING DONE ERROR
textDetectionStatus
required

The current status of the OCR text detection process

string
Allowed values: SCHEDULED PROCESSING DONE ERROR
createdAt
required

The timestamp when the context image was originally uploaded

string format: date-time
updatedAt
required

The timestamp when the context image was last updated

string format: date-time