> ## Documentation Index > Fetch the complete documentation index at: https://docs.wesog.com/llms.txt > Use this file to discover all available pages before exploring further. # Tag an image > Analyze a single image and return visual metadata. The request must provide exactly one input source: either `image` or `image_url`. This endpoint does not accept batches or multiple files in the same call. ## OpenAPI ````yaml https://api.wesog.com/openapi.json post /tag/image openapi: 3.1.0 info: title: Wesog API description: Wesog AI services for media providers version: 1.0.0 servers: - url: https://api.wesog.com description: Production server - url: https://v2.api.wesog.com description: Production server (v2) security: [] paths: /tag/image: post: tags: - Wesog Tag summary: Tag an image description: >- Analyze a single image and return visual metadata. The request must provide exactly one input source: either `image` or `image_url`. This endpoint does not accept batches or multiple files in the same call. operationId: tag_image_tag_image_post requestBody: content: multipart/form-data: schema: $ref: '#/components/schemas/Body_tag_image_tag_image_post' oneOf: - required: - image - required: - image_url properties: image: type: string format: binary description: >- Binary image file to analyze. Use this or `image_url`, but not both. image_url: type: string format: uri description: >- Publicly reachable image URL to analyze instead of uploading a file. lang: type: string description: >- Language used for language-dependent outputs such as caption or keywords. default: en example: en mode: type: string description: >- Tagging profile. Currently the default documented mode is `editorial`. default: editorial example: editorial date: type: string description: >- Optional image context date, typically in ISO format `YYYY-MM-DD`. Helps downstream people and caption enrichment. default: '' example: '2025-10-16' event: type: string description: >- Optional event name associated with the image, used as context for enriched outputs. default: '' example: Carabao Cup winners presentation city: type: string description: Optional city associated with the image context. default: '' example: London country: type: string description: Optional country associated with the image context. default: '' example: United Kingdom caption: type: boolean description: >- When `true`, include an AI-generated caption in the response. default: false keywords: type: boolean description: When `true`, include generated keyword tags in the response. default: false ocr: type: boolean description: When `true`, include OCR text extracted from the image. default: false colors: type: boolean description: >- When `true`, include dominant colors and black-and-white detection. default: false type: object required: true responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/TagImageResponse' '400': description: Invalid input combination. content: application/json: schema: $ref: '#/components/schemas/TagErrorResponse' '422': description: Validation error in multipart form fields. security: - APIKeyHeader: [] components: schemas: Body_tag_image_tag_image_post: properties: image: anyOf: - type: string contentMediaType: application/octet-stream - type: 'null' title: Image description: Binary image file to analyze. Mutually exclusive with `image_url`. image_url: anyOf: - type: string - type: 'null' title: Image Url description: Remote image URL to analyze. Mutually exclusive with `image`. lang: type: string title: Lang description: >- Language used for language-dependent outputs such as generated caption and keywords. default: en mode: type: string title: Mode description: >- Tagging profile to apply. The endpoint currently uses `editorial` as default mode. default: editorial date: type: string title: Date description: >- Optional contextual date for the image, ideally in ISO `YYYY-MM-DD` format. default: '' event: type: string title: Event description: Optional contextual event name associated with the image. default: '' city: type: string title: City description: Optional contextual city associated with the image. default: '' country: type: string title: Country description: Optional contextual country associated with the image. default: '' caption: type: boolean title: Caption description: If `true`, the response includes an AI-generated caption. default: false keywords: type: boolean title: Keywords description: If `true`, the response includes generated keyword tags. default: false ocr: type: boolean title: Ocr description: If `true`, the response includes OCR text extracted from the image. default: false colors: type: boolean title: Colors description: >- If `true`, the response includes dominant colors and black-and-white detection. default: false type: object title: Body_tag_image_tag_image_post TagImageResponse: properties: height: anyOf: - type: integer - type: 'null' title: Height description: Image height in pixels. width: anyOf: - type: integer - type: 'null' title: Width description: Image width in pixels. ratio: anyOf: - type: number - type: 'null' title: Ratio description: Aspect ratio of the image. orient: anyOf: - type: string - type: 'null' title: Orient description: Image orientation. n_faces: anyOf: - type: integer - type: 'null' title: N Faces description: Number of detected faces. shot: anyOf: - type: string - type: 'null' title: Shot description: Predicted shot type. illumination: anyOf: - type: string - type: 'null' title: Illumination description: Predicted lighting type. shape: anyOf: - type: string - items: type: integer type: array - items: type: string type: array - type: 'null' title: Shape description: Predicted image shape/style or raw shape dimensions. date: anyOf: - type: string format: date - type: string - type: 'null' title: Date description: Image date when available. people: anyOf: - items: $ref: '#/components/schemas/TagPersonResponse' type: array - type: 'null' title: People description: Detected people metadata. photo_or_illus: anyOf: - type: string - type: 'null' title: Photo Or Illus description: Whether the input is a photo or illustration. type_of_photo: anyOf: - type: string - type: 'null' title: Type Of Photo description: Predicted photo subtype. type_of_illus: anyOf: - type: string - type: 'null' title: Type Of Illus description: Predicted illustration subtype. categories: anyOf: - items: type: string type: array - type: 'null' title: Categories description: General image categories. colors: anyOf: - items: type: string type: array - type: 'null' title: Colors description: Representative image colors when requested. bw: anyOf: - type: boolean - type: 'null' title: Bw description: Whether the image is black and white. caption: anyOf: - type: string - type: 'null' title: Caption description: Generated caption when requested. keywords: anyOf: - items: type: string type: array - type: 'null' title: Keywords description: Generated keywords when requested. ocr: anyOf: - type: string - type: 'null' title: Ocr description: Extracted OCR text when requested. additionalProperties: true type: object title: TagImageResponse TagErrorResponse: properties: error: type: string title: Error description: Human-readable validation error. type: object required: - error title: TagErrorResponse TagPersonResponse: properties: face_box_as_dict: anyOf: - additionalProperties: type: number type: object - type: 'null' title: Face Box As Dict description: Face bounding box coordinates. celeb_name: anyOf: - type: string - type: 'null' title: Celeb Name description: Matched celebrity name if available. gender: anyOf: - type: string - type: 'null' title: Gender description: Predicted gender. nationality: anyOf: - type: string - items: type: string type: array - type: 'null' title: Nationality description: Detected or linked nationality. occupation: anyOf: - type: string - items: type: string type: array - type: 'null' title: Occupation description: Detected or linked occupation. race: anyOf: - type: string - type: 'null' title: Race description: Predicted ethnicity/race label. age_group: anyOf: - type: string - type: 'null' title: Age Group description: Predicted age group. current_age: anyOf: - type: integer - type: 'null' title: Current Age description: Estimated or linked age. face_expression: anyOf: - type: string - type: 'null' title: Face Expression description: Detected face expression. date_birth: anyOf: - type: string format: date - type: string - type: 'null' title: Date Birth description: Birth date when available. date_death: anyOf: - type: string format: date - type: string - type: 'null' title: Date Death description: Death date when available. wesog_id: anyOf: - type: string - type: 'null' title: Wesog Id description: Internal Wesog identifier. additionalProperties: true type: object title: TagPersonResponse securitySchemes: APIKeyHeader: type: apiKey in: header name: API-Key ````