LinkModel API Documentation

Upload a local video, wait for Gemini file processing, and reference the resulting URI in a native generateContent request.

This file workflow is only available for Google Gemini models that support native fileData input. Uploaded file URIs cannot be used with OpenAI, Anthropic, /chat/completions, /messages, image-generation, or video-generation endpoints.

Before you begin

You need:

A LinkModel API key with access to a compatible Gemini model, such as gemini-3.1-flash-lite.
A local video file. The examples below use sample.mp4 with MIME type video/mp4.
curl and jq.

Set your API key without placing it directly in shell history:

export LINKMODEL_API_KEY="<YOUR_API_KEY>"
export VIDEO_PATH="/path/to/your/video.mp4"
export UPLOAD_FILENAME="video-test.mp4"

The file lifecycle uses https://api.linkmodel.ai/v1. The Gemini-native request uses https://api.linkmodel.ai/v1beta.

Use a portable ASCII value for UPLOAD_FILENAME, containing only letters, numbers, dots, hyphens, or underscores. The local path may contain spaces or non-ASCII characters, but the upload filename becomes part of the Gemini file URI and should not.

1. Calculate file metadata

The upload session requires the exact file size and a hexadecimal MD5 checksum.

# Linux
SIZE_BYTES=$(stat -c%s "$VIDEO_PATH")
MD5_HEX=$(md5sum "$VIDEO_PATH" | awk '{print $1}')

# macOS: use these two commands instead
# SIZE_BYTES=$(stat -f%z "$VIDEO_PATH")
# MD5_HEX=$(md5 -q "$VIDEO_PATH")

printf 'size=%s md5=%s\n' "$SIZE_BYTES" "$MD5_HEX"

2. Create a Gemini upload session

curl --fail-with-body --silent --show-error \
  --request POST \
  --url "https://api.linkmodel.ai/v1/files/upload-sessions" \
  --header "Authorization: Bearer $LINKMODEL_API_KEY" \
  --header "Content-Type: application/json" \
  --data "{
    \"filename\": \"$UPLOAD_FILENAME\",
    \"mime_type\": \"video/mp4\",
    \"size_bytes\": $SIZE_BYTES,
    \"md5sum\": \"$MD5_HEX\",
    \"purpose\": \"vision\"
  }" \
  --output upload-session.json

A successful response contains a file identifier and a short-lived upload instruction:

{
  "code": 0,
  "data": {
    "file_id": "file_example123",
    "status": "pending_upload",
    "expires_at": 1783666435,
    "upload": {
      "url": "https://example-object-storage.invalid/...",
      "method": "PUT",
      "headers": {
        "Content-Type": "video/mp4",
        "Content-MD5": "base64-md5-from-the-server"
      },
      "expires_at": 1783659235
    }
  }
}

Extract the values needed by the next steps:

FILE_ID=$(jq -r '.data.file_id' upload-session.json)
UPLOAD_URL=$(jq -r '.data.upload.url' upload-session.json)
jq -r '.data.upload.headers | to_entries[] | "\(.key): \(.value)"' \
  upload-session.json > upload-headers.txt

md5sum in the session request is hexadecimal. Any Content-MD5 upload header is the Base64 value returned by the server. Do not convert or interchange them. Header names are case-insensitive, so avoid extracting them by an assumed capitalization.

3. Upload the video bytes

Send the file directly to the returned pre-signed URL. Use the returned upload headers and values unchanged.

curl --fail-with-body \
  --request PUT \
  --url "$UPLOAD_URL" \
  --header "@upload-headers.txt" \
  --upload-file "$VIDEO_PATH"

The object-storage response is normally HTTP 200 with an empty or very small body. The pre-signed URL and its headers are credentials for this upload; do not log or share them.

4. Complete the upload

After the direct upload succeeds, notify LinkModel so processing can begin:

curl --fail-with-body \
  --request POST \
  --url "https://api.linkmodel.ai/v1/files/$FILE_ID/complete" \
  --header "Authorization: Bearer $LINKMODEL_API_KEY" \
  --header "Content-Type: application/json"

An HTTP 202 response means processing has started. It does not mean the file is ready for Gemini yet.

5. Wait until the file is active

Poll the file resource until it becomes active or reaches the timeout:

for attempt in $(seq 1 60); do
  RESPONSE=$(curl --fail-with-body --silent --show-error \
    --url "https://api.linkmodel.ai/v1/files/$FILE_ID" \
    --header "Authorization: Bearer $LINKMODEL_API_KEY") || exit 1

  STATUS=$(printf '%s' "$RESPONSE" | jq -r '.data.status')
  printf 'attempt=%s status=%s\n' "$attempt" "$STATUS"

  case "$STATUS" in
    active)
      FILE_URI=$(printf '%s' "$RESPONSE" | jq -r '.data.uri')
      break
      ;;
    failed|error)
      printf 'File processing failed: %s\n' "$RESPONSE" >&2
      exit 1
      ;;
  esac

  sleep 10
done

test -n "${FILE_URI:-}" || { echo "Timed out waiting for the file" >&2; exit 1; }

The active resource includes a Gemini file URI:

{
  "code": 0,
  "data": {
    "file_id": "file_example123",
    "status": "active",
    "filename": "sample.mp4",
    "mime_type": "video/mp4",
    "bytes": 35077,
    "uri": "gs://managed-gemini-files/.../file_example123-sample.mp4",
    "created_at": 1783580035,
    "expires_at": 1783666435
  }
}

Keep the gs:// URI unchanged. It is an account-scoped Gemini reference, not a public download URL.

6. Analyze the video with Gemini

Reference the active file URI using fileData.fileUri and include the matching MIME type:

curl --fail-with-body \
  --request POST \
  --url "https://api.linkmodel.ai/v1beta/models/gemini-3.1-flash-lite:generateContent" \
  --header "Authorization: Bearer $LINKMODEL_API_KEY" \
  --header "Content-Type: application/json" \
  --data "{
    \"contents\": [{
      \"role\": \"user\",
      \"parts\": [
        {
          \"fileData\": {
            \"fileUri\": \"$FILE_URI\",
            \"mimeType\": \"video/mp4\"
          }
        },
        {\"text\": \"Describe the important events in this video.\"}
      ]
    }]
  }"

A successful response uses Gemini’s native response format rather than LinkModel’s code, data, and msg business envelope:

{
  "candidates": [
    {
      "content": {
        "parts": [{ "text": "The video shows..." }],
        "role": "model"
      },
      "finishReason": "STOP"
    }
  ],
  "modelVersion": "gemini-3.1-flash-lite",
  "usageMetadata": {
    "promptTokenCount": 140,
    "candidatesTokenCount": 183,
    "totalTokenCount": 323
  }
}

GenerateContent errors, including gateway rejections, use Gemini’s error envelope with an HTTP error status:

{
  "error": {
    "code": 400,
    "status": "INVALID_ARGUMENT",
    "message": "Invalid request parameter"
  }
}

Capture request identifiers from response headers or the body when present. See Error handling for status codes and retry guidance. The file upload and polling endpoints retain their own response schemas.

7. Delete the file

Delete the uploaded file when you no longer need it:

curl --fail-with-body \
  --request DELETE \
  --url "https://api.linkmodel.ai/v1/files/$FILE_ID" \
  --header "Authorization: Bearer $LINKMODEL_API_KEY"

Complete runnable example

The following script runs the complete lifecycle and attempts to delete the remote file even when a later step fails. It uses gemini-3.1-flash-lite and keeps temporary response files outside your project directory.

#!/usr/bin/env bash
set -euo pipefail

: "${LINKMODEL_API_KEY:?Set LINKMODEL_API_KEY first}"
: "${VIDEO_PATH:?Set VIDEO_PATH first}"

MODEL="${GEMINI_VIDEO_MODEL:-gemini-3.1-flash-lite}"
UPLOAD_FILENAME="${UPLOAD_FILENAME:-video-test.mp4}"
API_BASE="https://api.linkmodel.ai"
WORK_DIR=$(mktemp -d)
FILE_ID=""

cleanup() {
  if [ -n "$FILE_ID" ]; then
    curl --silent --show-error --request DELETE \
      --url "$API_BASE/v1/files/$FILE_ID" \
      --header "Authorization: Bearer $LINKMODEL_API_KEY" \
      --output /dev/null || true
  fi
  rm -rf -- "$WORK_DIR"
}
trap cleanup EXIT

case "$UPLOAD_FILENAME" in
  *[!A-Za-z0-9._-]*|'')
    echo "UPLOAD_FILENAME must contain only ASCII letters, numbers, dots, hyphens, or underscores" >&2
    exit 1
    ;;
esac

if stat -f%z "$VIDEO_PATH" >/dev/null 2>&1; then
  SIZE_BYTES=$(stat -f%z "$VIDEO_PATH")
  MD5_HEX=$(md5 -q "$VIDEO_PATH")
else
  SIZE_BYTES=$(stat -c%s "$VIDEO_PATH")
  MD5_HEX=$(md5sum "$VIDEO_PATH" | awk '{print $1}')
fi

jq -n --arg filename "$UPLOAD_FILENAME" --argjson size "$SIZE_BYTES" --arg md5 "$MD5_HEX" \
  '{filename:$filename,mime_type:"video/mp4",size_bytes:$size,md5sum:$md5,purpose:"vision"}' \
  > "$WORK_DIR/session-request.json"

curl --fail-with-body --silent --show-error --request POST \
  --url "$API_BASE/v1/files/upload-sessions" \
  --header "Authorization: Bearer $LINKMODEL_API_KEY" \
  --header "Content-Type: application/json" \
  --data-binary "@$WORK_DIR/session-request.json" \
  --output "$WORK_DIR/session.json"

FILE_ID=$(jq -er '.data.file_id' "$WORK_DIR/session.json")
UPLOAD_URL=$(jq -er '.data.upload.url' "$WORK_DIR/session.json")
jq -r '.data.upload.headers | to_entries[] | "\(.key): \(.value)"' \
  "$WORK_DIR/session.json" > "$WORK_DIR/upload-headers.txt"

curl --fail-with-body --silent --show-error --request PUT \
  --url "$UPLOAD_URL" \
  --header "@$WORK_DIR/upload-headers.txt" \
  --upload-file "$VIDEO_PATH"

curl --fail-with-body --silent --show-error --request POST \
  --url "$API_BASE/v1/files/$FILE_ID/complete" \
  --header "Authorization: Bearer $LINKMODEL_API_KEY" \
  --header "Content-Type: application/json"

FILE_URI=""
for attempt in $(seq 1 60); do
  RESPONSE=$(curl --fail-with-body --silent --show-error \
    --url "$API_BASE/v1/files/$FILE_ID" \
    --header "Authorization: Bearer $LINKMODEL_API_KEY")
  STATUS=$(printf '%s' "$RESPONSE" | jq -r '.data.status')
  printf 'attempt=%s status=%s\n' "$attempt" "$STATUS"
  case "$STATUS" in
    active)
      FILE_URI=$(printf '%s' "$RESPONSE" | jq -er '.data.uri')
      break
      ;;
    failed|error)
      echo "Gemini file processing failed" >&2
      exit 1
      ;;
  esac
  sleep 10
done
test -n "$FILE_URI" || { echo "Timed out waiting for the file" >&2; exit 1; }

jq -n --arg uri "$FILE_URI" \
  '{contents:[{role:"user",parts:[{fileData:{fileUri:$uri,mimeType:"video/mp4"}},{text:"Describe the important events in this video."}]}]}' \
  > "$WORK_DIR/generate-request.json"

curl --fail-with-body --silent --show-error --request POST \
  --url "$API_BASE/v1beta/models/$MODEL:generateContent" \
  --header "Authorization: Bearer $LINKMODEL_API_KEY" \
  --header "Content-Type: application/json" \
  --data-binary "@$WORK_DIR/generate-request.json" \
  --output "$WORK_DIR/generate.json"

jq -r '.candidates[0].content.parts[] | select(.text) | .text' \
  "$WORK_DIR/generate.json"
jq '{modelVersion, finishReason:.candidates[0].finishReason, usageMetadata}' \
  "$WORK_DIR/generate.json"

Troubleshooting

Symptom	Check
Session creation returns `400`	Confirm filename, MIME type, byte size, hexadecimal MD5, and `purpose: vision`.
`generateContent` returns `400` for an active file	Retry with a portable ASCII `UPLOAD_FILENAME`; avoid spaces and non-ASCII punctuation. Save the returned `request_id` if the problem continues.
Direct upload returns `400` or `403`	Confirm the URL has not expired, the bytes match the declared MD5, and every returned upload header is sent unchanged.
File never becomes active	Check the current status and expiration timestamps; create a new upload session after the upload instruction or file resource expires.
Gemini rejects the model	Confirm that your API key can access the selected Gemini model and that the model supports video `fileData`.
Gemini rejects the URI	Confirm the file belongs to the same LinkModel account, is still active, and is passed unchanged as `fileData.fileUri`.

Overview

Guides

FAQ

Video understanding with Gemini

Before you begin

1. Calculate file metadata

2. Create a Gemini upload session

3. Upload the video bytes

4. Complete the upload

5. Wait until the file is active

6. Analyze the video with Gemini

7. Delete the file

Complete runnable example

Troubleshooting

API Reference

​Before you begin

​1. Calculate file metadata

​2. Create a Gemini upload session

​3. Upload the video bytes

​4. Complete the upload

​5. Wait until the file is active

​6. Analyze the video with Gemini

​7. Delete the file

​Complete runnable example

​Troubleshooting

​API Reference

Before you begin

1. Calculate file metadata

2. Create a Gemini upload session

3. Upload the video bytes

4. Complete the upload

5. Wait until the file is active

6. Analyze the video with Gemini

7. Delete the file

Complete runnable example

Troubleshooting

API Reference