Recording marking

Proposed marks and feedback for a spoken or filmed answer, from its transcript, still frames and delivery.

Price30 credits (£3.00) per submission
Typical time60 s to 15 min
Scopemarking:write
Runs asA background job

Try it

Run recording marking in the sandbox

No key and nothing to pay. The sandbox returns a realistic example in a couple of seconds; no AI runs and no data is kept.

Queued202 and a job id, straight away
ProcessingPoll, stream or wait for a webhook
SucceededResult and files on the job

Every AI request runs as a background job, so nothing times out.

Upload the recording with POST /v1/files first and pass its file_id. EduMark transcribes the speech, samples still frames after scene changes and measures pauses and pace, then marks each question against your guide. The AI cannot hear pronunciation or sound quality, or see motion between frames: anything that depends on those comes back with proposed_marks: null and a reason. The result is a proposal for a named person to review: official_result is always false and requires_review always true. The transcript is included.

Requires marking:write. Costs 30 credits per submission. Send a unique Idempotency-Key; reuse it with the identical body when retrying. Returns 202 with a job: poll GET /jobs/{job_id}, stream GET /jobs/{job_id}/events, or use a signed webhook.

Recording marking

POST/v1/marking/recordings

Scope marking:write

Headers

Recording marking: headers
Field	Details
`Idempotency-Key`	stringRequiredA unique key per new operation; reuse it with the identical body when retrying.
`EduMark-Version`	enumAPI version. Defaults to the latest.One of `2026-10-21`

Request body

Recording marking: request body
Field	Details
`recording`	FileReferenceRequiredAn uploaded recording (POST /v1/files): MP4, MOV, WEBM, M4A, MP3, WAV or OGG, up to 500 MiB and 60 minutes.
`file_id`recording.file_id	stringRequiredThe id returned by POST /v1/files, after POST /v1/files/{id}/complete reported ready.Pattern `^file_[a-f0-9]{32}$`
`questions`	array of MarkedQuestionRequiredWhat the recording answers. Each is marked against the whole recording.1 to 20 items
`id`questions[].id	stringRequiredUp to 100 charactersPattern `^[A-Za-z0-9_.-]+$`
`question_text`questions[].question_text	stringRequiredUp to 12,000 characters
`max_marks`questions[].max_marks	integerRequired1 to 1,000
`marking_guide`questions[].marking_guide	string, optionalWhat a good answer contains and how marks are awarded. Draft one with POST /v1/marking/guides.Up to 16,000 characters
`criteria`questions[].criteria	array of CriterionOptional rubric. Criterion maxima must add up to max_marks.Up to 12 items
`id`questions[].criteria[].id	stringRequiredUp to 60 charactersPattern `^[A-Za-z0-9_.-]+$`
`title`questions[].criteria[].title	stringRequiredUp to 300 characters
`description`questions[].criteria[].description	string, optionalUp to 4,000 characters
`max_marks`questions[].criteria[].max_marks	integerRequired1 to 1,000
`context_text`	string, optionalAssignment-wide marking rules or the task brief.Up to 60,000 characters
`feedback`	FeedbackPreferences, optionalHow feedback is written. Each field is optional; unset fields use your team's Assessment & feedback settings.
`tone`feedback.tone	enum, optionalprofessional_balanced, supportive_developmental, direct_concise or custom.One of `professional_balanced`, `supportive_developmental`, `direct_concise`, `custom`
`custom_tone`feedback.custom_tone	string, optionalDescribes the tone when tone is custom.Up to 500 characters
`length`feedback.length	enum, optionalbrief, standard or detailed.One of `brief`, `standard`, `detailed`
`address`feedback.address	enum, optionaldirect ('you') or third_person ('the learner').One of `direct`, `third_person`
`instructions`feedback.instructions	string, optionalExtra writing instructions. They shape wording only, never marks.Up to 2,000 characters

Responses

Status	Meaning
202	Successful Response
400	Request rejected. Inspect error.code and request_id; failed work is not billed.
401	Request rejected. Inspect error.code and request_id; failed work is not billed.
402	Request rejected. Inspect error.code and request_id; failed work is not billed.
403	Request rejected. Inspect error.code and request_id; failed work is not billed.
404	Request rejected. Inspect error.code and request_id; failed work is not billed.
409	Request rejected. Inspect error.code and request_id; failed work is not billed.
410	Request rejected. Inspect error.code and request_id; failed work is not billed.
413	Request rejected. Inspect error.code and request_id; failed work is not billed.
415	Request rejected. Inspect error.code and request_id; failed work is not billed.
422	Validation Error
429	Request rejected. Inspect error.code and request_id; failed work is not billed.
503	Request rejected. Inspect error.code and request_id; failed work is not billed.

Request

curl -X POST 'https://api.edumark.ai/v1/marking/recordings' \
  -H "Authorization: Bearer $EDUMARK_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "recording": {
    "file_id": "file_3f2a9c0b5d7e4a1b8c6d2e0f9a8b7c6d"
  },
  "questions": [
    {
      "id": "q1",
      "question_text": "Give a two-minute explanation of the water cycle.",
      "max_marks": 10,
      "marking_guide": "Up to 6 marks for naming and correctly ordering evaporation, condensation and precipitation; up to 4 marks for a clear real-world example."
    }
  ],
  "feedback": {
    "tone": "supportive_developmental",
    "length": "standard",
    "address": "direct"
  }
}'

# Then poll until the job finishes (wait poll_after_seconds between calls)
curl 'https://api.edumark.ai/v1/jobs/job_01JB7Q8M4X2V9R' \
  -H "Authorization: Bearer $EDUMARK_API_KEY"

Queued202 and a job id, straight away
ProcessingPoll, stream or wait for a webhook
SucceededResult and files on the job

Every AI request runs as a background job, so nothing times out.

Response 202JSON

{
  "id": "job_0123456789abcdef0123456789abcdef01234567",
  "product": "media_marking",
  "status": "queued",
  "poll_after_seconds": 2,
  "credits": 30,
  "result_available": false
}

Finished job: resultJSON

{
  "status": "needs_review",
  "reason": null,
  "official_result": false,
  "requires_review": true,
  "questions": [
    {
      "question_id": "q1",
      "label": "q1",
      "status": "needs_review",
      "proposed_marks": 7,
      "max_marks": 10,
      "feedback": "You explain the water cycle in a clear order and use the right terms. Slow down when you describe condensation and give one everyday example to make it stick.",
      "rationale": "Covers evaporation, condensation and precipitation accurately; no real-world example is given.",
      "criteria": [
        {
          "ref": "overall",
          "band": "secure",
          "marks": 7
        }
      ],
      "evidence": [
        {
          "kind": "quote",
          "quote": "the sun heats the water and it rises as vapour",
          "location": {
            "start_ms": 4200,
            "end_ms": 9800
          }
        },
        {
          "kind": "visual",
          "label": "Submitted recording.mp4 at 0:42",
          "criterion_ref": "overall",
          "observation": "A labelled diagram of the water cycle is held up to the camera."
        }
      ],
      "confidence": 0.78,
      "reason": null,
      "inferred_fields": [],
      "attention": [],
      "comments": []
    }
  ],
  "totals": {
    "proposed_marks": 7,
    "max_marks": 10,
    "complete": true
  },
  "recording": {
    "kind": "video",
    "duration_seconds": 94,
    "transcript": {
      "state": "ready",
      "language": "english",
      "word_timing": "provider",
      "truncated": false,
      "segments": [
        {
          "start_ms": 0,
          "end_ms": 4100,
          "text": "Today I'm going to explain the water cycle."
        },
        {
          "start_ms": 4200,
          "end_ms": 9800,
          "text": "First, the sun heats the water and it rises as vapour."
        }
      ]
    },
    "delivery": {
      "sounding_ms": 81000,
      "word_count": 212,
      "words_per_minute": 157,
      "pause_count": 6
    },
    "frames_sampled": 18
  },
  "warnings": [],
  "feedback_style": {
    "tone": "supportive_developmental",
    "length": "standard",
    "address": "direct",
    "instructions_applied": false,
    "source": "request"
  },
  "provenance": {
    "engine": "shared_media_marking",
    "sandbox": true
  }
}