AI Marker Developer API Reference
Single-step compliance marking for images, video, audio, and text. Send media as URLs, Base64 strings, or raw multipart bytes (up to 500 MB). Results are stored for 1 hour with webhook callbacks.
Interactive Media Tools & Code Generators
Need to preview badge positions, test localized translations across 24 EU languages, or craft exact API requests? Visit our dedicated browser tools. Each tool includes a live JSON & code generator and metadata schema inspector (C2PA, Adobe XMP, ID3v2, Schema.org JSON-LD).
Image Labeling & XMP Inspector
Interactive HTML5 Canvas for testing floating corner pills, bottom disclaimer bars, caption strips, and semi-transparent watermarks.
Video Labeling & Spoken Voice Generator
Real-time video player previewing corner badges, lower thirds, and ElevenLabs spoken preambles with pre-roll extension or audio overlay (EU Recital 134).
Audio Voiceover & ID3 Tag Generator
Interactive audio player synthesizing localized spoken preamble and outro voiceovers across all 24 official EU languages.
Text Notice & Schema.org Formatter
Format statutory AI transparency notices for plain text, Markdown documents, and HTML web publications with structured metadata.
💡 How to Use the Interactive Tools for API Development:
1. Visual Customization
Pick badge style, theme, position, and EU locale in the browser tool.
2. Copy Generated JSON
Open the code drawer to copy the live JSON payload, cURL, or TypeScript snippet.
3. Call REST Endpoints
Send the JSON payload to /v1/mark/* with your Bearer API key.
1. Simple & Frictionless API
The AI Marker API provides a direct, single-step interface: send your asset in a single request and receive marked compliance outputs immediately (synchronously) or via webhooks and status polling (asynchronously).
Any Input Format
Pass media as a public URL, a Base64 string / Data URI, or multipart file bytes directly.
500 MB Size Limit
Stream high-resolution images, 4K videos, and lossless audio up to 500 MB per request.
1-Hour Retention
Input scratch files deleted immediately; marked outputs stored for 1 hour with download links.
2. Authentication
Include your API key as a Bearer token in the Authorization header:
3. Webhook Callbacks
When marking large video or audio files asynchronously, provide a webhook URL in the request payload. AI Marker will make an HTTP POST call as soon as processing completes.
{
"id": "mrk_01J98VIDEO987654321",
"status": "succeeded",
"modality": "video",
"label_preset": "lower_third.intro",
"locale": "en",
"created_at": "2026-08-18T16:00:00Z",
"completed_at": "2026-08-18T16:00:04Z"
}Mark Image (Single Step)
Mark an image with EU AI Act Article 50 compliant visual badges, embedded metadata, invisible hash watermark, and a C2PA provenance manifest when signing is configured. Accepts image URL, Base64 string, or multipart file upload up to 500 MB. Returns synchronously in HTTP 200.
Parameters
| Field | Type | Requirement | Description |
|---|---|---|---|
| image | string | Optional | URL (https://...) or Base64 string / Data-URI of the image |
| file | binary | Optional | Raw image file (for multipart/form-data requests) |
| label_preset | string | Optional | Preset: badge.standard | bar.bottom (default: badge.standard; alias standard-badge accepted). Combine with style.position_style for the other visual styles. |
| locale | string | Optional | EU language: en, de, fr, es, it, nl, pl, etc. (default: en) |
| label_family | string | Optional | generated (synthetic) | modified (altered) (default: generated) |
| wording | string | Optional | short_badge (default for images) | full_sentence. Full sentences exist for Tier-1 locales (en, de, fr, es, it, nl, pl, pt); others fall back to the badge string. |
| statement | string | Optional | Custom disclosure text overriding the catalogue wording (use with care — the catalogue strings are legally reviewed) |
| style | object | Optional | Visual style — the same vocabulary as the dashboard image tool: position_style (badge | bar | caption | border | ribbon | watermark), container_style (pill | rect | outline | none), theme (dark | light | accent), position (top-left | top-right | bottom-left | bottom-right), bar_edge (top | bottom), show_icon (bool), font_family (sans | serif | mono | display), font_weight (normal | medium | bold), text_transform (none | uppercase), size_pct (number; rendered text never below 12 px per Art. 50(5)) |
| webhook | string | Optional | Optional webhook URL to receive completion POST |
| sync | boolean | Optional | Wait synchronously for result (default: true for images) |
# 1. Via Image URL (Single Call)
curl -X POST https://markaimedia.com/v1/mark/image \
-H "Authorization: Bearer sk_live_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"image": "https://example.com/generated-photo.jpg",
"label_preset": "badge.standard",
"locale": "en"
}'
# 2. Or Direct Multipart File Upload (up to 500 MB)
curl -X POST https://markaimedia.com/v1/mark/image \
-H "Authorization: Bearer sk_live_your_api_key" \
-F "file=@/path/to/my_image.png" \
-F "label_preset=badge.standard"{
"id": "mrk_01J98IMAGE123456789",
"status": "succeeded",
"modality": "image",
"label_preset": "badge.standard",
"locale": "en",
"label_family": "generated",
"label_text": "AI-generated content",
"output": {
"url": "https://markaimedia.com/v1/markings/artifacts/art_01J98AA/content?expires=1787060400&signature=8f4a...",
"filename": "marked-mrk_01J98IMAGE123456789.png",
"content_type": "image/png",
"size_bytes": 489200,
"sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
"expires_at": "2026-08-18T17:00:00Z",
"manifest_url": "https://markaimedia.com/v1/markings/artifacts/art_01J98BB/content?expires=1787060400&signature=...",
"provenance": {
"schema": "https://markaimedia.com/schemas/disclosure/v2",
"disclosure_id": "mrk_01J98IMAGE123456789",
"claim": "ai_generated",
"digital_source_type": "http://cv.iptc.org/newscodes/digitalsourcetype/trainedAlgorithmicMedia",
"marking": {
"layers": [
"human_disclosure",
"embedded_metadata",
"hash_bound_evidence"
]
}
}
},
"urls": {
"get": "https://markaimedia.com/v1/markings/mrk_01J98IMAGE123456789",
"download": "https://markaimedia.com/v1/markings/artifacts/art_01J98AA/content?expires=1787060400&signature=8f4a..."
},
"created_at": "2026-08-18T16:00:00Z",
"completed_at": "2026-08-18T16:00:01Z"
}4. Error Handling (RFC 9457)
Standard error responses return machine-readable problem details:
| HTTP Status | Error Code | Description |
|---|---|---|
| 401 Unauthorized | invalid_api_key | Missing or invalid Bearer token. |
| 402 Payment Required | subscription_required | API access requires an active subscription. |
| 413 Payload Too Large | file_too_large | Media size exceeds the 500 MB limit. |
| 410 Gone | artifact_url_expired | Output download link exceeded the 1-hour expiration window. |
| 422 Unprocessable | invalid_label_preset | Incompatible label preset for requested modality. |
| 429 Rate Limited | rate_limited | Rate limit exceeded. Check Retry-After header. |
5. Support & Contact
Stuck on an integration, need a higher rate limit, or found something wrong in these docs? Write to us — include your request ID and endpoint so we can trace the call.