通俗理解API：OpenAI API调用手册

第1章：理解API——程序之间的合约

1.1 API的定义

API的英文即Application Programming Interface首字母的缩写，直译过来的意思就是：程序之间的接口。不过，我更倾向于把API理解为，程序之间的合约。这样的理解有助于我们更深入地揭示API的本质。

1.2 程序之间的合约：一种现实世界的类比

为了更好地理解API是如何充当程序之间的合约，我们可以通过一个现实世界的例子来展示。

想象一下餐厅里的服务员和厨师。顾客通过菜单选择自己想吃的食物，服务员将订单传递给厨师。在这个过程中，菜单就充当了一种“合约”。

• 菜单（API）： 菜单上列出了所有可供选择的菜肴以及它们的价格。这就像是API提供了一系列可用的函数、方法和数据结构，让开发人员知道可以使用哪些操作和如何使用它们。
• 顾客（调用方）： 顾客选择菜单上的菜肴。这就像程序中的一部分（调用方）选择调用API的特定功能。
• 服务员（接口）： 服务员了解菜单上的内容，并将顾客的选择传递给厨师。这就像接口在调用方和被调用方之间传递信息。
• 厨师（被调用方）： 厨师根据服务员传递的信息准备食物。在软件中，这个阶段对应于API所代表的底层系统或服务执行特定操作。
• 准备食物（执行操作）： 厨师根据订单准备食物，并确保按照菜单的描述准备。同样地，API确保按照文档中的描述执行特定操作。
• 食物的交付（返回值）： 食物准备好后，服务员将其送到顾客的桌上。在软件中，执行操作后，API会返回特定的值或结果。

通过这个类比，我们可以清楚地看到API作为程序之间的合约的工作原理。它定义了如何请求特定操作，如何传递参数，如何执行操作，以及如何返回结果。只要遵循API的规则（菜单），各方都可以顺利协同工作。如果尝试执行不在API规定范围内的操作，就像点菜单上没有的食物，那么操作将无法进行。

第2章：OpenAI API概述

2.1 人工智能的普及和OpenAI的角色

随着人工智能的飞速发展，它已经不仅限于学术研究或大型企业的专利技术。从推荐系统到自动驾驶汽车，AI正在渗透到我们日常生活的方方面面。在这个背景下，OpenAI通过开发易用的API接口，让普通人也能轻松使用和开发自己的对话式人工智能。这不仅降低了入门门槛，还促进了AI技术的广泛传播和应用。

2.2 OpenAI调用流程简述

调用OpenAI的API流程相当直观和友好，以下是一般的流程概述：

OpenAI的API不仅强大而且灵活，无论是初学者还是经验丰富的开发者都能轻松上手。它打开了一个新的世界，让更多人能够探索和利用人工智能的潜力。随着技术和平台的不断完善和升级，未来有望看到更多由OpenAI API支持的创新应用和服务。

第3章：OpenAI API简单调用（以gpt-3.5-turbo为例）

本章将列举几种常用语言的调用

Linux终端

curl https://api.openai.com/v1/chat/completions 
  -H "Content-Type: application/json" 
  -H "Authorization: Bearer $OPENAI_API_KEY" 
  -d '{
     "model": "gpt-3.5-turbo",
     "messages": [{"role": "user", "content": "Say this is a test!"}],
     "temperature": 0.7
   }'

Node.js(JavaScript）

async function getdata(){
  const res = await fetch('https://api.openai.com/v1/chat/completions',{
    method:'POST',
    headers:{
      Authorization:'Bearer 你的apikey',
      "Content-Type":"application/json"
    },
    body:JSON.stringify({
      model:'gpt-3.5-turbo',
      messages:[
        {
          role:"user",
          content:"hello!"
        },
        {
          role:"user",
          content:"how are you?"
        }
      ]
    })
  })
  const data = await res.json();
  console.log(data);
}
getdata()

Python

import requests

url = 'http://172.178.89.163:3001/v1/chat/completions'

headers = {
    'Authorization': 'Bearer 你的apikey',
    'Content-Type': 'application/json'
}

data = {
    'model': 'gpt-3.5-turbo',
    'messages': [
        {'role': 'user', 'content': 'hello!'},
        {'role': 'user', 'content': 'how are you?'}
    ]
}

response = requests.post(url, headers=headers, json=data)
content = response.json().get('choices')[0].get('message').get('content')

print(content)

GO

package main

import (
        "bytes"
        "encoding/json"
        "fmt"
        "net/http"
)

func main() {
        url := "https://api.openai.com/v1/chat/completions"

        messages := []map[string]string{
                {"role": "user", "content": "hello!"},
                {"role": "user", "content": "how are you?"},
        }

        bodyMap := map[string]interface{}{
                "model":    "gpt-3.5-turbo",
                "messages": messages,
        }

        body, _ := json.Marshal(bodyMap)

        req, _ := http.NewRequest("POST", url, bytes.NewBuffer(body))
        req.Header.Add("Authorization", "Bearer 你的apikey")
        req.Header.Add("Content-Type", "application/json")

        resp, err := http.DefaultClient.Do(req)

        if err != nil {
                fmt.Println("Error:", err)
                return
        }

        defer resp.Body.Close()
        var result map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&result)
        fmt.Println(result)
}

第4章：OpenAI API调用手册

4.1调用方式

你可以通过任何编程语言的HTTP请求与API进行交互！

4.2身份验证

OpenAI API使用API密钥进行身份验证。所有API请求都要在Authorization HTTP头部中包括您的API密钥

Authorization: Bearer OPENAI_API_KEY

如何获取API Key：platform.openai.com/account/api…

4.3models列表

  使用接口管理工具，可以获取OpenAi的models列表，也可自行调用。

GET https://api.openai.com/v1/models

import requests

url = 'https://api.openai.com/v1/models'
headers = {
    'Authorization': 'Bearer 你的apikey'
}

response = requests.get(url, headers=headers)

print(response.json())

这里直接列举了OpenAI常用模型

4.4参数

聊天模型request and response

json格式请求与返回

{
  "model": "gpt-3.5-turbo-0613",
  "max_tokens": 1000,
  "stream": true,
  "n": 1,
  "temperature":1,
  "messages": [
    {
      "role": "system",
      "content": "你现在需要扮演喜羊羊，当我问到你是谁的时候，你回答你是喜羊羊！"
    },
    {
      "role": "user",
      "content": "你是谁？"
    },
    {
      "role": "assistant",
      "content": "我是喜羊羊！快乐又活泼的喜羊羊！"
    }
  ]
}

{
  "id": "chatcmpl-7me3fFf3j7X5qJucqBpPB7SkKjRHz",
  "object": "chat.completion",
  "created": 1691828083,
  "model": "gpt-3.5-turbo-0613",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "咩咩咩咩~大家快跑，灰太狼来了！我是喜羊羊，我们要小心！"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 101,
    "completion_tokens": 44,
    "total_tokens": 145
  }
}

4.5进阶用法

  如何使请求携带上下文？

  答：将整个聊天数组都发送，即实现上下文功能，但请求不能超过最大token。

  如何自定义请求功能？

  答：在消息数组中使用system或者user指定chat身份，通过prompt工程，使其拥有特定功能。

第5章：OpenAI API调用的坑坑绕绕

  请求不成功怎么办？

  答：国内网络无法请求api.openai.com，请自行解决。

  多次请求后失败？

答：免费用户一分钟只能发送三次请求。