# FIM Completion API (Beta)

FIM (Fill In the Middle) Completion API.

User must set `base_url="https://api.deepseek.com/beta"` to use this feature.

## Endpoint

```http
POST /completions
```

operationId: `createCompletion`

### Servers

- `https://api.deepseek.com/beta`

## Authentication

### Alternative 1

**bearerAuth**

`Authorization: Bearer <API_KEY>`

```yaml
type: http
scheme: bearer
```

## Request body

**required**

### application/json

- Reference: [CreateCompletionRequest](#schema-create-completion-request) (`#/components/schemas/CreateCompletionRequest`)

## Responses

### 200

OK

#### application/json

- Reference: [CreateCompletionResponse](#schema-create-completion-response) (`#/components/schemas/CreateCompletionResponse`)

**Example**

```json
{
  "id": "60f16544-b4f2-4149-9326-79ccc6610d67",
  "choices": [
    {
      "text": "return a + b",
      "index": 0,
      "logprobs": null,
      "finish_reason": "stop"
    }
  ],
  "created": 1793084841,
  "model": "deepseek-flash",
  "system_fingerprint": "e72d3c7f663d3e1383b00b3884cb4501",
  "object": "text_completion",
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 4,
    "total_tokens": 16,
    "prompt_tokens_details": {
      "cached_tokens": 0
    },
    "prompt_cache_hit_tokens": 0,
    "prompt_cache_miss_tokens": 12
  }
}
```

### 200 (Streaming)

OK, returns completion chunks as server-sent events, followed by `data: [DONE]`.

#### text/event-stream

- `type`: `array`

- **Array items**

  - Reference: [CreateCompletionResponse](#schema-create-completion-response) (`#/components/schemas/CreateCompletionResponse`)

**Example**

```
data: {"id":"79323126-3e6a-4fb3-8d99-71fb50f801fc","choices":[{"text":"","index":0,"logprobs":null,"finish_reason":null}],"created":1793084906,"model":"deepseek-flash","system_fingerprint":"e72d3c7f663d3e1383b00b3884cb4501","object":"text_completion"}

data: {"id":"79323126-3e6a-4fb3-8d99-71fb50f801fc","choices":[{"text":"return","index":0,"logprobs":null,"finish_reason":null}],"created":1793084906,"model":"deepseek-flash","system_fingerprint":"e72d3c7f663d3e1383b00b3884cb4501","object":"text_completion"}

data: {"id":"79323126-3e6a-4fb3-8d99-71fb50f801fc","choices":[{"text":" a","index":0,"logprobs":null,"finish_reason":null}],"created":1793084906,"model":"deepseek-flash","system_fingerprint":"e72d3c7f663d3e1383b00b3884cb4501","object":"text_completion"}

data: {"id":"79323126-3e6a-4fb3-8d99-71fb50f801fc","choices":[{"text":" +","index":0,"logprobs":null,"finish_reason":null}],"created":1793084906,"model":"deepseek-flash","system_fingerprint":"e72d3c7f663d3e1383b00b3884cb4501","object":"text_completion"}

data: {"id":"79323126-3e6a-4fb3-8d99-71fb50f801fc","choices":[{"text":" b","index":0,"logprobs":null,"finish_reason":null}],"created":1793084906,"model":"deepseek-flash","system_fingerprint":"e72d3c7f663d3e1383b00b3884cb4501","object":"text_completion"}

data: {"id":"79323126-3e6a-4fb3-8d99-71fb50f801fc","choices":[{"text":"","index":0,"logprobs":null,"finish_reason":"stop"}],"created":1793084906,"model":"deepseek-flash","system_fingerprint":"e72d3c7f663d3e1383b00b3884cb4501","object":"text_completion","usage":{"prompt_tokens":12,"completion_tokens":4,"total_tokens":16,"prompt_tokens_details":{"cached_tokens":0},"prompt_cache_hit_tokens":0,"prompt_cache_miss_tokens":12}}

data: [DONE]
```

## Code samples

### curl

```bash
# Set DEEPSEEK_API_KEY to your API key before running this example.
curl --silent --show-error --max-time 60 "https://api.deepseek.com/beta/completions" \
  --header "Authorization: Bearer ${DEEPSEEK_API_KEY}" \
  --header "Content-Type: application/json" \
  --data '{
  "model": "deepseek-flash",
  "prompt": "def add(a, b):\n    ",
  "suffix": "\n",
  "max_tokens": 32,
  "temperature": 0,
  "stream": false
}'
```

### Python — OpenAI SDK

```python
# Set DEEPSEEK_API_KEY to your API key before running this example.
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["DEEPSEEK_API_KEY"],
    base_url="https://api.deepseek.com/beta",
    timeout=60.0,
)

response = client.completions.create(
    model="deepseek-flash",
    prompt="def add(a, b):\n    ",
    suffix="\n",
    max_tokens=32,
    temperature=0,
    stream=False,
)
print(response.model_dump_json(indent=2))
```

## Referenced schemas

### schema-create-completion-request

**CreateCompletionRequest** — `#/components/schemas/CreateCompletionRequest`

- `type`: `object`

- `required`: `["model","prompt"]`

- **Properties**

  - **`model`** (required)

    ID of the model to use. Use `deepseek-flash` or `deepseek-v4-pro`.

    - `type`: `string`

    - `enum`: `["deepseek-flash","deepseek-v4-pro"]`

  - **`prompt`** (required)

    The prompt to generate completions for.

    - `nullable`: `false`

    - `type`: `string`

  - **`echo`** (optional)

    Echo back the prompt in addition to the completion. Cannot be used together with `suffix` or `logprobs`.

    - `type`: `boolean`

    - `default`: `false`

    - `nullable`: `true`

  - **`logprobs`** (optional)

    Include the log probabilities on the `logprobs` most likely output tokens, as well the chosen tokens. For example, if `logprobs` is 20, the API will return a list of the 20 most likely tokens. The API will always return the `logprob` of the sampled token, so there may be up to `logprobs+1` elements in the response.

    The maximum value for `logprobs` is 20.

    - `type`: `integer`

    - `minimum`: `0`

    - `maximum`: `20`

    - `default`: `null`

    - `nullable`: `true`

  - **`max_tokens`** (optional)

    The maximum number of tokens that can be generated in the completion.

    - `type`: `integer`

    - `minimum`: `0`

    - `nullable`: `true`

    **Example**

    ```json
    1024
    ```

  - **`stop`** (optional)

    Up to 16 sequences where the API will stop generating further tokens. Each sequence must be a non-empty string of at most 512 bytes (UTF-8 encoded). The returned text will not contain the stop sequence.

    - `nullable`: `true`

    - `default`: `null`

    - **oneOf**

      - oneOf 1

        - `type`: `string`

        - `nullable`: `true`

        **Example**

        ```json
        null
        ```

      - oneOf 2

        - `type`: `array`

        - `minItems`: `1`

        - `maxItems`: `16`

        - **Array items**

          - `type`: `string`

          **Example**

          ```json
          "[\"\\n\"]"
          ```

  - **`stream`** (optional)

    Whether to stream back partial progress. If set, tokens will be sent as data-only [server-sent events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events#Event_stream_format) as they become available, with the stream terminated by a `data: [DONE]` message. [Example Python code](https://cookbook.openai.com/examples/how_to_stream_completions).

    - `type`: `boolean`

    - `nullable`: `true`

    - `default`: `false`

  - **`stream_options`** (optional)

    - Reference: [ChatCompletionStreamOptions](#schema-chat-completion-stream-options) (`#/components/schemas/ChatCompletionStreamOptions`)

  - **`suffix`** (optional)

    The suffix that comes after a completion of inserted text.

    - `default`: `null`

    - `nullable`: `true`

    - `type`: `string`

    **Example**

    ```json
    null
    ```

  - **`temperature`** (optional)

    What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic.

    We generally recommend altering this or `top_p` but not both.

    - `type`: `number`

    - `minimum`: `0`

    - `maximum`: `2`

    - `default`: `1`

    - `nullable`: `true`

    **Example**

    ```json
    1
    ```

  - **`top_p`** (optional)

    An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top\_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered.

    The value must be greater than 0 and at most 1. We generally recommend altering this or `temperature` but not both.

    - `type`: `number`

    - `minimum`: `0`

    - `exclusiveMinimum`: `true`

    - `maximum`: `1`

    - `default`: `1`

    - `nullable`: `true`

    **Example**

    ```json
    1
    ```

  - **`frequency_penalty`** (optional)

    This parameter is no longer supported. It will not take effect if you pass it to the API.

    - `deprecated`: `true`

  - **`presence_penalty`** (optional)

    This parameter is no longer supported. It will not take effect if you pass it to the API.

    - `deprecated`: `true`

### schema-create-completion-response

**CreateCompletionResponse** — `#/components/schemas/CreateCompletionResponse`

Represents a completion response from the API. Note: both the streamed and non-streamed response objects share the same shape (unlike the chat endpoint).

- `type`: `object`

- `required`: `["id","object","created","model","choices"]`

- **Properties**

  - **`id`** (required)

    A unique identifier for the completion.

    - `type`: `string`

  - **`choices`** (required)

    The list of completion choices the model generated for the input prompt.

    - `type`: `array`

    - **Array items**

      - `type`: `object`

      - `required`: `["finish_reason","index","logprobs","text"]`

      - **Properties**

        - **`finish_reason`** (required)

          The reason the model stopped generating tokens. This will be `stop` if the model hit a natural stop point or a provided stop sequence,
          `length` if the maximum number of tokens specified in the request was reached,
          `content_filter` if content was omitted due to a flag from our content filters,
          `insufficient_system_resource` if the request is interrupted due to insufficient resource of the inference system,
          or `aborted` if the generation was interrupted.

          - `type`: `string`

          - `nullable`: `true`

          - `enum`: `["stop","length","content_filter","insufficient_system_resource","aborted"]`

        - **`index`** (required)

          - `type`: `integer`

        - **`logprobs`** (required)

          - `type`: `object`

          - `nullable`: `true`

          - **Properties**

            - **`text_offset`** (optional)

              - `type`: `array`

              - **Array items**

                - `type`: `integer`

            - **`token_logprobs`** (optional)

              - `type`: `array`

              - **Array items**

                - `type`: `number`

            - **`tokens`** (optional)

              - `type`: `array`

              - **Array items**

                - `type`: `string`

            - **`top_logprobs`** (optional)

              - `type`: `array`

              - **Array items**

                - `type`: `object`

                - **additionalProperties**

                  - `type`: `number`

        - **`text`** (required)

          - `type`: `string`

  - **`created`** (required)

    The Unix timestamp (in seconds) of when the completion was created.

    - `type`: `integer`

  - **`model`** (required)

    The model used for completion.

    - `type`: `string`

  - **`system_fingerprint`** (optional)

    This fingerprint represents the backend configuration that the model runs with.

    - `type`: `string`

  - **`object`** (required)

    The object type, which is always "text\_completion"

    - `type`: `string`

    - `enum`: `["text_completion"]`

  - **`usage`** (optional)

    - Reference: [CompletionUsage](#schema-completion-usage) (`#/components/schemas/CompletionUsage`)

### schema-chat-completion-stream-options

**ChatCompletionStreamOptions** — `#/components/schemas/ChatCompletionStreamOptions`

Options for streaming response. Must be set together with `stream: true`; if `stream` is not set to `true`, the API returns a `400` error.

- `type`: `object`

- `nullable`: `true`

- `default`: `null`

- **Properties**

  - **`include_usage`** (optional)

    If set to `true`, all chunks in the stream will include a `usage` field, whose value is `null` on every chunk except the last one. If omitted or set to `false`, the `usage` field is absent from all chunks except the last one.

    Either way, the last chunk before the `data: [DONE]` message carries the token usage statistics for the entire request in its `usage` field. Note that no separate usage-only chunk is emitted: the statistics ride on the last content chunk, whose `choices` array always contains exactly one element that carries no new content and a non-null `finish_reason`.

    - `type`: `boolean`

**Example**

```json
null
```

### schema-completion-usage

**CompletionUsage** — `#/components/schemas/CompletionUsage`

Usage statistics for the completion request.

- `type`: `object`

- `required`: `["prompt_tokens","prompt_tokens_details","prompt_cache_hit_tokens","prompt_cache_miss_tokens","completion_tokens","total_tokens"]`

- **Properties**

  - **`completion_tokens`** (required)

    Number of tokens in the generated completion.

    - `type`: `integer`

  - **`prompt_tokens`** (required)

    Number of tokens in the prompt. It equals prompt\_cache\_hit\_tokens + prompt\_cache\_miss\_tokens.

    - `type`: `integer`

  - **`prompt_tokens_details`** (required)

    Breakdown of tokens used in the prompt.

    - `type`: `object`

    - **Properties**

      - **`cached_tokens`** (optional)

        Number of tokens in the prompt that hit the context cache. Same as `prompt_cache_hit_tokens`.

        - `type`: `integer`

  - **`prompt_cache_hit_tokens`** (required)

    Number of tokens in the prompt that hits the context cache.

    - `type`: `integer`

  - **`prompt_cache_miss_tokens`** (required)

    Number of tokens in the prompt that misses the context cache.

    - `type`: `integer`

  - **`total_tokens`** (required)

    Total number of tokens used in the request (prompt + completion).

    - `type`: `integer`

  - **`completion_tokens_details`** (optional)

    Breakdown of tokens used in a completion.

    - `type`: `object`

    - **Properties**

      - **`reasoning_tokens`** (optional)

        Tokens generated by the model for reasoning.

        - `type`: `integer`

      - **`safety_tokens`** (optional)

        DeepSeek extension. Tokens of the safety review, already included in `completion_tokens`. Present only when `safety_check` is `high`.

        - `type`: `integer`

        - `minimum`: `0`

  - **`server_tool_use`** (optional)

    With the web tools. The numbers of searches and fetches; omitted when all counts are zero. See the [Web Tools Guide](https://api-docs.deepseek.com/guides/web_tools.md#chat-completions-api).

    - `type`: `object`

    - **Properties**

      - **`tool_search`** (optional)

        Number of searches, excluding image searches.

        - `type`: `integer`

        - `minimum`: `0`

      - **`tool_fetch`** (optional)

        Number of page fetches.

        - `type`: `integer`

        - `minimum`: `0`

      - **`tool_image_search`** (optional)

        Number of image searches.

        - `type`: `integer`

        - `minimum`: `0`
