API Teks

Chat, Legacy Completions, dan Responses; mendukung streaming SSE

API Teks menyediakan Chat, penyelesaian teks Legacy, dan Responses. Ketiganya mendukung JSON non-streaming dan streaming SSE.

Ringkasan

Gateway YunSell AI mengekspos tiga endpoint teks. Pilih berdasarkan skenario:

Endpoint	Gunakan saat	Jenis endpoint
`POST /v1/chat/completions`	Obrolan umum, tool calling, input multimodal (gambar, dll.), streaming SSE	`openai`
`POST /v1/completions`	Penyelesaian teks legacy (prompt → kelanjutan)	`openai`
`POST /v1/responses`	Responses multi-putaran, reasoning, output terstruktur, tool calling	`openai-response`

Tips pemilihan:

Sebagian besar proyek baru sebaiknya memilih Chat Completions (/v1/chat/completions).
Gunakan Completions (/v1/completions) hanya untuk kelanjutan prompt tunggal atau kompatibilitas SDK legacy.
Gunakan Responses (/v1/responses) saat Anda membutuhkan konteks multi-putaran previous_response_id atau output terstruktur Responses.

Prasyarat: model harus muncul di daftar API Model dan mencakup jenis endpoint yang sesuai di supported_endpoint_types.

Konvensi: Auth, Base URL, Content-Type, dll. dijelaskan di Konvensi umum. Format error ada di Konvensi umum.

Endpoint

Method	Path	Deskripsi
POST	`/v1/chat/completions`	Chat (mendukung streaming SSE)
POST	`/v1/completions`	Penyelesaian teks
POST	`/v1/responses`	Obrolan Responses

POST `/v1/chat/completions`

Penyelesaian chat dengan JSON non-streaming dan streaming SSE.

Auth: Bearer Token

Content-Type: application/json

Body permintaan

{
  "model": "gpt-4o",
  "messages": [
    {
      "role": "system",
      "content": "You are a helpful assistant."
    },
    {
      "role": "user",
      "content": "Hello, who are you?"
    }
  ],
  "temperature": 0.7,
  "max_tokens": 1024,
  "stream": false
}

Field permintaan

Field	Tipe	Wajib	Deskripsi
`model`	string	Ya	ID model
`messages`	array	Ya	Daftar pesan percakapan
`messages[].role`	string	Ya	`system` / `user` / `assistant` / `tool`
`messages[].content`	string / array	Ya	Teks atau konten multimodal
`stream`	boolean	Tidak	Saat `true`, mengembalikan aliran SSE; default `false`
`temperature`	number	Tidak	Temperatur sampling, 0–2
`top_p`	number	Tidak	Nucleus sampling, 0–1
`max_tokens`	integer	Tidak	Maks. token output
`max_completion_tokens`	integer	Tidak	Maks. token completion
`stop`	string / array	Tidak	Urutan stop
`tools`	array	Tidak	Definisi tool
`tool_choice`	string / object	Tidak	Strategi pemilihan tool
`response_format`	object	Tidak	Format output terstruktur
`stream_options`	object	Tidak	Opsi streaming, mis. `{ "include_usage": true }`

Contoh pesan multimodal (input gambar):

{
  "model": "gpt-4o",
  "messages": [
    {
      "role": "user",
      "content": [
        { "type": "text", "text": "What's in this image?" },
        {
          "type": "image_url",
          "image_url": { "url": "https://example.com/image.jpg" }
        }
      ]
    }
  ]
}

Contoh permintaan (curl)

Non-streaming:

curl http://www.mangoto.ai/v1/chat/completions \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "Hello, who are you?"}
    ],
    "temperature": 0.7,
    "max_tokens": 1024,
    "stream": false
  }'

Streaming (SSE):

curl -N http://www.mangoto.ai/v1/chat/completions \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "Hello"}],
    "stream": true
  }'

Body respons (non-streaming)

HTTP 200, Content-Type: application/json

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1712697600,
  "model": "gpt-4o",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello! I'm an AI assistant. How can I help you today?"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 28,
    "completion_tokens": 15,
    "total_tokens": 43
  }
}

Field respons

Field	Tipe	Deskripsi
`id`	string	ID respons, mis. `chatcmpl-xxx`
`object`	string	Selalu `chat.completion`
`created`	integer	Unix timestamp (detik)
`model`	string	Model yang benar-benar digunakan
`choices`	array	Hasil generasi; panjang sama dengan `n` permintaan (default 1)
`choices[].index`	integer	Indeks hasil, dimulai dari 0
`choices[].message.role`	string	Selalu `assistant`
`choices[].message.content`	string / null	Teks balasan; mungkin `null` untuk tool call
`choices[].message.tool_calls`	array	Daftar tool call (saat tools diaktifkan)
`choices[].message.tool_calls[].id`	string	ID tool call
`choices[].message.tool_calls[].type`	string	Selalu `function`
`choices[].message.tool_calls[].function.name`	string	Nama fungsi
`choices[].message.tool_calls[].function.arguments`	string	Argumen fungsi sebagai string JSON
`choices[].message.reasoning_content`	string	Teks reasoning (model reasoning)
`choices[].finish_reason`	string	Alasan berhenti; lihat tabel di bawah
`usage`	object	Penggunaan token; lihat Objek respons bersama

Nilai finish_reason:

Nilai	Deskripsi
`stop`	Berhenti alami atau mencapai urutan stop
`length`	Mencapai batas `max_tokens`
`tool_calls`	Model memulai tool call
`content_filter`	Konten diblokir oleh kebijakan keamanan

Contoh respons tool call:

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1712697600,
  "model": "gpt-4o",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": null,
        "tool_calls": [
          {
            "id": "call_abc123",
            "type": "function",
            "function": {
              "name": "get_weather",
              "arguments": "{\"location\":\"Beijing\"}"
            }
          }
        ]
      },
      "finish_reason": "tool_calls"
    }
  ],
  "usage": {
    "prompt_tokens": 50,
    "completion_tokens": 20,
    "total_tokens": 70
  }
}

Body respons (streaming)

HTTP 200, Content-Type: text/event-stream

Dengan "stream": true di body permintaan, server mendorong event SSE. Setiap pesan terlihat seperti:

data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1712697600,"model":"gpt-4o","choices":[{"index":0,"delta":{"role":"assistant","content":"Hello"},"finish_reason":null}]}

data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1712697600,"model":"gpt-4o","choices":[{"index":0,"delta":{"content":"!"},"finish_reason":null}]}

data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1712697600,"model":"gpt-4o","choices":[{"index":0,"delta":{},"finish_reason":"stop"}],"usage":{"prompt_tokens":28,"completion_tokens":15,"total_tokens":43}}

data: [DONE]

Field chunk streaming

Field	Tipe	Deskripsi
`id`	string	ID yang sama dengan respons akhir
`object`	string	Selalu `chat.completion.chunk`
`created`	integer	Unix timestamp (detik)
`model`	string	Model yang digunakan
`system_fingerprint`	string	Sidik jari sistem (beberapa model)
`choices[].index`	integer	Indeks hasil
`choices[].delta.role`	string	Chunk pertama mungkin menyertakan `assistant`
`choices[].delta.content`	string	Fragmen teks inkremental
`choices[].delta.reasoning_content`	string	Teks reasoning inkremental (model reasoning)
`choices[].delta.tool_calls`	array	Fragmen tool call inkremental
`choices[].finish_reason`	string / null	Alasan berhenti di chunk terakhir; selain itu `null`
`usage`	object	Hanya muncul di chunk terakhir (memerlukan `stream_options.include_usage=true`)

Penanda akhir streaming: baris terakhir data: [DONE].

POST `/v1/completions`

Endpoint penyelesaian teks legacy.

Auth: Bearer Token

Content-Type: application/json

Body permintaan

{
  "model": "gpt-4o",
  "prompt": "Say this is a test",
  "max_tokens": 100,
  "temperature": 0.7,
  "stream": false
}

Field permintaan

Field	Tipe	Wajib	Deskripsi
`model`	string	Ya	ID model
`prompt`	string / array	Ya	Teks prompt
`max_tokens`	integer	Tidak	Maks. token output
`temperature`	number	Tidak	Temperatur sampling
`top_p`	number	Tidak	Nucleus sampling
`n`	integer	Tidak	Jumlah completion; default 1
`stream`	boolean	Tidak	Apakah streaming
`stop`	string / array	Tidak	Urutan stop

Contoh permintaan (curl)

Non-streaming:

curl http://www.mangoto.ai/v1/completions \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "prompt": "Say this is a test",
    "max_tokens": 100,
    "temperature": 0.7,
    "stream": false
  }'

Streaming (SSE):

curl -N http://www.mangoto.ai/v1/completions \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "prompt": "Say this is a test",
    "stream": true
  }'

Body respons (non-streaming)

HTTP 200

{
  "id": "cmpl-abc123",
  "object": "text_completion",
  "created": 1712697600,
  "model": "gpt-4o",
  "choices": [
    {
      "index": 0,
      "text": "This is indeed a test.",
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 5,
    "completion_tokens": 6,
    "total_tokens": 11
  }
}

Field respons

Field	Tipe	Deskripsi
`id`	string	ID respons, mis. `cmpl-xxx`
`object`	string	Selalu `text_completion`
`created`	integer	Unix timestamp (detik)
`model`	string	Model yang digunakan
`choices`	array	Hasil generasi
`choices[].index`	integer	Indeks hasil
`choices[].text`	string	Teks completion
`choices[].finish_reason`	string	`stop` / `length` / `content_filter`
`usage`	object	Penggunaan token; lihat Objek respons bersama

Body respons (streaming)

data: {"id":"cmpl-abc123","object":"text_completion","created":1712697600,"choices":[{"index":0,"text":"This","finish_reason":null}]}

data: {"id":"cmpl-abc123","object":"text_completion","created":1712697600,"choices":[{"index":0,"text":" is","finish_reason":null}]}

data: [DONE]

Field chunk streaming

Field	Tipe	Deskripsi
`id`	string	ID respons
`object`	string	Selalu `text_completion`
`created`	integer	Unix timestamp (detik)
`choices[].index`	integer	Indeks hasil
`choices[].text`	string	Fragmen teks inkremental
`choices[].finish_reason`	string / null	Alasan berhenti di chunk terakhir

POST `/v1/responses`

Endpoint obrolan Responses yang mendukung percakapan multi-putaran, tool calling, reasoning, dan lainnya.

Auth: Bearer Token

Content-Type: application/json

Body permintaan

{
  "model": "gpt-4o",
  "input": [
    {
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "Explain quantum computing in one sentence."
        }
      ]
    }
  ],
  "temperature": 0.7,
  "max_output_tokens": 1024,
  "stream": false
}

Field permintaan

Field	Tipe	Wajib	Deskripsi
`model`	string	Ya	ID model
`input`	string / array	Ya	Konten input; string atau array pesan
`instructions`	string	Tidak	Instruksi sistem
`temperature`	number	Tidak	Temperatur sampling
`max_output_tokens`	integer	Tidak	Maks. token output
`stream`	boolean	Tidak	Apakah streaming
`tools`	array	Tidak	Definisi tool
`tool_choice`	string / object	Tidak	Strategi pemilihan tool
`previous_response_id`	string	Tidak	ID respons sebelumnya untuk obrolan multi-putaran
`store`	boolean	Tidak	Apakah menyimpan percakapan
`metadata`	object	Tidak	Metadata kustom

Contoh permintaan (curl)

Non-streaming:

curl http://www.mangoto.ai/v1/responses \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "input": [
      {
        "role": "user",
        "content": [
          {"type": "input_text", "text": "Explain quantum computing in one sentence."}
        ]
      }
    ],
    "temperature": 0.7,
    "max_output_tokens": 1024,
    "stream": false
  }'

Streaming (SSE):

curl -N http://www.mangoto.ai/v1/responses \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "input": "Hello",
    "stream": true
  }'

Body respons (non-streaming)

HTTP 200

{
  "id": "resp_abc123",
  "object": "response",
  "created_at": 1712697600,
  "status": "completed",
  "model": "gpt-4o",
  "output": [
    {
      "type": "message",
      "id": "msg_abc123",
      "status": "completed",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "Quantum computing uses quantum bits that can exist in superposition to perform certain calculations exponentially faster than classical computers.",
          "annotations": []
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 15,
    "output_tokens": 28,
    "total_tokens": 43
  },
  "temperature": 0.7,
  "top_p": 1.0
}

Field respons

Field	Tipe	Deskripsi
`id`	string	ID respons, mis. `resp_xxx`
`object`	string	Selalu `response`
`created_at`	integer	Unix timestamp (detik)
`status`	string	Status respons; lihat tabel di bawah
`model`	string	Model yang digunakan
`output`	array	Daftar item output
`output[].type`	string	Jenis output; lihat tabel di bawah
`output[].id`	string	ID item output
`output[].status`	string	Status item output
`output[].role`	string	Peran (`assistant` untuk tipe `message`)
`output[].content`	array	Daftar blok konten
`output[].content[].type`	string	Jenis konten, mis. `output_text`
`output[].content[].text`	string	Konten teks
`output[].content[].annotations`	array	Daftar anotasi/kutipan
`output[].call_id`	string	ID tool call (tipe `function_call`)
`output[].name`	string	Nama fungsi (tipe `function_call`)
`output[].arguments`	string / object	Argumen fungsi (tipe `function_call`)
`output[].quality`	string	Kualitas gambar (tipe `image_generation_call`)
`output[].size`	string	Ukuran gambar (tipe `image_generation_call`)
`instructions`	string	Instruksi sistem (echo)
`temperature`	number	Temperatur sampling (echo)
`top_p`	number	Nucleus sampling (echo)
`max_output_tokens`	integer	Maks. token output (echo)
`previous_response_id`	string	ID respons sebelumnya
`parallel_tool_calls`	boolean	Apakah panggilan tool paralel diaktifkan
`store`	boolean	Apakah percakapan disimpan
`metadata`	object	Metadata kustom
`incomplete_details.reason`	string	Alasan tidak lengkap (saat `status=incomplete`)
`error`	object	Info error (saat `status=failed`)
`usage`	object	Penggunaan token; lihat Objek respons bersama

Nilai status:

Nilai	Deskripsi
`completed`	Generasi selesai
`in_progress`	Generasi sedang berlangsung
`failed`	Generasi gagal
`incomplete`	Tidak lengkap karena batas token atau serupa

Nilai output[].type:

Nilai	Deskripsi
`message`	Pesan teks asisten
`function_call`	Panggilan fungsi/tool
`image_generation_call`	Panggilan generasi gambar
`web_search_call`	Panggilan pencarian web

Body respons (streaming)

HTTP 200, Content-Type: text/event-stream

data: {"type":"response.created","response":{"id":"resp_abc123","object":"response","status":"in_progress"}}

data: {"type":"response.output_text.delta","delta":"Quantum","output_index":0,"content_index":0}

data: {"type":"response.output_text.delta","delta":" computing","output_index":0,"content_index":0}

data: {"type":"response.completed","response":{"id":"resp_abc123","status":"completed","usage":{"input_tokens":15,"output_tokens":28,"total_tokens":43}}}

data: [DONE]

Field event streaming

Field	Tipe	Deskripsi
`type`	string	Jenis event; lihat tabel di bawah
`response`	object	Objek respons lengkap atau sebagian
`delta`	string	Teks inkremental
`output_index`	integer	Indeks item output
`content_index`	integer	Indeks blok konten
`item`	object	Item output yang ditambahkan/selesai
`item_id`	string	ID item output
`part`	object	Fragmen ringkasan reasoning

Nilai type umum:

Nilai	Deskripsi
`response.created`	Respons dibuat
`response.output_text.delta`	Delta teks
`response.output_item.added`	Item output ditambahkan
`response.output_item.done`	Item output selesai
`response.function_call_arguments.delta`	Delta argumen fungsi
`response.function_call_arguments.done`	Argumen fungsi selesai
`response.completed`	Respons selesai

API Model

Daftar model yang terlihat oleh API Key dan jenis endpoint yang didukung setiap model

API Gambar

Teks-ke-gambar dan gambar-ke-gambar/edit; secara sinkron mengembalikan URL gambar atau data Base64