DeepSeek Vision API: Image URL, Base64, or File ID?

Your first DeepSeek vision request uses a small image from your laptop. It works.

The production application is less predictable. Some images live behind temporary download links. Others are large screenshots. A batch contains files uploaded hours earlier, and a retry may happen after the original link expires.

At that point, image delivery becomes an engineering decision.

Should the application send a URL, place base64 data inside the request, or upload the file and reference an identifier?

The choice affects request size, accessibility, retries, storage, and gateway compatibility. It can also determine whether the application repeatedly uploads the same image or attempts to use a reference that the receiving service cannot resolve.

This tutorial shows how to choose the transport method deliberately. It focuses on moving image inputs through a DeepSeek API route, rather than evaluating the model’s visual intelligence or repeating a general model introduction.

The code is an illustrative request-building example. It has not been run against your account, and model availability and limits must be confirmed for the selected gateway route.

Begin with the input methods the model API documents

DeepSeek’s current vision documentation describes deepseek-flash image input through base64 data URLs, accessible external image URLs, and references to files uploaded through its Files API.

For Chat Completions, image content is carried in a content-block array rather than a plain message string. The documentation also specifies format and payload limits. Those are direct-service rules; a gateway may impose additional restrictions. DeepSeek API Docs

This gives you three possible delivery patterns, but it does not mean every intermediary exposes all three.

Create a route-specific capability record before implementation:

A supported image model and a supported file-upload workflow are separate requirements.

Step 1: Classify how the application obtains its images

Start with your source, not your preferred SDK.

A live support tool may receive a screenshot directly from a user. An e-commerce application may already store approved images in object storage. A document-processing pipeline may analyze the same scanned page repeatedly.

These workloads favor different delivery methods.

Use this initial decision table:

The table is a starting point, not a universal ranking.

Also identify who is allowed to access the image and how long it should remain available. A convenient public link is not automatically an acceptable data-handling decision.

The application should preserve its access policy whichever transport method it chooses.

Step 2: Understand what base64 changes

Base64 moves the image bytes into the request body.

This avoids a separate image download from your storage location during inference, but it increases the request payload. Standard base64 encoding requires approximately four characters for every three input bytes, before adding the JSON structure.

For an image containing exactly 6 MiB of binary data, the encoded portion is approximately 8 MiB. This is a payload-size calculation, not an estimate of image-token usage or API cost.

That distinction matters.

Uploading more bytes and consuming more model tokens are related through the overall workflow, but they are not interchangeable measurements. Do not estimate visual token consumption from base64 string length unless the provider explicitly defines that relationship.

Also account for memory. An application may temporarily hold the original bytes, the encoded string, and the serialized JSON body. Large batches can create avoidable memory pressure before any model request is sent.

Step 3: Build the request without embedding credentials in code

The following JavaScript example constructs a small base64 image request using environment configuration.

DEEPSEEK_CHAT_URL must contain the complete Chat Completions operation URL confirmed for your route. DEEPSEEK_MODEL must match a model available to your account.

import { readFile } from "node:fs/promises";

const endpoint = process.env.DEEPSEEK_CHAT_URL;
const apiKey = process.env.MODEL_API_KEY;
const model = process.env.DEEPSEEK_MODEL;

if (!endpoint || !apiKey || !model) {
  throw new Error("Missing endpoint, API key, or model configuration");
}

const bytes = await readFile("./sample.png");

// This is an application example limit, not a provider quota.
const applicationLimit = 6 * 1024 * 1024;

if (bytes.length > applicationLimit) {
  throw new Error("Image exceeds this example's application limit");
}

const payload = {
  model,
  messages: [
    {
      role: "user",
      content: [
        {
          type: "text",
          text: "Read the visible product code. If unclear, say unreadable."
        },
        {
          type: "image_url",
          image_url: {
            url: `data:image/png;base64,${bytes.toString("base64")}`
          }
        }
      ]
    }
  ]
};

const serialized = JSON.stringify(payload);

console.log({
  imageBytes: bytes.length,
  requestBytes: Buffer.byteLength(serialized)
});

const response = await fetch(endpoint, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "Content-Type": "application/json"
  },
  body: serialized,
  signal: AbortSignal.timeout(90_000)
});

const responseText = await response.text();

if (!response.ok) {
  throw new Error(`Model request failed: HTTP ${response.status}`);
}

const result = JSON.parse(responseText);
console.log(result.choices?.[0]?.message?.content ?? "No text output");

Use a file that is actually PNG data; changing an extension does not convert an image. The timeout and application size limit are illustrative settings, not recommended universal values.

The example intentionally avoids printing the key, encoded image, or raw error body. Production error records should retain useful diagnostics through a redaction policy.

Step 4: Use external URLs when accessibility is predictable

An image URL keeps the image bytes out of the JSON request body. The receiving service must then download the image.

DeepSeek’s direct documentation requires an accessible HTTP or HTTPS image URL and specifies a download-time constraint. Verify both the upstream requirement and any gateway-specific behavior before relying on the method. DeepSeek API Docs

Test the exact URL your backend will send.

A page containing an image is not necessarily the image resource itself. A storage URL that works in a logged-in browser may require cookies that the model service does not have. A link may also return an HTML access-denied page instead of image bytes.

Record the image’s stable application identifier separately from its temporary download URL. This allows the system to refresh access without losing the connection to the original task.

Do not use the URL itself as the only identity of a customer image.

Step 5: Generate temporary links close to dispatch

A common production failure is creating a signed URL when a job enters the queue.

The job waits. The worker finally starts. The model service tries to retrieve the image, but the URL is no longer valid.

A better design prepares the link near the time of dispatch, subject to your storage system’s access rules.

The validity window should account for queue uncertainty after signing, request setup, remote retrieval, and any permitted retry. Avoid publishing a universal expiration duration: the correct value depends on the system and its data policy.

On retry, determine whether a new link is needed. Reusing an expired URL simply repeats the failure.

Log that a reference was refreshed without logging the secret-bearing query string. Signed URLs can grant access to content and should be treated accordingly.

This is an application responsibility; the model cannot renew a storage credential it was never authorized to manage.

Step 6: Treat file IDs as service-owned references

A file identifier is not the file itself.

Before adopting a Files API workflow, confirm where the file is stored, which credentials can reference it, how long it remains available, and how deletion works.

Use the official DeepSeek Files API guide as the direct-service reference, then verify the gateway’s supported operations separately.

Do not assume that a file uploaded directly to one service can be referenced through an unrelated gateway account. A gateway may have a documented mechanism for this, but that mechanism must be established rather than inferred from a similar-looking identifier.

Test the complete lifecycle:

1. Upload a harmless sample.
2. Reference it in a model request.
3. Reuse it in a second request.
4. Confirm the applicable access scope.
5. Delete it using the supported operation.
6. Verify the application handles later references appropriately.

If the gateway only supports chat requests, choose an input method it actually exposes instead of building around an unavailable upload path.

Step 7: Check every payload boundary

A request can satisfy the model provider’s limit and still be rejected earlier.

The application server, reverse proxy, API gateway, and upstream service may each have a request-size constraint. The effective supported size is limited by the relevant boundary with the lowest allowance.

Measure the serialized request body rather than only the original file size.

For a multi-image request, include all encoded images, text, metadata, and JSON overhead. Also consider whether the client or server duplicates the body in memory while preparing it.

When a request is rejected, record the status, response category, and layer where the rejection appears to occur. Do not assume every oversized-request error originates with DeepSeek.

The 4SAPI documentation should be used to confirm the route and operational requirements. If a size boundary is not documented, ask for clarification before sending production-sized batches.

Step 8: Preserve detail before optimizing transfer

Reducing image size can make transmission easier, but it may remove information the task needs.

A product-category classifier may work with a smaller image. Reading a tiny serial number may require a targeted crop. A chart-analysis task may need the axis labels and surrounding legend.

Evaluate transformations against the task, not against an arbitrary file-size goal.

Keep the original image and transformation version associated with the request. If a crop is used, record which region it represents. This helps explain why the model could or could not identify a value.

Do not claim that a resized image is equivalent merely because it looks similar on a small preview.

The earlier DeepSeek vision overview introduces the model family’s visual use cases. This tutorial addresses the separate delivery problem: ensuring that the right evidence reaches the model in a usable form.

Step 9: Make image retries safe and explainable

A timed-out request creates uncertainty.

The client may have stopped waiting while the upstream operation continued. Automatically repeating the request can therefore create another attempt and potentially another charge.

Track an application task ID and a separate identifier for each attempt. Keep the source image identity stable across attempts, even if the signed URL or transport method changes.

Use bounded retry only for conditions your application classifies as recoverable.

An invalid image format, missing permission, or unsupported content block usually needs a change rather than another identical request. A temporary transport problem may justify a retry after the relevant checks.

Avoid switching from URL input to base64 automatically without considering request size and data handling. A fallback should be a documented application behavior, not an improvised attempt to make any request succeed.

Step 10: Compare transport methods without confusing the result

To evaluate URL and base64 delivery, use the same approved image and the same task.

Record preparation time, request size, model-response time, retrieval errors, output acceptance, and total attributable cost. Do not call this a model benchmark; you are testing the integration path.

A useful test set includes:

• A small clear image.
• A larger image near your application limit.
• An image containing fine text.
• A temporary URL that remains valid.
• An intentionally expired URL.
• A repeated image used across several requests.

The invalid case is important because it shows whether your application reports a meaningful failure rather than returning an unrelated model answer.

For model changes, the DeepSeek API update-verification guide covers a different evaluation boundary. Keep transport tests and model-version tests separate when possible.

Step 11: Connect consumption records to accepted visual results

An image request is commercially useful when it produces a result your application can use.

For a serial-number task, acceptance might require an exact match or an explicit unreadable result. For classification, it might require agreement with reviewed labels.

Do not count every response containing text as success.

Associate application attempts with the records available through the 4SAPI usage-log guide. Include retries when calculating the cost of accepted results.

Also track avoidable transfer work. Re-encoding and resending the same large image may increase application overhead even where it does not change the provider’s published token accounting.

These measurements help your team choose a transport method based on actual workload behavior rather than a general preference for URLs or base64.

Start with the image path your business actually uses

For a 4SAPI evaluation, bring a representative image and its real storage pattern.

Confirm the available DeepSeek vision model, supported input methods, request-size conditions, and any Files API support. Then follow the getting-started instructions to create the account configuration.

Begin with one successful request and one intentional failure. If your production system uses temporary URLs, make the failure an expired reference. If it sends base64, make it an application-side size rejection.

Expand to a small batch only after the application handles both cases clearly.

The useful outcome is a repeatable image-delivery path: the correct image reaches DeepSeek, failures are classified, and each accepted result can be traced to its input and cost.