Qortex API User Guide
Submit batches of page or video URLs, poll until they finish, then fetch signals per URL. Explore authentication, endpoints, response fields and all nine signal types. No account is required to read this guide.
Quickstart
Three calls: upload a batch, wait for it to finish, then read results per URL. Examples use the video endpoints; page endpoints follow the same pattern.
- 1.
Set your key as an environment variable
shellexport QORTEX_API_KEY="paste-your-key-here" - 2.
Upload a newline-separated file of URLs
shell# urls.txt: one URL per line, up to 500 curl -X POST "https://api.qortex.ai/api/v1/video/batch/upload" \ -H "X-API-KEY: $QORTEX_API_KEY" \ -F "file=@urls.txt" - 3.
Check status until COMPLETED or ERROR
shellcurl "https://api.qortex.ai/api/v1/video/batch/BATCH_ID/status" \ -H "X-API-KEY: $QORTEX_API_KEY" - 4.
Fetch results for each submitted URL
shell# The URL must exactly match the submitted URL, path-encoded VIDEO_URL=$(python3 -c 'import urllib.parse,sys;print(urllib.parse.quote(sys.argv[1],safe=""))' "https://example.com/watch/123") curl "https://api.qortex.ai/api/v1/video/$VIDEO_URL" \ -H "X-API-KEY: $QORTEX_API_KEY"
Authentication
Every request must include your API key in the X-API-KEY header.
-H "X-API-KEY: $QORTEX_API_KEY"401; an invalid key returns 403. Keep keys out of source control and client-side code. Selecting a plan submits your key request automatically. Qortex prepares your key after prepaid payment or postpaid approval and delivers it securely off-platform; keys are never shown on this page.Batch upload
Send a multipart request with a file field named file containing up to 500 URLs, one per line.
- POST
/api/v1/page/batch/uploadSubmit web page URLs. Qortex discovers and processes videos on those pages.
- POST
/api/v1/video/batch/uploadSubmit publicly accessible video URLs to process directly.
curl -X POST "https://api.qortex.ai/api/v1/page/batch/upload" \
-H "X-API-KEY: $QORTEX_API_KEY" \
-F "file=@pages.txt"201 with an id. An invalid upload, or more than 500 URLs, returns 400. A 429 means too many requests: wait before trying again.Batch status
Poll a batch until its status is COMPLETED or ERROR, then stop.
- GET
/api/v1/{page|video}/batch/{id}/statusBatch state plus success, in-progress and failure counts. Replace {page|video} with page or video.
- GET
/api/v1/{page|video}/batch/{id}/stateLighter response containing only the batch id and overall status.
- GET
/api/v1/page/batch/{id}/poll?cursor=…Page batches only. Returns per-URL completion updates. Pass the returned cursor on the next poll to read updates not yet read with that cursor; omit it on the first call.
curl "https://api.qortex.ai/api/v1/page/batch/BATCH_ID/state" \
-H "X-API-KEY: $QORTEX_API_KEY"# First poll: omit cursor.
# Next poll: add ?cursor=THE_RETURNED_CURSOR
curl "https://api.qortex.ai/api/v1/page/batch/BATCH_ID/poll" \
-H "X-API-KEY: $QORTEX_API_KEY"Batch states: NEW (created), SUBMITTED (queued), IN_PROGRESS (processing), COMPLETED (finished) and ERROR (failed and will not finish). Stop polling at either terminal state.
Fetch results
Request results per URL. The URL must exactly match what you submitted and must be path-encoded.
- GET
/api/v1/page/{pageUrl}Signals for one page URL.
- GET
/api/v1/video/{videoUrl}Signals for one video URL.
curl "https://api.qortex.ai/api/v1/page/ENCODED_PAGE_URL" \
-H "X-API-KEY: $QORTEX_API_KEY"- Page results
- Expire 24 hours after the containing batch was created.
- Video results
- Do not expire.
202 with a full body while some signals are still PENDING. Do not treat that as final. A finished video lookup returns 200. Page lookups return 202 while processing or 204 if the page could not be retrieved.Page results include url, iabCategorization and up to 500 entries in videos. Only finished videos with a transcript are included; videos with no speech and ads are left out. Page results require your account to have submitted the URL in a batch created within the last 24 hours.
Video results include url, lookup status and a video object. Its status can be COMPLETED, PARTIAL, PENDING or ERROR. Metadata includes the video URL, resolution and duration (hh:mm:ss.fffffff, with no fractional part for whole seconds). The features array contains the available signals. Signals are the same whether the video was submitted directly or discovered on a page.
IAB category fields
Page and transcript categories include uniqueId, version, parent, name, tier1 through tier4, their corresponding tier IDs and score. Unused tiers are empty strings and unused tier IDs are null. A higher score means a stronger category match.
Signals
Which signals you receive depends on your account access.
- TRANSCRIPTION
- Text transcript of the video audio.
- SUMMARIZE
- A concise summary of the content.
- RISK_PROFILE
- 11 risk categories, each scored 0 to 5, plus an overall risk score from 0 to 100.
- SUITABILITY
- Brand suitability level (for example None, Medium or High), sensitive categories and explanation.
- SEMANTIC_ANALYSIS
- Key terms, term types and aliases.
- SENTIMENT
- Overall sentiment, emotional tone, excitement, controversy and per-entity sentiment.
- STORYBOARD_ANALYSIS
- Settings, scenes, objects, logos and on-screen text.
- CONTENT_OVERVIEW
- Content characteristics, including how scripted the video is on a 1 to 10 scale.
- ADVERTISER_OPPORTUNITIES
- Relevant IAB categories, product and service types, and aligned brands.
- Metadata
- Video duration and resolution.
Each feature has a type and status. Signal states are COMPLETED, PENDING, ERROR, SKIPPED and NOT_REQUESTED. A signal’s result is only included when its status is COMPLETED; transcription uses its own fields below. Paths are relative to a feature entry.
TRANSCRIPTION fields
- transcript
- Speech transcript. A video with no transcript has no TRANSCRIPTION entry.
- iabCategorization
- IAB 2.2 categories detected from the transcript.
- iabStatus
- Processing status of the transcript’s IAB categorization.
SUMMARIZE fields
- result.summary
- A short summary of the video’s content.
RISK_PROFILE fields
- result.overallRiskScore
- Overall risk score, from 0 to 100.
- result.categories[].category
- ADULT_CONTENT, VIOLENCE, HATE_SPEECH, DRUGS, WEAPONS, CRIME, PROFANITY, ALCOHOL_TOBACCO, GAMBLING, POLITICAL_EXTREMISM or NEGATIVE_NEWS.
- result.categories[].score
- Category risk score, from 0 to 5.
- result.categories[].reasoning
- Reason for the score; empty when the score is 0.
SUITABILITY fields
- result.level
- Brand suitability level, for example None, Medium or High.
- result.categories
- Array of sensitive content categories that apply.
- result.explanation
- Why the suitability level was assigned.
SEMANTIC_ANALYSIS fields
- result.terms[].term
- Key term from the video.
- result.terms[].type
- Kind of term, such as topic, person, organization, place, object, event, concept or theme.
- result.terms[].aliases
- Array of other names or phrases referring to the term.
SENTIMENT fields
- result.overallSentiment
- Overall sentiment, for example positive or mixed.
- result.overallSentimentExplanation
- Why the overall sentiment was assigned.
- result.signals.sentiment
- Short sentiment description.
- result.signals.emotionalTone
- Emotional tone of the video.
- result.signals.excitementLevel
- Excitement level: low, medium or high.
- result.signals.controversy
- How controversial the content is, for example low.
- result.entities[]
- Sentiment toward each person, organization, product or topic: name, type, sentiment, emotionalTone, excitementLevel and controversy.
STORYBOARD_ANALYSIS fields
- result.analysis.overall_scene_and_setting
- Settings and locations shown in the video.
- result.analysis.overall_narrative_tone_feeling
- What happens and the overall tone.
- result.analysis.overall_genre
- Genre, such as news or event coverage.
- result.analysis.overall_content_type
- Footage type, such as live_action or mixed_media.
- result.analysis.overall_scenes
- Comma-separated scenes.
- result.analysis.overall_objects
- Comma-separated people and objects seen on screen.
- result.analysis.overall_logos
- Comma-separated logos; unidentified logos include a short description.
- result.analysis.overall_texts
- Comma-separated on-screen text.
CONTENT_OVERVIEW fields
- result.overall_theme
- Main theme.
- result.primary_subject
- Main subject.
- result.description
- Short description.
- result.inferred_title
- Likely title.
- result.inferred_genre
- Likely genre.
- result.inferred_origin_country
- Likely country of origin.
- result.inferred_year
- Likely year of production (integer).
- result.language
- Language code, for example en.
- result.content_type
- Kind of content, such as a celebrity interview or advertisement.
- result.scripted_score
- Integer from 1 to 10; higher means more scripted.
- result.tone
- Tone of the video.
- result.keywords
- Array of descriptive keywords.
ADVERTISER_OPPORTUNITIES fields
- result.iab_categories
- Array of relevant IAB Content Taxonomy 3.1 category names. Page and transcript categories use IAB 2.2 instead.
- result.advertising_opportunities
- Array of product and service types suited to advertising alongside the video.
- result.aligned_brands
- Array of brands whose advertising would align with the video.
Status codes and errors
A 202 is not a final answer. Everything else tells you what to do next.
- 200Results readyVideo processing has finished; inspect video and individual signal states.Video processing has finished; inspect video and individual signal states.
- 201Batch createdUpload succeeded. Save the returned id to check progress.Upload succeeded. Save the returned id to check progress.
- 202PendingAccepted but not final yet. Keep polling at a sensible interval.Accepted but not final yet. Keep polling at a sensible interval.
- 204No contentThe page could not be retrieved. Not retryable as-is.The page could not be retrieved. Not retryable as-is.
- 400Bad requestUpload invalid, or the file contains more than 500 URLs.Upload invalid, or the file contains more than 500 URLs.
- 401UnauthorizedThe X-API-KEY header is missing.The X-API-KEY header is missing.
- 403ForbiddenThe API key is invalid.The API key is invalid.
- 404Not foundNo result for that URL, or a page result has expired.No result for that URL, or a page result has expired.
- 429Rate limitedToo many requests. Back off and retry later.Too many requests. Back off and retry later.